Automatically create user maps

Synchronizing data sources involves also synchronizing the users defined in the data sources. The same user may be defined differently in each data source.

To cope with this, you can 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.

Process outline

Automatically creating user maps involves the following high-level steps. The steps are described in detail in the sections below.

  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 the 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: For 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.

Exclude data sources

You can exclude data sources from the data extraction process.

  1. Create a file called excludedatasources.txt in the ..\Micro Focus\Connect\UserMaps folder.

  2. Add to the file the names of the data sources to be excluded:

    • Type the exact, case sensitive data source name

    • One data source per line

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 for each data source

The data sources 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 parameter 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.

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.
  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 will allow 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

For example, let's say you have Jira and Octane data source user accounts named MFConnectJira and MFConnectOctane.

In 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 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