Generate roles from identity data
Role automation
Generate repeatable role structures from source data, preview the impact, and apply the result to the development role model.
Role generators use two filters: one determines which roles exist; the other determines the accounts assigned to each role. Applying a generator manually updates the development role model. A role-generator scheduler task can also apply the result to the active model. Target memberships change later when the active model is executed in a job.
At a glanceDirect link to At a glance
This example generates employee roles by location and links them to existing Active Directory groups. A location such as Oregon produces the role Oregon_Employees, linked to the group Oregon - Employees. A parameterized member filter selects the AD accounts for that location.
| Input | Purpose | Example name |
|---|---|---|
| Role generation filter | Supplies role names, source locations, and matching target groups. | RoleGen_Employee_Location_Groups |
| Role member filter | Returns the target accounts for the location passed by the generator. | Employees_AD_Users_P_Location_Members |
Use the same pattern for students, departments, titles, or another source attribute. Replace the example names, tables, and fields with those in your environment. In the member-filter name, P indicates that the filter uses a parameter.
Before you beginDirect link to Before you begin
- Confirm the source location data is available and source identities are related to their AD user accounts.
- Ensure the target groups already exist and are collected in NIM. Use mappings to provision missing groups; a role generator associates groups with roles.
- Have a development role model available. Edit the existing development model, or create one if none exists.
- Review the model's scope and safety guidelines. Do not manage the same group's membership through both mappings and roles.
Build a role generatorDirect link to Build a role generator
Create the role generation filterDirect link to Create the role generation filter
- Go to Processing > Filters and create a filter named
RoleGen_Employee_Location_Groups. - Start with the source table containing the location information. Include the source location column, such as
LocationName, so it is available to pass to the member filter later. - On Columns specification, select Add script column and name it
cf_RoleName. - Use the Table data pane to insert the location field into the JavaScript code, then append the user type. For the source tables shown in this example:
return data['Locations']['LocationName'] + '_Employees';
- Select Save and Close, then Filter. Confirm the generated role names, such as
Oregon_EmployeesandWashington_Employees, contain no spaces. Use underscores in role and generator names. - Add a second script column named
cf_GroupName. Return the exact name of the group in the target system:
return data['Locations']['LocationName'] + ' - Employees';
- Select Save and Close, then Filter again. Confirm
cf_GroupNamematches the existing group names, including spaces and punctuation. In this example,Oregon_Employeesis the role name andOregon - Employeesis the group name.
Add include and exclude group lookupsDirect link to Add include and exclude group lookups
On the role generation filter's Lookup tab, select Add to create these two lookups:
| Setting | Include lookup | Exclude lookup |
|---|---|---|
| Lookup name | AD_Include | AD_Exclude |
| Filter column | cf_GroupName | cf_GroupName |
| System | AD | AD |
| Table | Groups | Groups |
| Field | cn or sAMAccountName, whichever matches cf_GroupName | The same matching field |
| Operation | include | exclude |
Select Filter [AD_Include] to review rows whose groups exist in AD. Select Filter [AD_Exclude] to identify rows whose groups do not match. Resolve unexpected missing groups or naming differences before continuing. The generator will use the include lookup result.
Create a parameterized role member filterDirect link to Create a parameterized role member filter
- Copy an existing employee update filter that already relates source employees to their AD accounts, or create an equivalent filter. Name it
Employees_AD_Users_P_Location_Members. - Include the AD account's unique identifier, such as
objectGUID, and the source location used to select its members. - On Parameters, select Add parameter. Set Name to
p_location, Type to input, and Data type to string. Set a default value such asWashingtonto preview a specific location.
- Add an expression for the source location field. Set the operator to equals (ci), select the Constant/Parameter (
|x|) control, and choose value of parameter > p_location. - Select Save, then Filter. Confirm the results contain only the expected accounts for the default location and include their AD identifiers.
The default value is for previewing the filter. During role generation, NIM passes each source location through p_location to find the accounts for that role.
Connect the filters and group lookupDirect link to Connect the filters and group lookup
Go to Output > Roles > Role Generation, select Add, and name the generator Employee_Location. Use underscores instead of spaces.
Under Roles and members, configure:
| Setting | Example value |
|---|---|
| Role generation filter | RoleGen_Employee_Location_Groups[AD_Include] |
| Role name column | cf_RoleName |
| Role member filter | Employees_AD_Users_P_Location_Members |
| Member filter param name | p_location |
| Member filter param value | LocationName, the source location column from the role generation filter |
Pass the source location, such as Oregon, to the member filter. Keep it separate from the formatted role name (Oregon_Employees) and group name (Oregon - Employees).
Under Role groups, select Enabled for the AD row using the AD_Include lookup. Confirm the Member filter column is the target account identifier, such as objectGUID, then select Save.
Review the impact and generate development rolesDirect link to Review the impact and generate development roles
- Use Calculate on the Members, Groups, and Roles tabs to review the generated relationships.
- Open Run and select Calculate to preview the operations in Impact analysis.
- Review the Execution options: Create roles, Update roles - add groups, Update roles - delete groups, and Delete roles. Enable only the operations you intend to apply, and review any proposed removals.
- Save the generator, then select Apply generator to apply the reviewed changes to the development role model. Review Impact analysis for the resulting operations.
- Return to Output > Roles and select Edit Role Model for the development model. Confirm the generated roles, their groups, and their members. Use Group Membership Reports to review pending membership actions before activation.
Applying a role generator manually updates the development role model only. It does not write changes to target systems. A scheduled role-generator task has separate development and active model options.
Activate and automate the role modelDirect link to Activate and automate the role model
After reviewing the development model, go to Output > Roles and select Activate Development Role Model (the orange play button), then confirm. Activation makes the model available to the next job that processes it.
The job must include a groupmembership operation for the target system. On its next execution, NIM processes the active model and adds or removes memberships according to the role filters and configured scope. See Use roles in jobs.
To maintain generated roles and their group assignments as locations are added or removed, configure a role-generator scheduler task. Choose whether it updates the development model, the active model, or both, and set guard limits before enabling recurring execution. Membership changes still require the job's groupmembership operation.
Edit or remove a generatorDirect link to Edit or remove a generator
Select Edit Role Generator to adjust the filters or settings. Select Remove Role Generator and confirm to delete one that is no longer needed. For a complete worked example, see the Role model tutorial.