Set Up Dynamic Security Using Security Files

Assign users permissions based on a defined security attribute.

Overview

You can assign security permissions to users with a data file sent to Visier. This approach allows dynamic security updates with each data load, minimizing the need for ongoing maintenance.

The initial security file assigns permissions to existing users, and you can modify permission assignments by sending an updated file. Any changes to an existing file requires a new data version, which may cause a brief delay in data access while the updates process.

Additional security measures are needed when a user needs access to an organization outside their hierarchy, or the organization doesn’t roll up to them. You can use security files to dynamically assign permissions when:

• A user needs access to an organization they don’t sit in. For example, an HR Business Partner needs access to R&D.
• A user needs access to multiple organizations. For example, an HR Business Partner needs access to R&D and IT.
• Multiple users require access to one organization. For example, if multiple HRBPs need to support the same R&D organization.

Set up dynamic security files

There are multiple ways to load security files into Visier. Security data files are loaded alongside source files, not existing analytic objects. For example, in the case of a Requisition you do not load the security file in the existing Requisition, the security file is a separate file that you load along with Requisition. For more information, see Data In.

Map a user to a file

User IDs can be dynamically mapped to Subject IDs using a security file. Each subject ID used by an analytic object can be associated with an array of User IDs. Analytic objects include Requisition (RequisitionID), Applicant (ApplicantID), and Employee (EmployeeID). For access control in the file, each User ID must appear on all Subject ID records where the user is permitted access. Always send a full restatement of this security file, as previous files will be ignored. To map a user to a subject member you will need:

• Source file to provide the members mappings.
• A mapping to populate the security data file.
• Permissions that leverage the relevant security data file.

Creating a source file

For example, using the Employee analytic object the file must contain the following columns:

• EmployeeID: The ID of the subject member being granted access.
• UserEmployeeIDs: The list of Employee IDs that will have access to the subject member.

Create a mapping

Each subject has a corresponding UserSubjectMemberAccess_Subject object that can be mapped to as a target. The Subject in the mapping name will be replaced with the subject to be given access. For example, for a Requisition object it would be UserSubjectMemberAccess_Requisition. For an Employee object it would be UserSubjectMemberAccess_Employee. For more information, see Add a Mapping.

Your mapping will require the following properties:

• EventDate mapped to tenantStartDate. This ensures the security will apply to the subject irrespective of time.
• SubjectID mapped to the correct subject. For example, Requisition or Employee. You can map this manually, but if your file is correctly formatted, it will map automatically.
• UserEmployeeIDs will be mapped from your file. You can map this manually, but if your file is correctly formatted, it will map automatically.

Apply a permission

The security data file that you’ve loaded can be accessed via the Dynamic Filter option when defining population access:

1. In a project, click Security > Permissions.
2. In the Data Security tab, select your UserSubjectMemberAccess source.
3. Click under Population Access.
4. Click Custom.
5. Expand Dynamic Filter and select Data to data file.
6. Click Apply.

Users will be granted permission to only the data stipulated in the original security file.

Map a population using a security file

After loading your source data into Visier, you must add a property to dimensions identified in the file. The property's object name must end in _List to load data properly.

Prerequisites

A parent-child dimension in the data is required to dynamically assign security. If no dimension exists, create a new parent-child dimension. For more information, see Create a Parent-Child Dimension. After you select or create a parent-child dimension, you need the following files to assign security permissions:

• Population file: Sets the population access in the dynamic permission or assigns a permission to a user.
• User Group Matrix file: Defines the user group to receive the dynamic permission. This file is not required when the information to identify the user group membership already exists on the employee. For more information, see User Group Matrix file.

To grant a permission, the EmployeeID must be in both the Population file and the User Group Matrix file. The files you send to Visier must be pipe delimited and in UTF-8 format. For more information, see Data File Guidelines.

Population file

The Population file must contain the following columns:

• Hierarchy: The parent-child dimension you will assign access via a permission. The Hierarchy column delineates between nodes with the same ID that belong to different parent-child dimensions. This could be one value when providing access to one dimension, or multiple values for several different dimensions. For example, Organization, Supervisory, and Company dimensions could all exist in this column.
• Node: A representation of the reference key of the parent-child dimension in your data source. For example, one supervisory parent-child dimension referenced in the data as SUP1.2. While another supervisory parent-child dimension has the reference key SUP1.9.
• User group columns: A column for each unique user group requiring access to the node. At least one column indicating a group is required to set population access. For example, one column could represent HRBP and another could represent HRBP Analyst. For several different items in the same cell, separate the items with a comma and white space. For example, employee ID numbers 123, 124, 125 can all exist in the same cell under HRBP. This formatting is necessary to properly load different data formats. After loading your data into Visier you will create an extraction rule to remove white space so you are left with a comma-separated list to map to your data source.

The following Population file example assigns dynamic security for HRBP and HRBP Analyst permissions.

• Employee 123 in their HRBP is allowed to see nodes SUP1.2 and SUP1.9 of the Supervisory dimension.
• Employee 123 in the HRBP Analyst is allowed to see node ORG1.1 of the Organization dimension.
• Employee 125 as an HRBP is only allowed to see node SUP1.2 of the Supervisory dimension.

