How to set up synchronization with LDAP

Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

You can synchronize person and group records from an LDAP server to Service Management via the On-Premise Bridge. When you configure the endpoint for the integration, you can define field mappings between the LDAP fields and the record fields in Service Management.

The following steps describe how to set up synchronization with LDAP.

Note

For more information about downloading, installing, and creating the On-Premise Bridge Agent, see How to use On-Premise Bridge agents on Windows or How to use On-Premise Bridge agents on Linux.
If you want to synchronize using the LDAPS protocol, make sure SSL is enabled on the LDAP server.
There is a Record to record mapping section for person records and for group records. You must define at least one mapping to save the endpoint. You can define mappings for both person and group records in the same integration, but you cannot add more than one mapping section for each record type in a single integration.

Download and install the On-Premise Bridge Agent.

Create an agent.

Specify the credentials.

Create an LDAP endpoint:

From the main menu, select Administration > Utilities > Integration > Endpoints.
Click Add.

Enter the endpoint details.

Field	Description
Endpoint type	Select LDAP integration.
Endpoint name	Type a name for the endpoint. Use only Latin letters and spaces.
Running on agent	Select the agent (installed in step 1 of the task) from the drop-down list.

Click Add.

Configure the endpoint:

Click Configure. The Endpoint Configuration dialog box opens.

Enter the endpoint details.

Field	Description
Connection configuration
Endpoint name	The name of the endpoint. Note This field is read-only.
Host name	Enter the name or IP address of the LDAP server.
Port	Enter the number of the port listened to by the LDAP server. The default is 389.
Credentials	Enter the credentials used to connect to the LDAP server. The full credentials are those defined as part of the agent to which the endpoint is connected. On the Microsoft Active Directory server, both Distinguished name and username login are supported. On the Apache DS server, only Distinguished name login is supported.
Scheduled integration interval	Select the interval between successive runs of the integration. The default value is 1 day. For example, if the current sync finishes at 10:00 AM on Monday, and the Scheduled sync interval is 1 day, the next sync will run at 10:00 AM on Tuesday.
Use SSL Encryption	Select this check box to run the sync using SSL encryption. Note Encryption is supported using TLS v1.1 and TLS v1.2 for Microsoft Windows 2008 R2 and above only.
Integration configuration
LDAP Server type	The supported LDAP server types are: Microsoft Active Directory 2008 Microsoft Active Directory 2012 Apache DS 2.0
Starting search directory	The root directory on the LDAP server where the data is stored.
Record to record mapping
Target record	Select Person or Group.
Source record	Enter the corresponding record type from LDAP.
Filter	The default filter is based on the selected record type (person or group). You can enter a custom filter to specify the relevant records for the integration. Example: To sync all people from groups 1 and 2 only, enter: (&(objectClass=person)(&(group=group1)(group=group2))). To sync all people in either level 1 or level 3, enter:(&(objectClass=person)(\|(level=level1)(level=level3))).
<Field mappings>	In each section, complete the following: Target fields. Select the record fields from Service Management to be mapped. If you select a field of type Enum, click the arrow button next to Map values. Select the target values from the drop-down list and enter the source values from LDAP. Click Add map value to add additional value mappings. Note It is possible to map multiple source values to the same target value. Source fields. Enter the corresponding fields from LDAP for the mapping. You can enter the fields in simple text or an Expression Language phrase. Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax. Mapping condition. Optionally, enter an Expression Language phrase defining a condition. The mapping applies only when the condition is satisfied. In each section, three default fields are provided. Click Add field to add additional field mappings. Click Remove next to any mapping to remove it. Important You must include mappings for all fields defined as mandatory for the selected record type.

Note When updating existing records, the sync identifies records based on their Upn. If the Upn field is mapped to the Email field in LDAP, for example, and multiple LDAP records have the same Email, they are mapped to the same record in Service Management. If there is a conflict in the record data between any of the LDAP records, an error is generated when the sync runs.

After completing the Integration configuration section, click the Test connection button to test the connection to the server.
Click Save.

Complete the Record to record mapping section for person records:

Enter the name of the person record type on the LDAP server in the Source record field.
Optionally, enter an Expression Language phrase as a filter in the Person filter field.
For the Language, Email, and Upn target fields, enter the corresponding fields from the LDAP records in the Source field column. The Upn field must be unique in Service Management person records. You can enter the fields in simple text or an Expression Language phrase.

Note In addition to the regular Expression Language functions, you can use the identification functions for LDAP integration described in Identification functions for LDAP integration.
Optionally, enter an Expression Language phrase as a condition for the field mapping in the Mapping condition column.
You can click Add field to add additional field mappings.

Complete the Record to record mapping section for group records:

Enter the name of the group record type on the LDAP server in the Source record field.
Optionally, enter an Expression Language phrase as a filter in the Group filter field.
For the Name and Upn target fields, enter the corresponding fields from the LDAP records in the Source field column. You can enter the fields in simple text or an Expression Language phrase.

Note In addition to the regular Expression Language functions, you can use the identification functions for LDAP integration described in Identification functions for LDAP integration.

The Group type target field is an Enum type field. Click the arrow button next to Map values and enter the LDAP values corresponding to the target values in the Source value column. Click OK.
Optionally, enter an Expression Language phrase as a condition for the field mapping in the Mapping condition column.
You can click Add field to add additional field mappings.

Click Request full sync run a full synchronization. For subsequent, on-demand, synchronizations, click Sync now to synchronize only the delta.

Note If you make any changes to the field mappings, you must run a full sync to update the field values of existing records based on the new mappings.

When the sync finishes, a status summary appears on the screen, displaying the total number of records synced as well as a breakdown by category: Added, Updated, Deleted, Unchanged, and Errors.

Note

There may be a delay between the end of the On-Premise Bridge task and the completion of the sync.
If an error occurred during the mapping of fields, the record is imported and is counted under Added/Updated in the summary, but the relevant fields are empty.
You can define enrichment rules to enrich the person and group data synced from LDAP. For more information, see Enrichment rules.

Go to Administration > Master Data > People > People to view the synchronized person records. Go to Administration > Master Data > People > Groups to view the synchronized group records.

LDAP integration limitations

The following limitations apply to the LDAP integration:

Deletion of records is not supported by the sync. If a record that exists in both LDAP and Service Management is deleted in LDAP, it is not deleted in Service Management after the sync.

The number of records imported from LDAP may not be equal to the total number of records added or updated in Service Management because multiple LDAP records may be identified with a single record in Service Management.

For the fields defined in the record to record mapping section, the data imported from LDAP is read-only in the user interface, with the exception of the Email field in person records when the value is not an actual email address, but uses a placeholder domain.

Many-to-many relationships are not supported by the sync.

When syncing a field with numeric data, the group separator is not preserved. For example, in the number 123,456.789, the comma is not preserved.

The userAccountControl attribute is relevant for Microsoft Active Directory only. Only the values 0 and 2 are supported.

If records were not imported due to an error that occurred during the sync, you must run the full sync again to import the missing records.