Use roles to add user accounts to groups in target systems.

To get started, Create a role.

Each role comprises two things:

  1. User groups in one or more target systems

  2. User accounts which should be assigned membership in those groups

The users in each role are supplied by a filter, which you should create prior to creating the role. See Filters. The filter must include users' unique identifiers for the source system and any target systems involved in the role. You can accomplish this using Relation items. Often, you can reuse a single filter for multiple roles by parameterizing it. See Parameters .

The set of all roles that exists in your NIM environment is called the role matrix. You can design your role matrix any way you want. However, for hierarchically-structured organizations, it's typically best to design it with one role per department and/or job title. Thus:

  • The highest level role corresponds to the entire organization;

  • Middle level roles correspond to individual business units or departments;

  • And the lowest level roles correspond to individual job titles.

Then, by supplying each role with the same parameterized, recursive filter, all users are automatically placed into the correct roles, all the way up the hierarchy. See Recursion.

Roles are executed via Jobs, at which time all user accounts in the role are added to all groups in the role.

Like all other aspects of NIM, roles are soll-ist based. Use the Inspect roles tool to evaluate the current ist and soll.


After a group has been added to at least one role, NIM now manages that group. It does so on an all-or-nothing basis. Every time NIM operates on a managed group, it removes all user accounts not specified in NIM's role model.

This includes any accounts previously added to the group on an ad-hoc basis, e.g., by an administrator via the system's own administration portal. It also includes any groups and/or memberships created with NIM's mapping functions.

Thus, for each target group, you must decide whether NIM will manage it via the role model or not. For groups which NIM will manage, you must:

  • Configure any relevant filters to include all necessary users.

  • No longer manage the group's memberships by other means except NIM.

For Active Directory target systems in particular, you should avoid having NIM manage built-in groups such as Administrators, Backup Operators, Domain Admins, etc.

Roles vs. mappings for group management

NIM provides two different ways to manage groups and group memberships in target systems:

Group create/delete mapping functions are useful for creating groups on the fly, via NIM. In contrast, you should use roles when the relevant groups already exist, and you are only managing their memberships. This is the difference between dynamic and static groups.

You should only use membership create/delete mapping functions sparingly, when absolutely necessary. Roles are far more efficient.


Do not attempt to manage memberships in a single group using both mappings and roles simultaneously. This causes conflicts and provisioning errors.