Create a parent-child dimension:

1. In a project, on the navigation bar click Model > Dimensions.
2. Select the dimension related to the population file.
3. In the dimension, click Customize > Add custom property.
4. In Customize, under Custom properties, click Add Custom Property.
5. Enter a display name with the _List suffix in the parent-child dimension. For example, Organization_Access_List.
6. In the Data type list, select Text.
7. Click Add.

Create a lookup mapping:

1. In a project, on the navigation bar, click Data > Mappings > Create Mapping.
2. Enter a display name that uses the Security Definition - prefix to notify other users that these files are used to define security. For example, Security Definition - Organization Hierarchy Lookup.
3. Add the description To set up dynamic security by file.
4. In Mapping type, select Lookup.
5. Select the source containing your data in the Population file.
6. Expand Target group and select the group included in the mapping.
7. In Data file type select Temporal.
8. Click Override behavior > Event date.
9. Click Create.

Map your properties:

1. Click MappingKey > Map from a column, and then select a key value from your source, for example EmployeeID.
2. Click EventDate > Map from a column.
3. Select the nodes to include in the mapping.
4. Create an intermediate property by clicking Add Intermediate Property.
5. In your new property, click Map from formula.
6. Enter an extraction rule to remove white space so you are left with a comma-separated list. The following example removes white space from the HRBP column.

1
stringSubstitute(column("HRBP"), " ", "")

The property has been successfully mapped to your data source. Next, create a business rule on the parent-child dimension to lookup the access list and assign it to the file with the _List object created above.

1. In a project, on the navigation bar, click Data > Rules > Business Rules > Create Rule.
2. Click Rule type > Business rule.
3. Click Display name and use the Security Definition pre-fix to clarify the purpose of the file. For example Security Definition - Americanization Hierarchy Lookup.
4. Click Subject and select your chosen parent-child dimension.
5. Add the description to set up dynamic security by file.
6. Enter a formula to lookup the access list and assign it to the _List object. For more information, see Business Rules. An example using the augmentedMapping rule is shown below.
7. Click Create.

1
2
3
4
5
augmentingMapping(
    mappingName, 
    mappingKey, 
    mappedProperties [,ifUnmapped, filter, ifOutputExists, ignoreIfNoValue]
)

If your dynamic security requires a User Group Matrix file to define your user groups, you must load the information to the analytic model. The information from this file is loaded as leveled dimensions and auxiliary mappings on the Employee subject. For more information, see Create a Leveled Dimension and Add a Mapping.

Generate a data version by running a job. This will allow you to preview the new mappings made to check they are correct. For more information, see Run a Job.

Configure security

Once you generate a data version you must configure the population access security. Begin by creating a new permission:

1. In a project, on the navigation bar, click Security > Permissions.
2. In the Permissions room, click Add Permission.
3. In the New Permission dialog, add a display name and description for the permission and then click Create.
4. Select the items you want to grant access to:
   1. In the Data security tab, click Add access.
   2. In the Select the data dialog, select the items and then click Finish. For more information, see Add Access to Items.
5. Click the Population Access value of your subject from the list and select Custom.
6. Expand Dynamic Filter > User to dimension.
7. Select your parent-child dimension. For example, Organization Hierarchy.
8. Expand the name of your Organization_Security_Organization_Access_List > Employee ID. Leave the other fields in their default settings, as once a setting is selected the default value is no longer available.
9. Click Apply.

User Group Matrix file

This file is optional when user group information already exists on the Employee subject. If user group information is not available through the Employee subject, provide the following columns to assign user groups to a permission:

• EmployeeID: A unique identifier for each employee.
• Designation Columns: A single column, or several columns, designating the identification of the employee belonging to that user group. Use either 1 meaning yes, or 0 meaning no to flag this designation.

The following User Group Matrix file example assigns employees to the user groups HRBP and HRBP Analyst:

• Employee 123 belongs to user groups HRBP and HRBP Analyst.
• Employee 125 belongs to user group HRBP.
• Employees 124 and 126 do not belong to either HRBP or HRBP Analyst.

Next, define the user group that will receive the dynamic permission via a security file. If needed, create a new user group. For more information, see Create a User Group.

1. In a project, on the navigation bar, click Security > User Groups.
2. Click to select the user group that will receive the dynamic permission.
3. In the Users tab, click Edit beside Dynamic Users.
4. Select the dimensions needed to define the user group. This step will incorporate the dimensions listed in the User Group Matrix file. Be sure to include all dimensions needed for all users provisioned in the permission.
5. Select the new attribute to assign the filter. Using the example User Group Matrix file above, the attributes would match the column headings (HRBP and HRBP Analyst).
6. Select the security value of the attribute. As seen in the example User Group Matrix file, select a value of 1 to include the security value in the filter.
7. Click Apply.
8. In the Permissions tab, turn on the Enabled toggle for the user group permission.

Only users defined in the User Group Matrix file are dynamically assigned security by the User Group. After successfully configuring the security of your permission you can preview your data version to confirm that the changes are successful. For more information, see Preview a Data Version.