Custom Mapping: Mapping Syntax
Created: 2019-07-30 11:58:45Modified: 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
6 mail:jsmith@abc.com
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
6 mail:jsmith@abc.com
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.