Skip to main content



Use roles to bulk assign user accounts to groups in target systems.

To get started, follow the example in the Role Model tutorial.

The purpose of roles is to manage security and entitlements in a controlled, simplified way. For example, in your organization you might have 10,000+ separate entitlements (application access, software licenses, accounts, file shares, permissions, etc) which are assignable to employees by means of group memberships in your target systems. A role consolidates multiple groups into a single object in NIM, so you can grant membership to all of them simultaneously. For this reason, the number of roles you create in NIM is always significantly fewer than the number of total groups in your target systems. To say it again, the purpose of roles is to simplify entitlement grants via group assignments.

Each role comprises three parts:

  1. Name of the role

  2. User groups in one or more target systems

  3. User accounts in those target systems to be assigned as members of the groups

All roles exist inside Role models. Typically, you'll build up your role model in phases. This may include generating roles in bulk with Role generators, Role mining, and/or manually creating/editing one-off roles.

The way you design your role model is up to you. Many organizations use a simple 1:1 correspondence of roles to departments, and the intermediate tutorial follows this example. Another common design is one role per combination of variables. For example, in K-12 school settings, one role per combination of grades, classes, and buildings. These designs can be implemented with the help of a role generator.

Roles are executed via groupmembership-type operations in Jobs.


The assignment of entitlements to user groups takes place in the target systems, not in NIM. The roles feature in NIM is strictly about managing the memberships of those groups. Entitlements are granted to users indirectly, through their group memberships.

Mappings vs. roles

It's important to understand that NIM provides two different ways to manage groups and group memberships in target systems:

  1. Mappings: Create/update/delete groups, and in some target systems, create/update/delete group memberships

  2. Roles: Manage group memberships in existing groups

In general, the recommended workflow is to use mappings to dynamically create/update/delete groups based on data in your HR system (e.g., departments), and then roles to manage the memberships in those groups.

What you must not do is attempt to manage memberships in a single group using both mappings and roles simultaneously. This is because when a group has been added to a role, NIM now manages that group on an all-or-nothing basis. Any user accounts assigned to the group by means other than a NIM role are removed. This includes accounts assigned to the group via the system's own administration portal. It also includes any groups and/or memberships created with NIM's mapping functions. This removal process is repeated every time the role is executed.

This also means that for any & all groups that NIM will manage, you must:

  • Configure the role's filter to include all necessary users.

  • No longer manage the group's memberships by any other means than NIM roles.

If you use membership mappings, they are best used sparingly, e.g., to manage memberships for <5 users and <5 groups. For managing a non-trivial number of group memberships, roles are far more efficient.


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