LDAP transform maps

  • Release version: Yokohama
  • Updated January 30, 2025
  • 6 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of LDAP transform maps

    LDAP transform maps in ServiceNow facilitate moving data from LDAP import set tables to target tables such asUserorGroup. These transform maps use standard import sets and enable integration with Active Directory or other LDAP directories. Customers can use default transform maps or create custom ones, but only one active transform map should be enabled per source and target table combination to avoid duplicate entries.

    Show full answer Show less

    Default LDAP transform maps

    ServiceNow provides two default LDAP transform maps:

    • LDAP User Import: Maps data from ldapimport to sysuser, designed for creating user records during LDAP on-demand login with Active Directory mappings.
    • LDAP Group Import: Maps data from ldapgroupimport to sysusergroup, used for creating group records from LDAP organizational units (OUs).

    Note that there is no default transform map for LDAP department records.

    Creating and using custom LDAP transform maps

    Custom transform maps must follow specific mapping rules, especially to enable proper user and group identification and authentication. Important fields include:

    • usource (not coalesced) identifies the LDAP distinguished name (DN) for users or groups, used for authentication and association.
    • One of usamaccountname, udn, or ucn (coalesced) is used to uniquely identify users depending on LDAP directory type (e.g., Active Directory uses usamaccountname).

    When mapping reference fields like manager or department, transform scripts are required because LDAP attributes often contain distinguished names rather than direct references. ServiceNow provides built-in transform scripts to handle these references properly, avoiding incorrect record creation.

    LDAP data transformation and reference handling

    Simple LDAP attributes map directly to target table fields. For reference fields, if a matching record exists it is linked; otherwise, a new record is created. Distinguished names (DNs) are long text strings representing LDAP references, which must fit target field lengths (default 40 characters may be insufficient and can cause truncation).

    To accurately associate manager references, ServiceNow includes the LDAPUtils script with setManager and processManagers functions. These parse DNs and find existing user records to set manager fields properly. The default LDAP User Import transform map uses these functions in transform and onComplete scripts to handle manager references, ensuring data integrity even if managers are imported after their direct reports.

    If your integration does not use the manager attribute, these function calls should be removed or commented out.

    Additional considerations

    • Only one active transform map per source-target pair should be enabled to prevent duplicate entries unless coalescing is correctly set.
    • For importing and coalescing on binary LDAP attributes (e.g., objectSID), custom transform scripts are necessary.
    • The username field must be mapped to a unique LDAP attribute containing the user's login ID (commonly sAMAccountName for Active Directory).
    • Legacy import maps can be transitioned to transform maps by clearing references to old import maps, accessible via a hidden Map field on the LDAP server record.

    The transform map moves data from the import set table to the target table (User or Group).

    The LDAP integration uses standard import sets and transform maps. You can also create custom LDAP transform maps.
    Important:
    Whether you select or create custom LDAP transform maps, there should be one active transform map for a set of source and target tables. Enabling multiple transform maps for the same source and target tables can produce duplicate entries in the target table unless you coalesce against the matching fields.

    Default LDAP transform maps

    By default, the system provides two transform maps for LDAP data.
    Table 1. Default LDAP transform maps
    Transform Map Source Table Target Table Description
    LDAP User Import [ldap_import] [sys_user] Default transform map for creating user records from LDAP credentials as part of LDAP on-demand login. Contains mappings for an Active Directory LDAP server.
    LDAP Group Import [ldap_group_import] [sys_user_group] Default transform map for creating group records from LDAP OUs. Contains mappings for an Active Directory LDAP server.
    Note:
    By default, the system does not have a transform map for LDAP department records.

    Requirements for custom LDAP transform maps

    If you choose to create a custom transform map, the transform map must meet the following mapping requirements.
    Table 2. Requirements for custom LDAP transform maps
    Source Table Source Field Target Table Target Field Coalesce Description
    ldap_import u_source sys_user source false The u_source field identifies the LDAP DN of the imported user or group. The system uses this field to determine that a user requires LDAP authentication, to find a user's manager, and to put users into groups.
    ldap_import Select one of the following fields:
    • u_samaccountname
    • u_dn
    • u_cn
    		 sys_user user_name true If LDAP integrates to Active Directory, select u_samaccountname as the source field. If other LDAP directories are used, select u_dn or u_cn as the source field.

    Differences between LDAP transform maps and legacy import maps

    When specifying LDAP mapping relationships using transform maps, there is a major difference in how reference fields are set for manager and department.

    When using a transform map, it is necessary to use a transform script to create references. This is because the value associated with an LDAP attribute like "manager" is the distinguished name (DN) of the manager.

    Without some extra logic in place, the result is the creation of a user record with a manager name that is the distinguished name of that user in LDAP. The integration includes a transform script to facilitate the creation of these references. The default transform map "LDAP User Import" includes transform scripts for these references.

    Existing mapping relationships
    When updating legacy import maps to transform maps, you can retain the LDAP mapping relationships that existed prior to the addition of the System LDAP application. The LDAP server has a Map field that is a reference to the legacy import map.
    Note:
    By default this field is hidden, so you have to configure the form to display it.
    If you want to transition to using a transform map, clear the reference to the legacy import map.
    LDAP import map settings
    Verify and use attributes to limit the fields the integration imports from the LDAP source. Additionally, it is important to map the user_name field to the LDAP attribute that contains the user's login ID. For Active Directory this is usually the sAMAccountName attribute. If you would like to import and coalesce on a binary attribute (such as objectSID or objectGUID), you have to create a custom transform script.
    Note:
    Any value mapped to the user_name field must be unique.

    If you do not specify a transform map (such as LDAP User Import), the integration uses the following default mappings:

    Table 3. LDAP import default mapping
    User field or variable LDAP attribute
    user_name sAMAccountName
    email mail
    phone telephoneNumber
    home_phone homePhone
    mobile_phone mobile
    first_name givenName
    last_name sn
    title title
    department department
    manager manager
    middle_name initials
    u_memberof groups
    u_member members
    u_manager manager

    LDAP data transformation

    If an LDAP attribute contains simple data, the transform map links an imported LDAP attribute to an appropriate field in the target table (User or Group). For example, sample data in the sAMAccountName attribute maps to the User ID field in the User table.

    If the imported LDAP data maps to a reference field, the instance searches for an existing matching record. If no matching record exists, the instance creates a new record for the reference field unless the field mapping specifies otherwise.

    For example, suppose the LDAP attribute l maps to the Location reference field in the User table. Whenever the import brings in an attribute value that does not match an existing location record value, the transform map creates a new location record. The new location record has the same value as the imported attribute, and the imported user record now has a link to the new location record.

    However, there are times when LDAP attribute returns a distinguished name (DN), which is essentially a reference to another record within the LDAP directory. For example, the manager attribute typically contains the distinguished name for the manager of the current LDAP directory entry. An imported DN typically uses a long text string such as: cn=Beth Anglin,ou=Users,dc=my-domain,dc=com.
    Warning:
    Make sure your target fields are long enough to contain a DN. Many text fields use the default length of 40, which may not be long enough for some DN values. The ServiceNow system truncates any value that exceeds the field length.

    Administrators do not typically want the system to create new users from the DN value because the new user has no association with an existing user. Instead, administrators want the import to locate the manager's existing user record and associate it with the newly imported user. The LDAPUtils script include contains the setManager and processManagers functions that can parse a DN and search for an existing user. For best results, use these functions to create a custom transform map.

    For example, the LDAP User Import transform map script calls the setManager function:
    
// 
// The manager coming in from LDAP is the DN value for the manager.   
// The line of code below will locate the manager that matches the 
// DN value and set it into the target record.  If you are not  
// interested in getting the manager from LDAP then remove or 
// comment out the line below
ldapUtils. setManager (source , target ) ;
    In some cases, the integration imports a user's record before importing the associated manager's user record. To handle such cases, you may want to call the processManagers function after the transform completes. For example, the LDAP User Import transform map uses an onComplete transform script to call the processManagers function.
    // It is possible that the manager for a user did not exist in the database when // the user was processed and therefore we could not locate and set the manager field. // The processManagers call below will find all those records for which a manager could  // not be found and attempt to locate the manager again. This happens at the end of the  // import and therefore all users should have been created and we should be able to  // locate the manager at this point 
ldapUtils. processManagers ( ) ;

    Remove or comment out the setManager and processManagers function calls if your LDAP integration does not use the manager attribute.