How to successfully create LDAP objects within ServiceNow utilising the LDAPUtils script include
Please indulge me a brief moment to introduce the subject matter of the article for those uninitiated. For those of you with a background in Windows Systems administration, you will no doubt already be well aware of the fact that an LDAP directory can be thought of logically as having the appearance of a tree structure. All entries (called objects) of the directory have a defined position within this hierarchy. In all, the tree structure is known as the directory information tree (DIT). Each entry in the DIT consists of an attribute value pair when combined, and these attributes describe an object, which can be thought of as a record. The complete "path" to the desired entry is known as a Distinguished Name (DN). A DN has a unique name that identifies the entry in the respective hierarchy. In the example above, John Doe and Jane Doe are different common names (cn) that identify different entries at that same level
We can conceptualise this LDAP Directory Structure in the following diagram:
Understanding the LDAP directory structure in the ServiceNow platform
As you can imagine, a complete path to a record, Distinguished Name, or DN, can become unwieldy. It is difficult for software applications that were designed to store data in the relational database model, such as platforms like ServiceNow, to store in complex tree data structures as is seen in LDAP databases. The DIT structure is great for organising, storing, and accessing large commonalities of data for LDAP, but maintaining data integrity for structures such as these is challenging for ServiceNow.
Using the LDAPUtils script in the LDAP directory
To overcome this shortcoming, the LDAPUtils script include is bundled with the core ServiceNow platform to transform Distinguish Names records into a format that the platform can manage and store. However, despite the inclusion of the LDAPUtils script include into the platform, ServiceNow customers may still find themselves in a situation where they have data represented on their LDAP server that differs slightly from the way that the same data object is represented in ServiceNow.
Let's say, for argument's sake, that a customer is attempting to import a user account from an LDAP Server, but this LDAP user object is configured with a manager property. In cases such as this, the customer may find that the import set record for user object contains all the data properties that the object possesses, has it is found on LDAP. Including the manager field. But after performing a load and transform of the data to a ServiceNow table, such as the sys_user, they find that manager property (field), present in LDAP source and the import set record, is now empty in the sys_user table within Service Now. The reason behind this is the OOB transform map, named 'LDAP User Import', is not configured with required functions to handle the manager properties from the LDAP source and needs to be configured to do so.
For the curious, if you were to explore the LDAPUtils script include, you will find a function named 'ldapUtils.setManagerField'. This method was coded to handle the transformation of the manager LDAP user object property into ServiceNow.
The desired behaviour would be for the distinguished name of the manager property from the LDAP source, and import set record, to appear, reconstituted, as a display name of a user account record in ServiceNow who is the manager of that given user account. So to be clear, the manager field should be a reference to a sys_user table record, that record would be the name of the person who is responsible for managing the user. The field would be of reference type to the sys_user record the representing the LDAP manager. To gain this desired behaviour, customers need to define which of the fields on their target table is intended to represent the manager.
Below is an example of the OOB LDAP User Import transform map that has been modified to set the manager field to u_managed_by_field on the target table.
Similarly, if you were to further explore the LDAPUtils script include further, you will find that ServiceNow has also provided a whole host of functions to manage the transformation of DTI LDAP tree data into a format more palatable for ServiceNow to store. Examples of such are the addGroups and addMembers methods.
Troubleshooting the LDAPUtils script
If you find you are still having trouble correctly syncing your AD with ServiceNow in a fashion similar to that described above, please take the following action:
- Ensure that the manager data is formatted as a DN name in the import set. The OOB LDAPUtils script include function is not robust enough to translate formats it is not prepared for.
- Once the data has been uploaded to the import set table, check for and remove duplicate records. Clean up anything that may confuse for the outcome of the data transform.
- Clean the import set table, create a new import set, and resume testing your data transform.
- Review the data in AD and compare that to the LDAP setup in ServiceNow. Verify whether ServiceNow is set up to do the import in the way you are expecting it to.
For further reference, check out the following discussion from the ServiceNow Community and the ServiceNow platform documentation
