NOTE: MY POSTINGS REFLECT MY OWN VIEWS AND DO NOT NECESSARILY REPRESENT THE VIEWS OF MY EMPLOYER, ACCENTURE.
THE FOLLOWING ARTICLE IS A SUGGESTED METHOD FOR DEVELOPING AND TESTING ORCHESTRATION CODE, AND IS NOT AN ENDORSEMENT OF ANY PARTICULAR PRODUCT MENTIONED.
DIFFICULTY LEVEL: ADVANCED
Assumes knowledge and/or familiarity of several different areas in ServiceNow and Windows.
____________________________________________________________________________
Now that we have Active Directory (AD) installed on a VirtualBox server it is a straight-forward matter to set up LDAP and do a round-trip with Orchestration. After all, we need a way to refresh our ServiceNow User table with any updates, inserts, or deletes, right? To do this ServiceNow has provided an LDAP listener mechanism.
This article will not cover all the in's-and-out's of installing LDAP, but only those topics necessary to get things to update from the VirtualBox AD to your Developer Instance User table. This will give you the final step in the "round-trip" of creating a user using ServiceNow.
BTW, I created this lab without LDAPS or Certificates, but rather took the simpler path of just LDAP. I leave the LDAPS implementation for you to conquer!
What we will be doing in this article:
Orchestration Workflow -> Active Directory -> LDAP Listener -> LDAP Import -> Transform -> ServiceNow User Table.
The items marked in yellow are what has been completed so far. The white is to-be-done.
Prerequisites:
1. Do the previous two labs in this series for installing a VirtualBox Windows 2008 Server, and setting up Active Directory on it.
- Mini-Lab: Orchestration - Creating your own Windows 2008 Server with VirtualBox
- Mini-Lab: Creating your own AD Server with VirtualBox
2. Some familiarity with Windows 2008 Server.
3. Familiarity with creating a Transform Map from scratch.
4. Familiarity with User administration.
5. Before starting you will need to spin up your VirtualBox Windows 2008 Server. It needs to be running for the following process to work.
Lab 1.1: Creating the LDAP Listener
First we will create the LDAP listener.
This depends on a couple of factors:
- What is the name of your AD domain?
- What is the User ID and Password you will be using for Domain Admin?
Note: The values listed below are specific to my laptop and the VirtualBox Windows 2008 Server I had created for the previous labs.
1. Navigate to System LDAP. This will display the out-of-the-box (OOB) LDAP Application.
2. Navigate to System LDAP -> Create New Server. This will display the New LDAP Server form.
3. Fill out the form with the following:
a. Type of LDAP Server: Active Directory
b. Server Name: myForest LDAP Server
c. Server URL: ldap://192.168.43.6:389/
(this will depend on your implementation of the AD server in the labs from the last article. Port 389 is for normal LDAP)
d. Starting search directory: DC=myforest,DC=local
(this will depend on how you set up AD in the labs from the last article)
The finished form should look something like this:
e. Click on the Submit button to save your work. This will take you to the LDAP Server form for your new server. Continue filling in the form.
i. Login distinguished name: myForest\Administrator
(I used my domain admin I had created in the last lab)
ii. Login password: ***********
f. Right-click on the header and save your work.
Ignore any errors that may appear like (this is normal):
g. Scroll down to Related Links and make sure the Listener is in stopped state. If not then click on the Stop Listener link. You cannot fill in and save the MID Server field unless the Listener is off.
i. Fill in the MID Server: StevesFabMid_Lap
(this is my laptop Geneva MID Server. You will need to use your own)
h. Right-click on the form header and Save to save your work.
i. Scroll down to the Related Links and click on the Start Listener link.
j. After the Listener is back up and running. Then click on the Test Connection link to verify that things are really ok. If all is good your LDAP Server URL should light with a green dot next to it, and the Operational Status column will display "true". Also, the Listener check box will be checked in the Advanced Options section.
Everything should look like this:
Lab 1.2: Creating the Custom LDAP OU Definition and Data Source
1. Scroll down to the bottom of the LDAP Server form. You will observe in a related list that two LDAP OU Definitions have been created for you. These should be Groups, and Users. We will be adding a third to pull in the ForestAdmins OU users that we created in the last article.
a. Click on the New button on the related list. This will display the New LDAP OU Definition form. Fill out the form with the following:
i. Name: ForestAdmins
ii. RDN: OU=ForestAdmins
iii. Query Field: sAAMAccountName
iv. Filter: (&(objectClass=person)(sn=*))
v. Server: Should already be auto-filled with your MID Server name.
vi. Table: Should already be auto-filled with User [sys_user]
vii. Right-Click on the form head to Save your work.
Your form should look like this:
b. At the bottom of the form under Related Links click on the Browse link. After a moment this will display the LDAP Browse form.
c. Click on the "+" symbol next to the LDAP Nodes folder to expand the folder.
d. Click on one of the displayed names to bring up that user's attributes. If everything is right with the connection your form should look something like this:
e. Back arrow on your browser a couple of times to return to the New LDAP OU Definition form.
f. At the bottom of the form, in the Data Sources related list, click the New button. This will display the new Data Source form.
g. Fill in the form with the following:
i. Name: ForestAdmins_OU_LDAP
ii. Import set table label: LDAP Forest Admins OU
iii. Import set table name: u_ldap_forest_admins_ou
iv. Type: LDAP
v. LDAP Target: ForestAdmins
vi. Right click on the form header to save your work.
Your form should look something like this:
h. Under related links click on the Load All Records link. This will cause ServiceNow to create the Import set table and load any of the user records currently in the ForestAdmins OU. When done it should look something like this (you will notice that I had three user records in my ForestAdmins OU. You should see at least one record insert):
Lab 1.3: Creating the Custom LDAP Transform
1. Click on the Create transform map link. The new Transform Map form will be displayed.
2. Fill in the form with the following:
a. Name: ForestAdmins_OU_LDAP
b. Target table: User [sys_user]
c. Run script: Checked
d. Script (I copied this from the User transform that was auto-created):
(function transformRow(source, target, map, log, isUpdate) {
//
// 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. To ignore the manager
// from LDAP, remove or comment out the line: ldapUtils.setManager(source, target);
//
// NOTE: The 'manager' field SHOULD NOT be mapped in the 'Field Maps' related list
// if the manager is brought in through an LDAP import. The 'ldapUtils' scripts
// here and in the 'onComplete' Transform Map will map this value automatically.
ldapUtils.setManager(source, target);
// Set the source LDAP server into the target record
target.ldap_server = source.sys_import_set.data_source.ldap_target.server;
})(source, target, map, log, action==="update");
e. Right-click on the form head and Save your work.
3. Under related links click on the Mapping Assist link. This will display the Mapping Assist tool.
a. Arrange your fields to look like this:
b. Click update to save your work.
4. From the fields related list mark the user_name Coalesce field to true.
5. Under Transform Scripts click the New button:
a. When: onStart
b. Script:
(function runTransformScript(source, map, log, target /*undefined onStart*/ ) {
gs.include("LDAPUtils");
var ldapUtils = new LDAPUtils();
ldapUtils.setLog(log);
})(source, map, log, target);
6. Click the Submit button.
7. Click the New button again.
a. When: onComplete
b. Script:
(function runTransformScript(source, map, log, target /*undefined onStart*/ ) {
//
// 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();
})(source, map, log, target);
8. Click on the Submit button.
Your form should look something like this:
9. From the Related Links click on the Transform link. This will display the Specify Import set and Transform map. The ForestAdmins_OU_LDAP - sys_user transform should already be present in the right-hand column.
NOTE: If you get an error like this:
You will need to go and reload your Data Source, and then run the Transform from that.
10. Click the Transform button. You should get a successful transform (all green).
11. Click on the Transform Histories link. You should see your import record and it should show that one or more new records were inserted. Go check your User table for the new records.
Lab 1.4: Test Everything Using Orchestration
Okay now let's test the round-trip.
1. Navigate to Workflow -> Workflow Editor.
2. Open the workflow we created in the last article: AD Server Tester
3. Open the Run Script Activity named Initialize.
a. Modify the workflow.scratchpad.firstname to be: R2D2
b. Modify the workflow.scratchpad.lastname to be: Robot
c. Click the Update button to save your work.
4. Run the workflow.
5. Now check the AD Server to see that R2 showed up where he should have.
6. Now check your instance's User table to see if R2 is present there as well:
Looks great!
So there you have it. You can now do the round-trip of creating a user in AD from an Orchestration Workflow, and seeing that user being transmitted via LDAP and saved in your User table, and ALL using VirtualBox with your Development Instance!
Cool, huh? 🙂
Resources:
For setting up ServiceNow LDAP I used the following resources:
Wiki: LDAP Integration Setup � If you bump into any issues this is a great resource!
Wiki: LDAP Integration via MID Server
Wiki: LDAP Integration Troubleshooting
Steven Bell
For a list of all of my articles: Community Code Snippets: Articles List to Date
Please Share, Like, Bookmark, Mark Helpful, or Comment this blog if you've found it helpful or insightful.
Also, if you are not already, I would like to encourage you to become a member of our blog!
