User maps and user matching

This topic describes how to create user maps and apply user matching.

About user maps and user matching

Use user maps and user matching allow you to synchronize user fields. User maps describe how a user is identified in all your data sources. These maps define users that have different user names across multiple Data sources. User maps allow you to map these two users together so that the synchronization knows that they are the same user.

User matching finds a user representation across two products and indicates that a user in System 1 is the same one in System 2.

The following are some common user representations:

  • Jira DisplayName
  • Octane email, full_name or name
  • ALM/QC loginname
  • Azure DevOps DisplayName

If both products use the same user representation, you do not need to use user maps. If, however, the user representation is inconsistent, you must define user maps.

You can define user maps:

You can manually construct the maps through the user interface. For example, when mapping between ALM Octane and Jira, you can map the Jira assignee field to the ALM Octane owner field. For details, see User maps and user matching.

Back to top

Define user maps in the dashboard

Each user map defines one user's identity across your different data sources.

To define a user map:

  1. On the top banner, select the User Maps tab.
  2. Click Add User Map. A User Map entry is added to the grid. In this User Map, you specify a single user's various identities across the different data sources.

  3. Double-click the User Map placeholder text, and rename the User Map. The user map name is only used internally.

  4. Add rows to the user map.
  5. On each row, select a data source, and enter the user's name as it's defined in the data source.
  6. Repeat the above steps to create Data maps for all the users in your data sources.
  7. Click Save.

Back to top

Import user maps

You can import user maps through a structured XML file.

To create a template of the XML file, you export users directly from the endpoint system and import them into the Connect database using the Batch utility scripts.Alternatively, define a user map and export it. For details, see Automatic user mapping.

To import User maps:

  1. Create one or two User maps in the UI. For details, see Define user maps in the dashboard.

  2. Export the User maps:

    1. In the top banner, click the gear button, and select Export.
    2. In the Export Connect Data dialog box, select the Users tab.
    3. Select the User Maps you want to export, and click Export.

  3. Open the exported file.

    The following example shows a typical user map record:

    <UserMap>
   <name>User Map2</name>
   <User>
      <type>DataSource</type>
      <value>Jira DataSource</value>
      <name>Example Jira TeamDev</name>
   </User>
   <User>
      <type>DataSource</type>
      <value>Octane DataSource</value>
      <name>example.octteamdev@localhost</name>
   </User>
</UserMap>

  4. Repeat the above structure in the XML file to define a User map for each user.

    Element Comments 
    <UserMap>
   <name>
    		 The user map name. An internal label identifying the user for whom you are creating the user map. The name should be unique. 
    <User>
   <name>

    The user's name as found in the Data Source <value>.

    You are allowed to specify multiple names for the same user within the same Data Source.

    Caution: Do not change any of the data outside of the <UserMaps> block. This information is necessary to allow you to re-import the file.

  5. After completing all the user maps, save the file with an .xml extension.

  6. Import the XML file:

    1. In the top banner, click the gear button, and select Import.
    2. Select your modified XML file.
    3. Click Import.

Back to top

Enable user maps

After you create user maps, you need to associate them with user fields inside your connections.

To enable user maps:

  1. Select the Connections tab.
  2. Click the gear alongside a Connection and select Edit.
  3. In the Update Connection dialog box, click Next to go to the Types and Fields tab.
  4. Select a type and click (Edit).
  5. For each user field in the list, select the Enable User Map column.

Back to top

Fallback users

You can configure fallback users to use during synchronization, in cases where there is no user mapping.

For example, consider a case where a Jira Story is synchronized with ALM Octane and the Jira Story has Jane Doe as the Author. If there is no matching user in ALM Octane and no relevant user mapping, then a user story wil be created in ALM Octane with the Author set to the fallback user.

This can also be useful if you do not want to create a full set of user accounts in the products being synchronized.

Fallback users can be configured to be specific or general. For example, you can designate fallback user Bob for a specific project mapping, type, and field. Alternatively, you can designate fallback user Bob for all project mappings, type mappings, and field mappings.

To set the fallback users:

  1. In the Connection wizard, go to the User Configuration page.

  2. To set a fallback user for all type and field mappings, expand the Target Fallback User or Master Fallback User dropdowns in the Project Fallback Users area, and select a user.

  3. To set a fallback user for specific types and fields:

    1. In the Type and Field Fallback Users area, click +Fallback User. The Create Fallback User dialog opens.

    2. Select Target or Master.

    3. Choose a project, type, field, and user and click OK. The Fallback mechanism is applied to the most specific user. If you specify a user for a particular type, it overrides the general designation set in the upper pane.

    4. Repeat as required for each target or master.

Note: The Fallback mechanism is currently supported for the ALM/QC, ALM Octane, and Jira connectors. Version 24.2 also supports the Azure DevOps and ServiceNow connectors.

Back to top

Next steps: