Share this page

# 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 via 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.

Note: In Jira, ALM Octane and ALM/QC data sources: The utility extracts only those users who participate in the projects defined in the connection.

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

The files are saved in: <Micro Focus Connect directory>/UserMaps.

The script runs without stopping the Micro Focus 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 ..\Micro Focus\Connect\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`

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 via proxy servers, specify the proxy details in property bag files.

To specify proxies in property bag files (only required if the endpoint requires a proxy):

1. Create a text file using the following naming convention: {datasourcename}.property.bag.txt

   {datasourcename} needs to match exactly one of the data source names as defined in Micro Focus Connect.

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

3. Save the property bag file in: <Micro Focus Connect directory>/UserMaps.
4. Run the mfcDataSourceUsers utility. For details, see DataSourceUsers and UserMaps.

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, list the following parameter:

   columns=key,identifier

   key and identifier must exactly match 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: <Micro Focus Connect directory>/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. To allow all Jira users, even if their emails are not unique, add `tablescan=true`.To only allow users with a unique email address, the default behavior, leave out the tablescan property or set it to false.

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 Micro Focus 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 Micro Focus 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 Micro Focus Connect to stay up to date with changes made to the LDAP/Active Directory systems. This allows Micro Focus 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 Micro Focus 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:

"%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%" "|" "pairs" "%USER_MAPS_PATH%\JIRA" "%USER_MAPS_PATH%\OCTANE" ["OCTANE=DefaultOctaneUserRepresentation" “JIRA=DefaultJiraUserRepresentation”]

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 Micro Focus Connect 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, Micro Focus Connect 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 disabled 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:

"%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%" "|" "orphans" "%USER_MAPS_PATH%\JIRA" "%USER_MAPS_PATH%\OCTANE" "OCTANE=DefaultOctaneUserRepresentation" “JIRA=DefaultJiraUserRepresentation”

Pairs and orphans example

This example has Jira and ALM Octane data source user accounts named MFConnectJira and MFConnectOctane.

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= MFConnectOctane | -
Representation only on Jira side | John Smith=John Smith Ted Brown = MFConnectJira | -
Representation on both sides | John Smith=John Smith Bob White= MFConnectOctane Ted Brown = MFConnectJira | Bob White= MFConnectOctane Ted Brown = MFConnectJira

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, usin the UserMap script from the Batch utility scripts.

To map the non-LDAP users:

1. Locate the UserMaps folder in your Micro Focus Connect installation.

2. Create a text file with no extension in this folder 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 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 Micro Focus Connect service restart.

Back to top

See also:

- User maps and user matching

- Add projects and rules to a connection

- Batch utility scripts

https://admhelp.microfocus.comMicro Focus Connect8942
Tips to improve your search results... Micro Focus Connect Help CenterMF Connect Help4.5AllView Local Help CenterView Online Help CenterbackGo back in browser historyforwardGo forward in browser historyRemove search highlightsnext topicGo to next topicprevious topicGo to previous topicPrint the current topicVersion: