Mapping

Mapping is a data integration functionality that automatically maintains mapping files based on external data sources, such as Active Directory and text files. This gathers metadata, like Departments, Locations, E-mails, Full Names, etc., from external sources.

warning

Make sure that LDAP Collector is configured before proceeding with the mapping configurations.

Adding a Text File Source

1. Go to Administration > Mapping > Source.

2. Click New Source.

3. Name the new source created as ldap_[client_name].

4. On the drop-down beside the text box for the name, select Text File.

5. Click Save.

   

   Adding Text File Source

   
   

6. Provide the location of the text file and choose \t as the separator to be used. The file must be located in the LdapCollector directory, which is by default in C:\Program Files\OpeniT\Core\Log\temp\LdapCollector for Windows and /var/opt/openit/temp/LdapCollector for Unix.

7. Click Save.

8. Click (Re)Load fields.

   

   Text File Source Information

   
   

9. Select sAMAccountName as the Unique Key for the map data. Keeping track of historical changes requires this reference key.

   • Under the Include column, check all the fields used for generating mapping files from this source, including the ID key.
   • Under the Track History column, check the department, division, and l data fields.

10. Click Save.

Text File Field Selector

11. Create another source by clicking New Source.
12. Name the new source created as email_[client_name].
13. On the drop-down beside the text box for the name, select Text File.
14. Click Save.

Adding a Text File Source

15. Provide the location of the text file and choose \t as the separator to be used. The file must be located in the LdapCollector directory, which is by default in C:\Program Files\OpeniT\Core\Log\temp\LdapCollector for Windows and /var/opt/openit/temp/LdapCollector for Unix.

16. Click Save.

17. Click (Re)Load fields.

Text File Source Information

18. Select mail as the Unique Key for the map data. Keeping track of historical changes requires this reference key.

    Under the Include column, check all the fields used for generating mapping files from this source, including the ID key.

    Under the Track History column, check the department, division, and l data fields.

19. Click Save.

Text File Field Selector

If you want to use Active Directory (AD) as the mapping source, follow these instructions:

NOTE

Take note of your Active Directory credentials when using it as the mapping source.

Adding an Active Directory Source

Make sure that a source is available. This requires an AD server, port, forest path, IP address, username, and password.

1. Go to Administration > Mapping > Source.

2. Click New Source.

3. Name the new source.

4. For the Type, select Active Directory.

5. Click Save.

   

   Adding New Active Directory Source

   
   

6. Fill out the details to connect to the Active Directory.

7. Click Test connection.

8. Wait for it to process. After successfully connecting to the AD, click Save.

   

   Active Directory Details

   
   

9. Choose how to filter the schema list. Basic is selected by default. The Advanced filtering allows administrators to provide a custom filter string to optimize their interactions with the Active Directory.

   NOTE

   For advanced filtering, it is helpful to have an AD Explorer installed. The AD Explorer will provide the valid filter string reference needed in the configuration. You may also check this reference for the filter syntax.

   

   Active Directory Schema

   
   

10. If Basic is selected:

    • Click the Get schema list button.
    • Select user from the drop-down list.

    

    Active Directory Schema

    
    

    If Advanced is selected, a default filter string will be supplied. Alternatively, you can manually type in or paste a specific filter string into the text field for precise data filtering.

11. Click Save.

    

    Active Directory Schema

    
    

12. On the (Re)load Fields, select all.

    NOTE

    If you select the Advanced schema filtering, the reloading of fields may take time, depending on the number of fields filtered based on the provided filter string.

    
    

13. Select a stable key and set it as the Unique Key for the map data. Data extraction and historical change monitoring require this key.

    Fields	Description
    Unique Key	Used to differentiate between user records, usually SAMAccountName in Active Directory.
    Name	Name of the source record as it is seen from the source.
    Include	Select relevant fields to include in the data gathering. The mapping module updates the selected fields nightly.
    Track History	Toggle the history to track the fields over time to account for users moving between departments or if it should only display the most recent value. Consider tracking historical changes when creating input sources. For example, keeping historical data for reporting could be vital for Country, Region, Department, and Project; keeping track of old Mail, Phone number, and Office number is likely not helpful.

    Field Selector
    
    
    NOTE

    Several mapping files may be generated based on a single input source.

    Under the Include column, check all the fields used for generating mapping files from this source, including the ID key.

    Under the Track History column, check all the required historical data fields.

    NOTE

    Click the Default button to automatically include title, physicalDeliveryOfficeName, mail, l, displayName, department, sAMAccountName, division, employeeType, and manager fields. Also, the sAMAccountName will be automatically selected as the default Unique Key.

    
    

14. After selecting the desired fields, click Save.

    

    Active Directory Field Selector

    
    

After adding a text file source or an Active Directory source, proceed with configuring the mapping files.

Configuring Mapping Files

1. Go to Administration > Mapping > Maps.

2. Click New Map.

   

   Creating New Map

   
   

3. Select the two (2) newly created mapping sources.

4. Select license-multi as the mapping Type.

   Mapping Types

   Types	Description
   license-single	The older format of license mapping for a single source field to a single group type (e.g., user to department). It is a one-to-one map used to map a user to a user group.
   license-multi	This new mapping format allows mapping from a single source to multiple group types (e.g., user to department, location, project). It stores fields, such as Location, Department, and City of any group with concurrency.
   virtual	Virtual mapping files can be used for any data type and allow mapping from one source field to a single group type. This mapping adds user attributes and lists users of a department and the corresponding address.

   Mapping Types

   
   
   NOTE

   Virtual mappings are one-to-one maps, which means that each attribute needs one map.

