Automatic user mapping

This topic describes how to automatically map users between data sources.

In this topic:

Automatically generate user maps

When you synchronize data sources, you must also synchronize the users defined in the data sources. The same user may be defined differently in each data source. To handle this, you define user maps.

If you have a small number of users in each system, you may be able to defined the user maps manually. For a large amount of users, you can use utilities that automate the user mapping process.

To automatically create user maps:

1. Extract user data tables from the data sources.

   The extraction utility supports the following data sources: ALM Octane, ALM/QC, Jira, Azure DevOps, Rally, VersionOne, ServiceNow.

   If you connect to your data sources using proxy servers, define the proxy details in property bag files.

2. In the extracted user data tables, identify key and identifier columns for each data source.

3. Repeat the user data extraction, this time specifying only the key and identifier columns from each data source.

   You specify the key and identifier columns in the property bag files.

4. Run the UserMaps script to create and import user maps from the user data tables. For details, see Batch utility scripts.

Back to top

Extract user data tables from data sources

You use the DataSourceUsers utility to extract user data tables from the data sources.

The utility extracts the user information in the data sources.

To extract the user data: In Windows, right click the mfcDataSourceUsers.bat file and run as administrator.

The files are saved in the <Connect_installdir>\UserMaps folder.

The script runs without stopping the Connect server.

Include or exclude data sources

Follow these steps to include or exclude specific data sources from the data extraction process.

1. Create a file called datasourceusers.property.bag.txt in the <Connect_installdir>\UserMaps folder.

2. Add one line for each data source that you want to exclude, making sure to use the exact name with case sensitivity:
{name of data source}=-datasourcename

3. Add one line for each data source that you want to include, making sure to use the exact name with case sensitivity:
   {name of data source}=+datasourcename

   Note: You cannot use both +datasourcename and -datasourcename in the property bag.

   • If you exclude specific data sources using -datasourcename, all other data sources are included.

   • If you include specific data sources using +datasourcename, all other data sources are excluded.

4. To track, audit, or analyze the REST executing commands, add one or more of the following arguments:

   Argument	Description
   restheaders=true	Returns all the headers sent and received to and from the program and endpoint system.
   resturls=true	Returns the fully qualified URLs sent to the endpoint systems.
   rawdata=true	Returns all of the JSON data returned by the endpoint system for each REST URL.

5. Save and close the file.

Specify proxy servers

If you connect to your data sources using proxy servers, you need to specify the proxy details in the property bag files. This is only required if the endpoint requires a proxy. You can specify the proxy information in the individual property bags files, or once globally.

To specify proxies in individual property bag files:

1. Create a text file using the following naming convention: <datasourcename>.property.bag.txt where

   <datasourcename> needs to exactly match an existing data source name.

2. In the file, define the proxy parameters for Tomcat. For details, see Proxy setup.

3. Save the property bag file in <Connect_installdir>\UserMaps.
4. Run the mfcDataSourceUsers utility. For details, see DataSourceUsers and UserMaps scripts.

To specify global proxy information:

1. Create a text file using the following naming convention: datasourceusers.property.bag.txt.

2. In the file, define the proxy parameters for Tomcat. For details, see Proxy setup.

3. Save the file in <Connect_installdir>\UserMaps.
4. Run the mfcDataSourceUsers utility. For details, see DataSourceUsers and UserMaps scripts.

Back to top

Specify Key and Identifier columns

This section describes how to specify Key and Identifier columns for each data source. This is necessary, because data sources may include user information which is not necessary for the user mapping.

For the user mapping, you need to identify two fields in each data source: a key and an identifier.

• The key is a user field that has a common value for a given user across all data sources.
• The identifier is the field that contains the label (example: name or email address) by which the user is known in the data source. For example, in ALM Octane, users can be identified by their email addresses, full name or log in name. In Jira, users are identified by their display name.

In some cases, the key and identifier in a data source may be the same field.

To instruct the utility to extract only the key and identifier fields, create a property bag for each data source that specifies the relevant columns.

To specify key and identifier columns for data sources:

1. Create a property bag file for each data source. For details, refer to the previous section.

2. In the file, add the following parameter to the property bag file: columns=key,identifier where

   key and identifier must exactly match the names from the headers. A header name may be repeated twice.

3. Extract the user keys and identifiers from the data sources: Right click the mfcDataSourceUsers.bat file and run as administrator.

   The user data files are saved in <Connect_installdir>\UserMaps

To specify whether to extract all users or a subset:

1. Create a property bag file for each data source. For details, refer to the above sections.

2. In the file, add the allusers property and set it to true: allusers=true.

   • If set to true, all users are extracted from the endpoint server instance.
   • If set to false, or if it is not listed in the file, only those users who actively participate in the project are extracted.

3. Optionally, for Jira data sources add these properties to the property bags:

   Property	Meaning	Requirement
   alwaysauthenticate	Sends basic authentication credentials with each REST request, even those that are not required by the Connect Jira data source.
   groups	Extracts additional users of the specified groups, with their projects. Use a comma as a delimiter between multiple group names.	allusers must not be set to true
   projectusers	Extracts additional users from all project-specific issues.	allusers and roles must not be set to true
   roles	Extracts additional users of all roles in their respective project contexts.	allusers must not be set to true
   tablescan	Allows all Jira users, even if their emails are not unique. The default value, false, only allows users with a unique email address.

