Custom Mapping: Mapping Syntax

Created: 2019-07-30 11:58:45
Modified: 2023-07-24 13:25:48
Tags: Custom Mapping Features UnitySync

It is important to use correct syntax when building your own map file. Below find descriptions of the various control characters:

Character Example Description
^ ^givenname^ This represents the first value of a Source attribute.
[ ] [objectclass] This represents all values of the enclosed attribute. This is handy when assigning all values of an attribute in one assignment. (Not used in ODBC)
~ ~sn~ This represents a UnitySync generated internal variable.
| top|person This is a multi-value separator. The example shows a literal assignment of a multi-valued attribute. Variables can be used as well: ^telephone^|^telephone1^
{ } {telephone} This performs a ‘pop’ function on the telephone attribute. The first value is assigned and removed from the Source variable. The next assignment by ^ or { } will be the next value of telephone. This option is not used in ODBC.
r| r|Addr=^Addr1^|^Addr2^ Preceding the Destination attribute name with r| indicates that instances of “ | ” in the Destination assignment will be treated as CR-LF (carriage return / line feed). This is only valid for multi-line Destination objects.

Using Reserved Characters as Literals

Some characters in map files are reserved for special use by UnitySync. If you ned these characters to be included literally in a custom mapping, you must ‘escape’ the character with a preceding \ (backslash) character. The following list identifies the escape sequence for each of the reserved characters:

Character Example
\] ]
\[ [
\{ {
\} }
\~ ~
\^ ^
\# #
\% %

For example, the following mapping appends the company attribute value surrounded by square brackets to the displayname:

displayname#256=~cn~ \[^company^\]

This mapping would result in displayname values as follows:

  • Oprah Winfrey [Harpo Productions]
  • Bill Gates [Microsoft]
  • Warren Buffet [Berkshire Hathaway]

LDAP Mapping Examples

Source attributes:

1 dn:uid=jsmith,ou=ABC Company
2 objectclass:top
3 objectclass:person
4 telephone:555-1212
5 telephone:653-2234
7 company:ABC Company
8 cn:Smith, John
9 address1:10 River Street
10 address2:Suite 100

Attribute Mappings:

1 dn=cn=~cn~,~struct~
2-3 objectclass=interorgperson|top
4 tel1={telephone}
5 tel2=^telephone^
6 mail=^mail^
7 company=Acme
8 last=~sn~ and first=~givenname~
9-10 r|address=^address1^|^address2^

IMPORTANT NOTE: *telephone and objectclass are multivalued fields.

How are the results determined?

In our configuration we have set display-parse=yes and display-firstlast=yes on the Display Name tab.

  • Line 1: Since the Source CN (Line 8 of the LDIF) is parsed using display-parse=yes and displayfirstlast= yes the internal variable of ~cn~ will be constructed. The ~struct~ variable autogenerates the rest of the dn string and builds any structure that needs to be built.
  • Lines 2&3: The Destination object class has two literal values ‘inetorgperson’ and ‘top’.
  • Line 4: Because the Source telephone field (Lines 4 & 5) have 2 values, the first value will have to be popped off. The {telephone} variable pulls off the value ‘555-1212’ and assigns it to tel1. What is left in the Source telephone field is one value ‘653-2234’.
  • Line 5: tel2 is assigned what’s left of the telephone field: ‘653-2234’.
  • Line 6: This is a straight attribute assignment.
  • Line 7: The Destination company attribute will be assigned ‘Acme’ for all objects.
  • Line 8: Because display-parse=yes the variable ~sn~ will be the result of the parsed CN (Source line 8). If the display-parse was set to no, ~sn~ would have been assigned Source attribute sn if it were available.
  • Lines 9&10: The preceeding r| indicates that the following “ | ” symbols will be translate to CR-LF. Therefore, the value of the Destination attribute “street address” will be:
    10 River Street
    Suite 100

So, our result looks as follows in the LDIF file:

1 dn:cn=John Smith,o=Acme
2 objectclass:inetorgperson
3 objectclass:top
4 tel1:555-1212
5 tel2:653-2234
7 company:Acme
8 last:Smith and first:John
9&10 Address::MjAgU29tZSBTdHJlZXQNClN1aXRlIDEwMA==

IMPORTANT NOTE: Multi-line attributes contain control characters (CR-LF). Therefore, LDIF standard requires that the attribute be base64 encoded, as show in Lines 9&10 above.

Share this article:

  1. Directify - Self Service

  2. Mimic - Replication

  3. UnitySync - Sync
  1. emPass - Sync
  1. Profiler
  2. SimpleSync