LDAP Mappings tabs

A Directory Synchronisation configuration contains a group mapping for mapping LDAP groups to Content Manager, and a user mapping, for mapping LDAP users to Content Manager. Both are configured in the same way.

A mapping consists of a list of rules, and a list of searches. When Directory Synchronisation is performed, the LDAP searches are executed, and the rules are then applied to each LDAP entry returned by the search.

When synchronising a LDAP entry to a location, the rules in the rules list are applied in order, one after the other. Rules can be configured to set a number of writeable properties on a Content Manager location, as well as writeable properties on the first Address or Electronic Address child object of the location. The same Content Manager property can be set by multiple rules, in which case the last applicable rule will be the one that sets the property.

Rules can be applied either unconditionally, or conditionally. Conditions are set by specifying that a particular LDAP attribute should match a particular text pattern. Text patterns can be matched literally, or matched using wild card or regular expression logic. If using regular expressions, regular expression captures can be specified and the captured values can be used when setting the property value.

Variable substitutions can be used to set the value of a Content Manager property. Valid variables can refer to LDAP attributes, or to regular expression captures if regular expression matching is enabled. If a variable is not resolved, for example if a LDAP attribute is not present, the variable will be substituted with an empty string value.

Note that variable substitutions can only be used with text format Content Manager properties.

Rules can be marked as Required. If a Required rule has a LDAP attribute condition, and the condition is not fulfilled by the given LDAP entry, then the synchronisation of that LDAP entry does not proceed, and the LDAP entry will not be considered part of the synchronisation set.

Rules also have a Link to Existing option, which allows the Directory Synchronisation tool to map LDAP entries, to pre-existing unsynchronised Content Manager locations. If Link to Existing is specified for a rule, then before creating a new location to synchronise to, the Directory Synchronisation logic will first search for an existing unsynchronised location with a property value matching that of the rule. If such a location is found, that location is then synchronised with the given LDAP entry. If such a location is not found, or if multiple matching locations are found, a new location is created instead.

If Content Manager business logic is violated when applying a rule, an error will be raised when saving the location, and an error message will be written to the Directory Synchronisation log. Synchronisation will then proceed with another LDAP entry.

Configuring Rules

  • To create a new rule, right-click under Rules and click Add.
  • To copy an existing rule, right-click on the existing rule and click Copy.
  • To edit a rule, double-click on the rule, or right-click on the rule and click Edit.
  • To change the order of the rules, right-click on a rule and click Move Up or Move Down.
  • To remove a rule, right-click on the rule and click Remove.
  • Property Name - property name in  Content Manager
  • Property Value - property value in  Content Manager. This may be a text field, for text properties, and otherwise a drop-down field, for non-text properties.
  • Require Matching LDAP Attribute - select this option to set an LDAP attribute that must be matched before the rule is applied.
    • LDAP Attribute Name - the name of an LDAP attribute on the LDAP entry, to match against. If left blank, the rule will be considered unconditional, and applicable to all LDAP entries.
    • LDAP Attribute Pattern - a pattern to match the LDAP attribute against.
    • LDAP Attribute Matching Type - determines the type of matching logic to use when matching the LDAP attribute. Possible values are:
      • Exact - the pattern must match the attribute value exactly
      • Substring - the pattern must be a sub-string in the attribute value
      • Wild Card - the pattern is a wild card matching expression, using * and ?
      • Regular Expression - the pattern is a regular expression
      • Case Sensitive - whether the pattern is case sensitive. This applies to all 4 matching types.
  • Require Matching LDAP Filter - select this option to set an LDAP filter that must be matched before the rule is applied. The required filter is a standard LDAP search expression, that is, anything that can be understood by the LDAP server.

Enabled - enables the current rule when running the synchronisation.

Required for Synchronisation - the LDAP entry will only be synchronised if this rule is applicable.

Link to Existing Locations - the property value calculated by this rule will be used to look up existing Content Manager locations, and if a unique unsynchronised location is found, that location will be synchronised to the LDAP entry.

