Using a role mapping file to import default roles

By default, built-in roles (ADMIN, USER, DESIGNER, GRID_ADMIN, REPOSITORY_ADMIN) are not imported into BMC Atrium Single Sign-On and rules for built-in groups are not imported into the repository or the CDP.

This default behavior is intended to prevent the unintentional merging of authorization domains when migrating multiple BMC Atrium Orchestrator environments into a single BMC Atrium Single Sign-On environment. This behavior can be changed by providing a role mapping file specifying the group names to be used for import in place of the built-in roles.

The role mapping file is a Java Properties file supplied to the migration tool using the ‑‑roleMap option. This properties file alters the default import behavior for Access Manager built-in (and user-defined) roles.

Role map properties file functions

The content of the file is governed by the rules for a Java java.utils.Properties file read using the load( method. The file must be encoded using the default character encoding for the system (see ).  Each property entry is a key/value pair where the key is the built-in or user-defined role to which groups are mapped. The value is a comma-separated list of group names mapped to (or aliases of) the role identified by the key.

For example, GRID_ADMIN=BAO Admin, AoGridAdmin

In the example, you specify "BAO Admin" and "AoGridAdmin" as aliases for the built-in role GRID_ADMIN.  


Group names with embedded spaces are supported; leading and trailing whitespace is discarded. To use a user-defined role with an embedded space as a key, you must specify the embedded space with a backslash (\). Group names that contain an embedded comma are not supported.

Role and group names are not case-sensitive. Therefore, "GRID_ADMIN" and "gRiD_aDmIn" refer to the same role. The first appearance of a group name defines its case-preserved value used when adding the group to BMC Atrium Single Sign-On.  (The case-preserved value for user-defined and built-in role names are set in Access Manager.)

The role map properties file functions in the following manner:

  • During role/group import into BMC Atrium Single Sign-On, the groups mapped to a built-in or user-defined role are each added to BMC Atrium Single Sign-On.
  • The membership of any added or existing group is updated to include the members of the built-in or user-defined role to which the group is mapped. 
    For example, a mapping of GRID_ADMIN=AoRoot and REPOSITORY_ADMIN=AoRoot imports the AoRoot group into BMC Atrium Single Sign-On and assigns it members from both GRID_ADMIN and REPOSITORY_ADMIN.
  • During rule import into the repository or the CDP, rules written for a built-in or user-defined role for which a mapping is provided are imported as rules for the mapped group(s).
    For example, a mapping of USER=AuthenticatedUsers causes CDP process execution rules permitting USER rights to run workflows to be imported as rules for the group AuthenticatedUsers.

Related topic

Migration tool options

Was this page helpful? Yes No Submitting... Thank you