Setting up the LDAP Import Map

From ServiceNow Wiki
Home > Integrate > Single Sign-On > LDAP > Setting up the LDAP Import Map
Jump to: navigation, search

The latest release this documentation applies to is Fuji. For the Geneva release, see LDAP integration. Documentation for later releases is also on docs.servicenow.com.


1 Overview

LDAP Mapping is the process of matching fields in your LDAP database to fields in your ServiceNow instance. Since this process has a performance effect, ServiceNow recommend scheduling processing during off-peak hours, or processing a few records at a time to maintain system availability.

2 Setting Up a Transform Map for LDAP

The best practice is to define a transform map that only imports the needed or required attributes. Depending on the version of ServiceNow you are using, the method for specifying LDAP mapping relationships varies. The easiest way to know whether or not you are running a version which uses the System LDAP application for the LDAP integration is to find the application from the application navigator.

If you do have the System LDAP application: use a transform map to specify your mapping. See Creating New Transform Maps for complete instructions.

If you do not have the System LDAP application: use a LDAP legacy import map to specify your mapping, or the default LDAP transform that is included in baseline instances. Remember to adjust the Coalesce field to match against the correct fields. For more information, see Using the Coalesce Field.

Note: The Run Business Rules option is applied only for the target table. Only transform maps associated to the target table run the business rules associated with different tables. If you are updating a user group and have business rules running on a user group table, the group must have roles define.

The Table Transform Map form

LDAP field maps

2.1 Differences between 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 transform maps 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 of the manager. Without some extra logic in place the result is the creation of a ServiceNow 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.

The System LDAP menu

2.1.1 Transitioning from Legacy Maps to Transform Maps

In order to retain the LDAP mapping relationships that existed prior to the addition of the System LDAP application, clear the reference field for your LDAP server (which is associated with your old Legacy Import Map). The LDAP Server has a Map field that is a reference to the the Legacy Import Map. By default, this field is hidden so you will have to configure the form to display it. If you want to transition to using a Transform Map then you should clear the reference specified in this field.

2.2 Using the Default 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. Review Glide Properties. Note that 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:

ServiceNow 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

3 LDAP Scripting

These sample scripts automate common LDAP tasks.

3.1 Set Disabled Active Directory Users to Inactive

You can identify disabled Active Directory users by checking the value of the userAccountControl attribute. Use the following script to automatically disable ServiceNow users when the associated AD user is disabled. This rule executes whenever the User Account Control value changes and disables user accounts if the User Account Control signifies a disabled AD account.

  1. Configure the User form and create a new integer field called User Account Control.
  2. Add mapping for userAccountControl (external) to the new field.
  3. Create a new business rule with the following properties:
Business Rule field Value
Name Disable AD Users
Table User [sys_user]
When Before
Condition current.u_user_account_control.changes()
var disabledFlag = 2;
//perform a bitwise comparison on userAccountControl to see if the 2 bit flag is enabled
if (current.u_user_account_control & disabledFlag) {
  gs.log('Disabling user: ' + current.user_name + 'userAccountControl=' + current.u_user_account_control);

3.2 Assign Field Values

You can use a script to assign a value to any field for which there is a field mapping. For example, to assign a value to the sys_user.company field, create a field map for the company field and add a transform script of:

company = "Don's Sporting Goods";

3.3 Skip Particular Users

If you cannot completely filter the LDAP user list using LDAP filter properties, you can exclude users with a map script. Once you have run the logic to identify a user that should not be imported, set the user_name field to an empty string and this user will not be imported.


One way to identify users to filter out is to look for a string in the distinguishedName attribute. For example, this script excludes accounts that are not in a Users OU. You might use this script if you have too many Users OU to include in the target OU LDAP Option.

//vdn is a variable mapped to distinguishedName
var vdn = source.getElement(this.distinguishedName);
if (vdn.indexOf('OU=Users')<0) {
  gs.log('LDAP Import Skipping User: ' + vdn);

A more complex method of filtering is to use Regular Expressions.

//vcn is a variable mapped to cn
//vdn is a variable mapped to distinguishedName
//c is the regular expression string
var vdn = source.getElement(this.distinguishedName);
var vcn = source.getElement(this.cn);
var c = /^[a-z][a-z][a-z][0-9][0-9][0-9]$/;
var nvcn = vcn.toLowerCase();
//test to see if the cn is in the form of 3 letters followed by 3 numbers, only import these
if (c.test(nvcn)) {
	user_name = nvcn;
} else {
	gs.log("LDAP import rejected username: " + vcn + " for DN: " + vdn);
	user_name = "";

4 Verify LDAP Mapping

After creating an LDAP transform map, refresh the LDAP data to verify the transform map works as expected.

  1. Navigate to System LDAP > Scheduled Loads.
  2. Click on your LDAP import job.
  3. Click Execute Now.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Personal tools