The Run Rules on DN button is used to test the rules against a particular LDAP entry. Enter the Distinguished Name of the LDAP entry in the text field next to the button, and then press the button to run the entire rule set against that particular LDAP entry. A detailed log will be produced showing the effect of each rule.

Rule Examples

Example 1:
Property Name: Email Address
Property Value: $(userPrincipalName)
This rule will set the Email Address property to the value of the userPrincipalName attribute. If the userPrincipalName attribute is not present, the Email Address will be set to an empty string.

Example 2:
Property Name: Email Address
Property Value: $(userPrincipalName)
LDAP Attribute Name: objectClass
LDAP Attribute Pattern: person
LDAP Attribute Matching Type: Exact

This rule functions just as rule 1, but will only be applied to LDAP entries with a objectClass attribute with the value of person.

Example 3:
Property Name: Network Login
Property Value: CORP\$(sAMAccountName)
LDAP Attribute Name: objectClass
LDAP Attribute Pattern: person
LDAP Attribute Matching Type: Exact
Link to Existing: True

This rule uses a variable substitution to assemble a value for the Network Login property. For example if the sAMAccountName attribute contains the value JoeBloggs, Network Login will be set to CORP\JoeBloggs.

Because Link to Existing is True, if any existing location has the same value for Network Login, the existing location will be synchronised, instead of creating a new location.

Even if the LDAP entry is moved to a different location in the LDAP directory, Directory Synchronisation will still be able to synchronise the moved LDAP entry to the same Content Manager location, by using this rule to link on the Network Login property.

Example 4:
Property Name: Network Login
Property Value: $(1)\$(2)
LDAP Attribute Name: ntUserDomainId
LDAP Attribute Pattern: ^(.*)\:(.*)
LDAP Attribute Matching Type: Regular Expression
Link to Existing: True

This rule uses a regular expression to pick out domain and user name components from the ntUserDomainId attribute. The regular expression contains two captures, and these are included in the property value as $(1) and $(2).

For example if ntUserDomainId is ASIAPACIFIC:JoeBloggs, Network Login will be set to ASIAPACIFIC\JoeBloggs.

Example 5:
Property Name: User Type
Property Value: Records Manager
LDAP Attribute Name: memberOf
LDAP Attribute Pattern: *Records Manager*
LDAP Attribute Matching Type: Wild Card

This rule sets the User Type property of the location, to Records Manager, if a LDAP memberOf attribute is present with a value that contains Records Manager. The same effect could be achieved by using Sub-string matching.

For example, this rule would apply to a LDAP entry with a memberOf attribute with the value CN=Records Managers,CN=Groups,DC=corp,DC=com.

Configuring Searches

  • To create a new search, right-click under Searches and click Add.
  • To copy an existing search, right-click on the existing search and click Copy.
  • To edit a search, double-click on the search, or right-click on the search and click Edit.
  • To change the order of the searches, right-click on a search and click Move Up or Move Down.
  • To remove a search, right-click on the search and click Remove.
  • Search Base - enables you to select the base node in the LDAP directory under which you want to retrieve entries, for example, CN=Builtin, DC=trim, DC=lab
  • Search Scope - enables you to select how deep you wish to search in your directory hierarchy:
    • Base - returns items on the selected base level only.
    • One Level - returns items one level down in the hierarchy.
    • Sub-tree - returns all items in the complete hierarchy below the selected base level. Some directory servers will return an error if this search exceeds their internal search limits. In this case, use one of the other options to find a further search base entry lower in the hierarchy.
  • Search Filter - enables you to filter the search, using standard LDAP syntax, to return a specific set of search results. The search filter can be quite complex and can be used to refine the number and type of LDAP entries returned.
  • Enabled - enables the current search when running the synchronisation.
    For more information on search filters, see LDAP Search Filters.

    Testing searches
    The Run Search button is used to execute a search and view the results. The results will be written to the DS log for examination by the Directory Synchronisation administrator.

    The Run Rules on Search button is used to run the configured rule set against all the results of a search. A log will be produced, analogously to when running the entire Directory Synchronisation.