Skip to main content


Provision groups & manage memberships

This article demonstrates how to dynamically provision target groups via Mappings and manage their memberships via Roles. For more information, see Group management.

This example is based on the following scenario:

  • NIM roles will be used to manage group memberships in an Active Directory target system

  • The groups in the AD target system correspond 1:1 to departments in the organization

  • The only group membership that employees require for their AD accounts is membership in their department's group

This is a very simple use case for NIM roles: each role corresponds to one department, and contains only one target group which also corresponds to that department. In more complex environments, roles typically contain multiple groups, and may be based on source data other than departments (e.g., job titles, project assignments, etc). However, this is a good example to start with.

We'll use the HR500 test dataset as our source system and an Active Directory system as our target system.

  1. Create a role model to start with a fresh Development role model.

  2. Create a filter that returns departments from the source system.

    We'll feed this filter into a group create mapping, to dynamically provision groups into our AD target system. Any time a new department is added to the source system, NIM will detect it and create a corresponding target group in AD.

    For this example:

    1. Add the source table which contains the column based on which groups should be created.

      For this example, the table is hr500.departments, and the column is organizational_unit.

    2. Optional: If the naming scheme of departments in the HR source system is different than the desired naming scheme of groups in the target system, a transformation is required.

      For this example, we want to prefix department names with DEPGRP_. For example, the HR department EN_DOC should correspond to the target AD group DEPGRP_EN_DOC.

      1. Create a JavaScript filter column.

        For this example, we'll use the following JavaScript: return 'DEPGRP_'+departments['organizational_unit'].

        We'll name the transformed column dep_grp_name.

    3. Create both Include and Exclude lookups for the transformed column, by following the example in Create a lookup.

      The exclude lookup will be used in a group create mapping function to dynamically create groups that don't already exist, and the include lookup will be used in a role generator to assign the created groups to generated roles.

  3. Create a mapping for the target system, for its group create function.

    For this example:

    1. For the mapping's Filter, select the Exclude version of the filter created in step (2).

      We feed the exclude lookup into the group create mapping because it returns the groups that don't already exist in the target system, i.e., the groups that need to be created.

  4. Optional: Create group update and/or delete mappings if you want to handle update and/or delete actions, in addition to the group create mapping you just created.

  5. Create a job for the group-related mapping(s) created in step (3).

    For this example:

    1. Add the group create mapping to the job.

      For this example:

    2. Optional:: Additionally add any group update and/or delete mappings you created to the job.

    3. Evaluate and execute a job for this job, to initially provision groups into the target system.

  6. Create a filter to feed into a role generator as its Role Member Filter.

    For this example:

    1. Set up the filter according to the requirements of the Role Member Filter.

      For this example, we'll relate the hr500.employees table to the ad.Users table. We'll make sure to include AD's user objectGUID column.

    2. Specify an expression item parameter for the source system column on which your roles are based. This parameter becomes the Member Filter Param Name in your role generator.

      For this example, we'll parameterize the organizational_unit column of the hr500.departments table. This lets us filter employees by department, since our roles correspond 1:1 to our departments.

    3. Optional: You may need to Exclude rows by duplicate value to exclude duplicate target accounts.

      For example:

  7. Create a role generator.

    For this example:

    1. For the Role Generation Filter, select the filter created in step (2).

      For this example, it is our departments filter.

    2. For the Role Name Column, select the specific column of the Role Generation Filter which contains the names of the roles to be generated.

      For this example, it is the organizational_unit column of the departments filter.

    3. For the Role Member Filter, select the filter created in step (6).

      For this example, it is our departmentAccounts filter.

    4. For the Member Filter Param Value, select the column whose rows should be iterated through the Member Filter Param Name to find the target accounts for each role.

      For this example, it is the organizational_unit column of the departments filter.

    5. The Role groups pane is automatically populated with the include lookup from the Role Generation Filter. Select the Enabled checkbox for the entry. This places existing groups into their corresponding roles.



      An additional way to place groups in roles is Role mining. It is not necessary in this example, but may be useful in more complex production scenarios.

    6. Go to the Run tab.

    7. Optional: Adjust the Execution Options.

    8. Click Calculate to preview all operations that will be performed.

    9. Click Save.

    10. Click Apply Generator to execute the role generator.

      The development role model has been populated with the generated roles.

  8. Create a job.

    For this example:

    1. Add a groupmembership job item for the relevant target system(s).

      For this example, it's just our AD system.

    2. Optional: Inspect pending group memberships to preview all pending role model operations.

    3. Activate the development role model.

    4. Evaluate and execute a job for this job, to initially execute the role model you've created.

    5. Optional: Inspect active group memberships to see the results of the execution.

  9. Optional: Create a sync task (or multiple sync tasks) containing the jobs created in steps (5) and/or (8), to run them on a regular basis.


    Role generators cannot yet be applied in jobs, or scheduled in sync tasks. You must apply them manually with the Apply Generator button on the Run tab.

    This functionality is under development. When it is released, it will be possible to automate the entire Provision groups & manage memberships process.