5. Set user-to-groups.map as Filename for the map. This file will be saved in C:\Program Files\OpeniT\Core\Configuration\ for Windows and /var/opt/openit/etc for Unix by default.

   warning

   It is not advisable to edit this file manually. The mapping module will overwrite any manual updates made to this file.

6. Choose Yes for Use History?.

7. Click Save. A list of sources will be shown.

   

   New Map Details

   
   

8. Two (2) tables with source fields will be displayed on the interface. The first table corresponds to the first mapping source, and the second table corresponds to the second mapping source.

   • For the first table, under the Key(s) column, check sAMAccountName.
     Under the Include column, check department, division, and l.
   • For the second table, under the Key(s) column, check mail.
     Under the Include column, check department, division, and l.
   
   
   danger

   An error will be prompted if no value is selected for Key(s) or Include.

   If the mapping file is virtual, you can directly include new maps in the web interface.

9. Click Save.

   

   New Map Field Selection

   
   

10. Create another map by clicking New Map.

    

    Creating New Map

    
    

11. Select the two (2) newly created mapping sources.

12. Select license-multi as the mapping Type.

Mapping Types

Types	Description
license-single	The older format of license mapping for a single source field to a single group type (e.g., user to department). It is a one-to-one map used to map a user to a user group.
license-multi	This new mapping format allows mapping from a single source to multiple group types (e.g., user to department, location, project). It stores fields, such as Location, Department, and City of any group with concurrency.
virtual	Virtual mapping files can be used for any data type and allow mapping from one source field to a single group type. This mapping adds user attributes and lists users of a department and the corresponding address.

Mapping Types

NOTE

Virtual mappings are one-to-one maps, which means that each attribute needs one map.

13. Set user-properties.map as Filename for the map. This file will be saved in C:\Program Files\OpeniT\Core\Configuration\ for Windows and /var/opt/openit/etc for Unix by default.

    warning

    It is not advisable to edit this file manually. The mapping module will overwrite any manual updates made to this file.

14. Choose No for Use History?

15. Click Save. A list of sources will be shown.

    

    New Map Details

    
    

16. Two (2) tables with source fields will be displayed on the interface. The first table corresponds to the first mapping source, and the second table corresponds to the second mapping source.

    • For the first table, under the Key(s) column, check sAMAccountName.
      Under the Include column, check displayName, employeeType, mail, physicalDeliveryOfficeName, and title.
    • For the second table, under the Key(s) column, check mail.
      Under the Include column, check displayName, employeeType, mail, physicalDeliveryOfficeName, and title.
    
    
    danger

    An error will be prompted if no value is selected for Key(s) or Include.
    If the mapping file is virtual, you can directly include new maps in the web interface.

17. Click Save.

    

    New Map Field Selection

    
    

Verifying the Data Sources and Mapping Files

1. Go to Administration > Job Runner

2. Look for Update Data Sources and Mapping Files, click Run.

   

   Job Runner: Update Data Sources and Mapping Files

   
   

3. Go to the Configuration directory C:\Program Files\OpeniT\Core\Configuration for Windows and /var/opt/openit/etc for Unix. Verify that user-to-groups.map and user-properties.map files exist.

You may refer to the following guides for managing Mapping Sources, Mapping Files, and Mapping Overlay.

Editing a Mapping Source

1. Go to Administration > Mapping > Source.

2. On the left side of the screen, select the Source to edit.

3. Make the necessary updates to the Source settings or fields.

4. Click Save.

Deleting a Mapping Source

1. Go to Administration > Mapping.

2. On the left side of the screen, select the Source to delete.

3. On the lower-right part of the screen, click Delete.

4. Click OK on the pop-up.

Deleting a Source

Editing a Mapping File

1. Go to Administration > Mapping > Maps.

2. Click the name of the map to edit.

3. Make the necessary updates to the map.

4. Click Save.

Deleting Mapping Files

1. Go to Administration > Mapping > Maps.

2. Tick the checkbox corresponding the map(s) to delete.

3. Click Delete.

4. Click OK on the pop-up window.

Deleting Mapping Files

Configuring a Mapping Overlay

Configure the overlay to tailor the user details shown in the License Monitor.

This tab is only accessible if a mapping is configured under Maps and if the mapping files are updated.

Follow these steps to configure the overlay:

1. Go to Administration > Mapping > Overlay.
2. Select configuration file.
3. The overlay will appear on the interface. Select the field to display on the overlay.
4. Click the green plus icon to add field(s), meanwhile, click the red minus icon to delete field(s).
5. Click the pencil icon to edit the field label.
6. Click the up or down icon to change the arrangement of the fields.
7. Click Save.
8. Click OK on the pop-up.

Configuring a Mapping Overlay

Editing a Mapping Overlay

1. Select the overlay to edit from the drop-down.

2. Make the necessary updates to the overlay.

3. Click Save.

Next Step?

After completing the Mapping configuration, you may proceed with managing the Mapping Sources in the Analysis Server.

Managing Mapping Sources