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

# 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 the 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 the 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:

Ensure that a source is available. This requires 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 custom filter string to optimize their interactions with the Active Directory.

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

    1. Click the Get schema list button.
    2. 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.

    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
    
    
    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 Track History column, check all the required historical data fields.

    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.

   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, 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
   
   
   Virtual mapping 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 is by default in C:\Program Files\OpeniT\Core\Configuration\ for Windows and /var/opt/openit/etc in Unix.

   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 the sAMAccountName. Under the Include column, check the department, division, and l.

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

   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.

    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, 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
    
    
    Virtual mapping 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 is by default in C:\Program Files\OpeniT\Core\Configuration\ for Windows and /var/opt/openit/etc in Unix.

    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 the sAMAccountName. Under the Include column, check the displayName, employeeType, mail, physicalDeliveryOfficeName and title.

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

    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, which is by default in 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.

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.

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

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.

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
   
   

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
   
   

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