4. For LDAP enabled environments, add these LDAP-specific properties, if you want to link data source user extracts to LDAP attributes:

   java.naming.provider.url=

   java.naming.security.principal=

   java.naming.security.credentials=

   basedomain=

   java.naming.security.protocol=

   java.naming.security.authentication=

   The first four attributes are required. The protocol and authentication attributes are optional. For assistance, open a support ticket or see the JAVA API documentation.

Back to top

Create and import user maps

The UsersMaps script does the following:

1. Identifies matching users in the data files, based on their identical key values.

2. Creates a user map for each user with its various identities.

   Note: In the Jira environment, user uniqueness is based solely on the email address, regardless of which user field was selected. If multiple users have the same email address in an endpoint system, the first enabled user is used.

3. Imports the user maps to Connect.

For details, see Batch utility scripts.

To create and import user maps:

1. Open the mfcUserMaps.bat file and edit the following line:

   "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "|" {"incremental" | "pairs" | "orphans" | "removeall"} "%UTILITIES_PATH%\Jira" "%UTILITIES_PATH%\Oct1"

   The following table explains the command's arguments:

   Argument	Details
   {"incremental" | "pairs" | "orphans" | "removeall"}	"incremental", "pairs", "orphans" and "removeall" are all optional and mutually exclusive. incremental. Takes any set of data source maps, with any subset of users, and import them in the context of the existing user map in the database. pairs. Imports pair user maps. For details, see Pairs and orphans. orphans. Imports orphan user maps. For details, see The 'orphans' argument. removeall. Empties the database of all user maps. If no argument is provided, the script removes all the existing user maps and replaces them with the newly generated ones.
   "%UTILITIES_PATH%\{DataSourceName}"	The paths and file names of the user data files. The data files are generated by the mfcDataSourceUsers utility. List all the data files that you want to include in the user maps. The file names must match the data source names precisely as they are defined in Connect. For details, see Create a data source.

2. Right click mfcUserMaps.bat and run as administrator.

3. Re-export data source users on a periodic basis and re-import the user maps into Connect to stay up to date with changes made to the LDAP/Active Directory systems. This allows Connect to be current with new added users, user name corrections, and users that left the organization.

Back to top

Pairs and orphans

This section describes the usage of the 'pairs' and 'orphans' arguments for creating and importing user maps. For details, see Create and import user maps.

The 'pairs' argument

The pairs argument imports pair user maps. This argument takes a pair of user map files, where each member of the pair is equivalent to a connection running across the two data sources. When using this option, the script only imports those users with matching keys in both user map files. As a result, there will be no ‘orphan’ user maps in the Connect database, with a user representation from one product and not the other. For a sample scenario, see Pairs and orphans example.

To import the user maps, use the following syntax:

The 'orphans' argument

The orphan argument imports orphan user maps. This argument takes a pair of user map files, where each member of the pair is the equivalent to a connection running across the two data sources.

When using this option, the script only imports users with no matching keys in either of the user map files. As a result, there will only be orphan user maps in the database, with a user representation from one product, and not the other.

To import orphan user maps, you must append both sets of DATASOURCENAME=userrepresentation to the end of the command. As a result, the synchronization assigns a default user representation to the missing key-value pairs on the 'other' data source. This prevents synchronizations from breaking, for artifacts last modified by a user who may have been deactivated in the product endpoints. You must specify both default user representations, in order to import the orphan user maps. To import the user maps, use the following syntax:

Pairs and orphans example

This example has Jira and ALM Octane data source user accounts named ConnectJira and ConnectOctane.

In ALM Octane, the account has two real users, John Smith and Bob White. In Jira, the account also has two real users, John Smith and Ted Brown.

The following table shows the entries in the user map for each of the cases.

Argument	Entries in user map for 'pairs'	Entries in user map for 'orphans'
No default representation pairs	John Smith=John Smith	-
Representation only on ALM Octane side	John Smith=John Smith Bob White= ConnectOctane	-
Representation only on Jira side	John Smith=John Smith Ted Brown = ConnectJira	-
Representation on both sides	John Smith=John Smith Bob White= ConnectOctane Ted Brown = ConnectJira	Bob White= ConnectOctane Ted Brown = ConnectJira

Back to top

User mapping exceptions

In Jira and ALM Octane, users are generally created through LDAP integration. As a result, the same users exist on both sides of the connection. However, there may be additional users that do not use LDAP. These users exist in only one of the systems. This section describes how to create user maps for the non-LDAP users, using the UserMap script from the DataSourceUsers and UserMaps scripts.

To map non-LDAP users:

1. Go to the <Connect_installdir>\UserMaps folder.

2. Create a text file with no extension with the following name: <DataSourceName1>=<DataSourceName2>. For example, to map between the following data sources, set the file name to Octane=Jira.

   

3. Enter the non-LDAP users in the following format: <Unique iD>|<user>=<user email>. For example:

   ABCDEFG|John Smith=john.smith@acme.com

   HIJKLMNO|Tom Conway=tom.conway@acme.com

4. In the <Connect_installdir>\Utilities folder, open the mfcUserMaps,bat file in a text editor.

5. Uncomment the exceptions option (remove REM) and add a reference to the file you created above. For example:

   "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%" "|" "exceptions" "%USER_MAPS_PATH%\Octane=JIRA"

6. If you are also using the Purge batch script, add the above command to the end of the file, before the Connect service restart.

Back to top

See also:

• User maps and user matching

• Add projects and rules to a connection

• Batch utility scripts