Create user maps and apply user matching

To synchronize user fields with Micro Focus Connect, you use user maps and user matching.

About user matching and user maps

User matching involves finding a user representation across two products such that a user in one system is the same user as one from the other system.

Within Micro Focus Connect, users can be represented in a product using different methods:

  • Email

  • Name

  • Full name

If you use the same user representation in both products, you do not need to use User maps.

When the user representation is inconsistent, you must define User maps. User maps describe how a user is identified in all your data sources.

Define user maps:

  • In the UI

  • Import an xml file

  • Use batch utilities to automate user map creation and updates

User maps define users that have different user names across multiple Data sources. User maps allow you to map these two users together so that Micro Focus Connect knows they are the same user.

The Micro Focus Connect batch utilities offer an alternative and more robust method to create and maintain user maps. To learn more about our supported command line utilities, see DataSourceUsers and UserMaps.

Back to top

Define user maps in the UI

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 Micro Focus Connect database using the Batch utility scripts. For details, see Automatically create user maps. Alternatively, define a User map in the Micro Focus Connect and export it.

To import User maps:

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

  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 Micro Focus Connect 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 navigate 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

Example: Create a user map with the default user

The following section describes how to create a user map with the default user for a synchronization between Jira and ALM Octane.

This example creates a mapping from the Jira Display Name to the ALM Octane Email. Jira is currently restricted to display name. ALM Octane user representation can be set to either email, full name, or name.

To create the user map:

  1. Determine the fields you want to map. Jira is currently restricted to display name. ALM Octane user representation can be set to either email, full name, or name.This example creates a mapping between the Jira display name and ALM Octane email.
  2. Exclude any data sources that are not required: Create a file named excludedatasources.txt in the ..\Micro Focus\Connect\UserMaps folder and add all the data source names that you want to exclude. Separate the entries with a line break. Note: The data sources names must match exactly, including upper and lower case.

  3. Perform an initial extraction of the user data:

    1. Open a command prompt as an administrator.
    2. Navigate to the Micro Focus Connect Utilities folder. For details, see Batch utility scripts.

    3. Run the DataSourceUsers script. This extracts all of the user data from the data sources to files. These files are given the names of the data sources with no extensions, in this example OCT_TEST and Jira Cloud. This step uses a unique key that exists in both data source files. In this example, the email address is unique in both systems and it is used as the key.

      OCT_TEST file content

      id|name|email|first_name|last_name|full_name|phone1|
      5003|TomJones|tom.jones@microfocus.com|Tom|Jones|Tom Jones|null|

      Jira Cloud file content

      key|name|displayName|emailAddress|accountId
      null|null|Tom Jones|tom.jones@microfocus.com|6086f22fbb0b0500704ea7c3

  4. Configure the fields used for the mapping by creating property bags for each data source. In this example, the data sources are named OCT_TEST and Jira Cloud, resulting in the following files: OCT_TEST.property.bag.txt and Jira Cloud.property.bag.txt. The names are case-sensitive.

    • The OCT_TEST.property.bag.txt has the following columns defined:

      columns=email,email

    • The Jira Cloud.property.bag.txt has the following columns defined:

      columns=emailAddress,displayName

  5. Extract the user data again: Open a command prompt as an administrator, navigate to your Micro Focus Connect Utilities folder, and run the DataSourceUsers script. This extracts all of the user data from the data sources to files, filling them with content:

    • The OCT_TEST file content:

      tom.jones@microfocus.com|tom.jones@microfocus.com

    • The Jira Cloud file content:

      tom.jones@microfocus.com|Tom Jones

  6. Create user maps:

    1. Open the mfcUserMaps.bat file in the Micro Focus Connect Utilities folder in a text editor.
    2. Uncomment the line that has the pairs option by removing the REM from the start of the line. When run with the pairs signature it executes incremental inserts/updates of common missing keys and/or changed values for the file pairs.

    3. Add the references to the data sources and a default user for each system, The user you designate as default, must exist.

      "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%" "|" "pairs" "%USER_MAPS_PATH%\OCT_TEST" "%USER_MAPS_PATH%\Jira Cloud" "OCT_TEST=tom.jones@microfocus.com" "Jira Cloud=Tom Jones"

    4. Save the mfcUserMaps.bat file.

    5. Open a command prompt as an administrator, navigate to your Micro Focus Connect Utilities folder, and run the UserMaps script. This script stops the Micro Focus Connect Connect service, adds the user maps, and restarts the service. The results displayed in Micro Focus Connect are:

      • The mapping key: TOM.JONES@MICROFOCUS.COM
      • User representation in Jira: Tom Jones
      • User representation in ALM Octane: tom.jones@microfocus.com

  7. Automate the process: Since users can be added on both systems, it is a recommended practice to automate the process. Navigate to your Micro Focus Connect Utilities folder, and edit the mfcPurge.bat file in a text editor. Add the bolded lines (the below code is based on the changes made to the batch files above):

    "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcAudit.jar" "%CONNECT_PATH%" "|" "%BACKUP_PATH%" "connectionnames=" "columnnames=" "datetime="

     

    REM run the mfcDataSourceUsers.bat java command line text

    "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcDataSourceUsers.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%"

     

    net stop ConnectWebServer

    :loopStop

    sc query ConnectWebServer | find "STOPPED"

    if errorlevel 1 (

    timeout 1

    goto loopStop

    )

     

    REM run the mfcUserMaps.bat java command line text

    "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "removeall"

    "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcUserMaps.jar" "%CONNECT_PATH%" "%USER_MAPS_PATH%" "|" "pairs" "%USER_MAPS_PATH%\OCT_TEST" "%USER_MAPS_PATH%\Jira Cloud" "OCT_TEST=tom.jones@microfocus.com" "Jira Cloud=Tom Jones

    …

    If not already scheduled, add this script to your task scheduler to run on a daily basis. For details, see Purge files on Windows as a nightly task.

Back to top

Next steps: