The Exchange Connector for Lotus Notes, new with Exchange 5.5, provides a
component that synchronizes one or more Notes Name & Address books with the Exchange directory. Synchronization is bi-directional and can include
custom recipients as well as mailboxes. The names and addresses of
distribution lists (Notes "groups") can be synchronized; however, the
membership of the DL or group is not carried in the shadow entry, and all
mail routing must be done on the system where the DL or group is
maintained.
As delivered, the product synchronizes a useful subset of the many
attributes supported by the two directories. The purpose of this article
is to explain how attributes are synchronized, and how you can customize
the process to meet local requirements. Through customization, you can do
either of the following:
- Change the list of attributes that are synchronized between Notes and
Exchange, adding or removing attributes.
- Change the way attributes are mapped between the systems.
The synchronization process uses four control files, which are located in
two subdirectories of the Connector's root directory. The UNC for the
Notes Connector's root directory is:
\\<servername>\connect$\exchconn
Important Note: If you edit these files using NotePad or another text
editor, ensure that you save backup copies of the shipped files. In
addition, do not use the [tab] key when making changes. All whitespace
characters should be entered using the space key.
Also, before you edit these files, ensure that directory synchronization is
not active (for example, by shutting down the Notes Connector). If you add
attributes to the synchronized schema or change any mapping rules for
existing attributes, you will most likely need to do a full directory
reload in one or both directions.
Schema definition files determine the subset of the native directory
schemas that are synchronized. Each line in the file that is not blank or
a comment defines a single attribute. The first column is a short name or
tag for a directory attribute used in the mapping rules (see below). The
second column has the maximum field length for the purpose of directory
synchronization. The total of all field lengths must not exceed
approximately 9500. The third column contains the internal name for the
attribute in the directory. See Appendix A for how to determine these
names for Exchange and Notes. For the Notes Address Book, the schema
definition includes a fourth column, which should be present but is not
used by the Connector.
The following definition of the Exchange directory schema is shipped in
Dxamex\amap.tbl:
ACCOUNT 32 Assoc-NT-Account
COMPANY 64 Company
DEPARTMENT 64 Department
FULLNAME 128 Display-Name
FIRSTNAME 64 Given-Name
ALIAS 64 Mail-nickname
OFFICE 64 Physical-Delivery-Office-Name
LASTNAME 64 Surname
NOTESADDR 128 Proxy-Addresses(NOTES:)
USNCreated 12 USN-Created
Initials 5 Initials
Title 32 Title
Phone 20 Telephone-Office1
MobilePhn 20 Telephone-Mobile
Fax 20 Telephone-Fax
The following definition of the Notes address book schema is shipped in
Dxanotes\amap.tbl:
FULLNAME 220 FullName 1
MAILDOMAIN 31 MailDomain 2
COMPANY 64 CompanyName NULL
DEPARTMENT 64 Department NULL
FIRSTNAME 64 FirstName NULL
LASTNAME 64 LastName NULL
LOCATION 128 Location NULL
SHORTNAME 8 ShortName NULL
Initials 5 MiddleInitial NULL
Title 32 JobTitle NULL
Phone 20 OfficePhoneNumber NULL
MobilePhn 20 CellPhoneNumber NULL
Fax 20 OfficeFAXPhoneNumber NULL
; do not change the following definitions
UNID 64 $$UNID NULL
DN 256 $$DN NULL
USNCreated 16 $$USN NULL
Mapping rule files define how attributes from one schema are mapped to
attributes in the other schema. Each non-blank, non-comment line is a rule
that assigns a value to a single attribute in an entry in the target
directory. The right-hand side of the rule is a string expression made up
of string constants, numeric constants, references to attributes in the
source directory, and built-in string manipulation functions.
The following rules for mapping Notes attributes to Exchange attributes
are shipped in Dxamex\mapnotes.tbl:
Alias = ISEQUAL( ShortName, "", SUBSTR( FullName, 1, 64 ), ShortName )
FullName = X500( FullName, "CN" )
FirstName = FirstName
LastName = LastName
Company = Company
Department = Department
Office = Location
Initials = Initials
; change the following rule only with care
TA = "NOTES:" Strip( FullName, ";", "L", "R" ) "@" MailDomain
; do not change the following rule
DN = UNID
Note that the DN and TA attributes were not defined explicitly in the
Exchange schema. These attributes are required for directory
synchronization and are always synchronized. The TA (Target-Address)
attribute is the Notes user's e-mail address and must be unique within the
Exchange directory. Although Notes does not enforce the uniqueness of this
name, for all practical purposes the name must be unique to allow the Notes
router to reliably deliver mail to the right mailbox. The DN (Distinguished
Name) mapping rule actually provides only a portion of the eventual full DN
created for the Notes entry in Exchange. The full DN is constructed by
concatenating the DN of the Import Container where Notes custom recipient
entries are stored, with the DN fragment created by the mapping rule.
The TA rule provides a good example of how the string expressions work.
For example, if the Notes user's full name and mail domain are "Denise
Graham/Sales/Acme Corp; Denise Graham; Graham" and "Acme-HQ", then this
rule will result in an Exchange TA field containing "NOTES:Denise
Graham/Sales/Acme Corp@Acme-HQ". See below for a full description of the
built-in mapping functions that are available.
The following rules for mapping Exchange attributes to Notes attributes
are shipped in Dxanotes\mapmex.tbl:
FullName = Trim( Strip( NotesAddr, "@", "R" ), "B" )
MailDomain = Trim( Strip( NotesAddr, "@", "L" ), "B" )
ShortName = Alias
LastName = ISEQUAL( LastName, "", FullName, LastName )
FirstName = FirstName
Company = Company
Department = Department
Location = Office
Initials = Initials
; do not change the following rules
UNID = "00000000-00000000-00000000-00000000"
USN = USNCreated
DN = DN
Mapping Rules use a simple macro language that allows you to define how to
create entries in different directory systems. An important part of this
macro language is the mapping functions that manipulate a series of
arguments you supply and return a result in the form of a string. Your
mapping rules can combine this result with other constant strings and
function calls to build up the overall result of the rule.
Mapping functions operate on strings and numeric constants. Strings can be
either attribute tags (the short names defined in the schema definition
file) from the source directory, or string literals. A string literal is
an actual sequence of characters enclosed in quotation marks, such as "Star
Mart", ".", or even " " (three spaces). Note that you cannot use the
real internal attribute names in mapping rules. You must use the attribute
tags defined in the schema definition files.
FUNCTION_NAME( arguments )
For example:
If this function is coded in a mapping rule, it will return the left-most
four characters of the contents of the Fullname field in the source
directory.
Functions can be combined with each other or with string literals, allowing
you to create arbitrarily complex result strings. A rule and the resulting
string it returns can be as long as 2,048 characters.
The list below represents all the built-in mapping functions; more complete
explanations and examples are provided later in this document.
AND()
Returns the concatenation of two non-null strings, or the null string if
either of the two strings specified is null.
CFGPARM()
Returns a value from the connector's INI file.
ISEQUAL()
Returns a configurable value, depending on whether or not two
expressions are equal.
LEFT()
Returns the left n characters of an expression, padded on the right if
necessary.
LOWER()
Converts a field to lower-case characters.
NAMEF()
Returns a person's first name or initial from a pre-formatted string.
NAMEL()
Returns a person's last name or initial from a pre-formatted string.
NAMEM()
Returns a person's middle name or initial from a pre-formatted string.
POS()
Determines the position of a particular string within an attribute.
PROPER()
Converts a name field to proper-name format.
REPLACE()
Converts a name field to proper-name format.
RIGHT()
Returns the right n characters of an expression, padded on the left if
necessary.
SUBSTR()
Returns a specified sub-string of a string, padded with extra characters
if necessary.
STRIP()
Locates the left-most or right-most occurrence of one string in another
and removes characters.
TRIM()
Returns a field with leading and/or trailing blanks removed.
UPPER()
Converts a field to upper-case characters.
WORD()
Returns a specified number of words from a string.
X500()
Extracts an attribute from an X.500-style hierarchical address.
Mapping Functions: Detailed Descriptions
Notational conventions:
UPPERCASE type
used for function names
[ ]
used to indicate optional arguments. If an optional argument is
omitted, its default value is assumed.
In the examples, each sample call is followed by the result it
produces. Although the examples use only string literals as arguments,
remember that each argument can itself be an arbitrarily complex string
expression, including nested function calls.
Syntax:
AND(exp1,exp2)
Description:
Returns the concatenation of two non-null strings, or the null string if
either of the strings involved is null.
Examples:
AND("A", "B" ) "AB"
AND ("", "B") ""
AND("A", "") ""
Syntax:
CFGPARM( exp1[,exp2] )
Description:
CFGPARM returns the value of a parameter in the Exchconn.ini file. Exp1
specifies the parameter whose value is to be returned; exp2 specifies the
section within the INI file. If the section is omitted, then the DXA's
home section is used. If neither the section nor the parameter is found,
the result is an empty string.
Examples:
CFGPARM( "executable") "lsdxamex.exe"
CFGPARM( "locale", "dxm") "English"
Syntax:
ISEQUAL( exp1, exp2, val1, val2 )
Description:
ISEQUAL returns the value of val1 if exp1 equals exp2, otherwise it returns
the value of val2.
ISEQUAL is not case-sensitive.
Examples:
ISEQUAL( "remote", "remote", "R", "L") "R"
ISEQUAL( "remote", "local", "R", "L") "L"
ISEQUAL( "remote", "REMOTE", "R", "L") "R"
Syntax:
LEFT ( field, length, [, pad] )
Description:
LEFT returns the left-most length characters of field. If field has fewer
than length characters, the result is padded on the right with the pad
character.
The default pad character is a blank.
Examples:
LEFT ( "416-862-7148", "3" ) "416"
LEFT ( "triple", "9" ) "triple "
LEFT ( "triple", "9", "x" ) "triplexxx"
Syntax:
LOWER ( field )
Description:
LOWER returns the value of field with any upper-case letters converted to
lower-case.
Examples:
LOWER ( "LinkAge" ) "linkage"
LOWER ( "Bonnie" ) "bonnie"
Syntax:
NAMEF ( field, [, style] )
Description:
If field contains a person's name in a specified format, NAMEF returns the
person's first name or initial. Two styles are supported:
- The name is in the form "First Middle Last".
- The name is in the form "Last, First Middle".
The default style is 1 if field does not contain a comma, 2 if it does.
Initials or strings of initials are treated as first or middle names. If a
name has only one part, it is considered both first and last name,
regardless of the style.
Examples:
NAMEF ( "Sarah Elizabeth Turner" ) "Sarah"
NAMEF ( "S. E. Turner" ) "S."
NAMEF ( "SE Turner" ) "SE"
NAMEF ( "Turner, Sarah E.", "2" ) "Sarah"
NAMEF ( "Madonna", "2" ) "Madonna"
Syntax:
NAMEL ( field, [, style] )
Description:
If field contains a person's name in a specified format, NAMEF returns the
person's last name. Two styles are supported:
- The name is in the form "First Middle Last".
- The name is in the form "Last, First Middle".
The default style is 1 if field does not contain a comma, 2 if it does.
Initials or strings of initials are treated as first or middle names. If a
name has only one part, it is considered both first and last name,
regardless of the style.
Examples:
NAMEL ( "Sarah Elizabeth Turner" ) "Turner"
NAMEL ( "S. E. Turner" ) "Turner"
NAMEL ( "Sarah Turner" ) "Turner"
NAMEL ( "Turner, Sarah E.", "2" ) "Turner"
NAMEL ( "Madonna") "Madonna"
Syntax:
NAMEM( field, [, style] )
Description:
If field contains a person's name in a specified format, NAMEF returns the
person's middle name or initial.
Two styles are supported:
- The name is in the form "First Middle Last".
- The name is in the form "Last, First Middle".
The default style is 1 if field does not contain a comma, 2 if it does.
Initials or strings of initials are treated as first or middle names. If a
name has only one part, it is considered both first and last name,
regardless of the style. Anything that is not identified as a first or last
name is considered a middle name.
Examples:
NAMEM ( "Sarah Elizabeth Turner" ) "Elizabeth "
NAMEM ( "S. E. Turner" ) "E. "
NAMEM ( "Turner, Sarah E." ) "E. "
NAMEM ( "Turner, Sarah", "2" ) ""
NAMEM ( "Turner, Sarah E.", "2" ) "E."
NAMEM ( "Turner, Sarah E. M", "2" ) "E. M."
Syntax:
POS ( field, target )
Description:
POS returns the position of the string target within field.
If the target is not in the field, POS returns zero.
Examples:
POS ( "Title: President", "Ti" ) "1"
POS ( "Title: President", ":" ) "6"
POS ( "Title: President", "Manager" ) "0"
Syntax:
PROPER ( field )
Description:
PROPER returns the value of field with lower-case and upper-case letters
converted to mixed-case, as if field were a proper name.
Examples:
PROPER ( "linkage" ) "Linkage"
PROPER ( "john") "John"
PROPER ( "o'malley" ) "O'Malley"
Syntax:
REPLACE ( field, what [,with] )
Description:
This mapping function enables you to remove specific characters from an ID
or replace selected characters with substitute characters. It scans field
for any characters in the what string and replaces them with the
corresponding character from the with string. If the with string is shorter
or is not provided (meaning that one or more characters in what have no
corresponding characters in with), those characters are elided (removed)
from field.
Examples:
REPLACE ("James Martin"," ","_") "James_Martin"
REPLACE ("Sales & Marketing Email Group"," ",".")
"Sales.&.Marketing.Email.Group"
REPLACE ("Constantine Ra[circumflex i]ch'al", " [circumflex i]'", ".i") "Constantine.Raichal"
Syntax:
RIGHT ( field, length [,pad] )
Description:
RIGHT returns the right-most length characters of field. If field has fewer
than length characters, the result is padded on the left with the pad
character. The default pad character is a blank.
Examples:
RIGHT ( "416-862-7148", "7" ) "62-7148"
RIGHT ( "416-862-7148", "8" ) "862-7148"
RIGHT ( "node", "5", "@" ) "@node"
Syntax:
STRIP ( string1, string2, [scan-from-direction] , [strip-toward-
direction]),
where
[scan-from-direction] = "L" | "R"
[strip-toward-direction] = "L" | "R"
Description:
STRIP locates the left-most or right-most occurrence of string2 in string1
and removes characters from the right or left, including string2. The value
for scan-from-direction determines whether STRIP looks for the left-most or
right-most occurrence of string 2 in string 1; the value for strip-toward-
direction determines whether characters are removed from the left or right
of where string2 starts.
If the either the scan-from-direction or the strip-toward-direction
parameter is omitted, the value for the missing parameter is assumed to be
the same as the one that is specified. If both these parameters are
omitted, the default for both is assumed to be "R" (right).
Examples:
STRIP ( "Senior Vice President", "Vice", "L" ) " President" (Note the
leading space)
STRIP ( "Senior Vice President", "Vice", "R" ) "Senior " (Note the
trailing space)
STRIP ( "Senior Vice President", " " , "L") "Vice President"
STRIP ( "Senior Vice President", " ", "R" ) "Senior Vice"
STRIP ( "Senior Vice President", " ", "R", "L" ) "President"
Syntax:
SUBSTR ( field, start [,length [, pad] ] )
Description:
SUBSTR returns the portion of field starting at position start, with length
characters, padded with the pad character if necessary.
The default for length is (length of string - start + 1). The default pad
character is a blank.
Examples:
SUBSTR( "Vice-President", "6" ) "President"
SUBSTR( "Vice-President", "2", "3" ) "ice"
SUBSTR( "Vice-President", "7", "9", "s" ) "residents"
SUBSTR( "Vice-President", "11", "4" ) "dent"
Syntax:
TRIM ( field [,option] )
Description:
TRIM returns field with leading or trailing blanks removed. Option
specifies whether to remove leading blanks (L) trailing blanks (R), or both
(B).
Examples:
TRIM ( " Title ", "B" ) "Title"
TRIM ( " Title ", "L" ) "Title "
TRIM ( " Title ", "R" ) " Title"
Syntax:
UPPER ( field )
Description:
UPPER returns the value of field with any lower-case letters converted to
upper-case.
Examples:
UPPER ( "LinkAge" ) "LINKAGE"
UPPER ( "Bonnie" ) "BONNIE"
Syntax:
WORD ( field, n [, m] )
Description:
WORD returns m blank-delimited words starting with the nth word in field.
WORD returns an empty string if field contains fewer than n words. The
default value for m is 1.
Examples:
WORD ( "one of a kind", "1" ) "one"
WORD ( "one of a kind", "1", "2" ) "one of"
WORD ( "one of a kind", "3", "2" ) "a kind"
WORD ( "one of a kind", "5" ) ""
WORD ( "Sarah E. Turner", "3" ) "Turner"
Syntax:
X500 ( address, field name [,index] )
Description:
X500 returns the contents of the named field for the specified address. If
the address has two or more components with the same field name, the index
value is used to specify the correct one.
The following X.500-type addresses are supported:
- Microsoft Exchange Canonical (for example,
/o=org/ou=site[/cn=container])
- Lotus Notes Canonical (for example, cn=name/ou=site./o=org/c=country)
- Lotus Notes Abbreviated Canonical (for example, name/site/org/country)
For example, suppose the value of the DN field is that provided in the
sample X500 address below:
/o=StarMart/ou=Sales Office/cn=Recipients/cn=Notes_Users
The function would provide the following result:
X500 ( DN, "ou") "Sales Office"
X500 ( DN, "o") "StarMart"
X500 ( DN, "cn", 2) "Notes_Users"
Appendix: How to determine the internal name of directory attributes
Both Exchange and Notes allow you to inspect internal names of directory
attributes and inspect detailed schema and content information for
specific attributes of a directory entry.
For the Exchange directory, run the Exchange Administrator with the /raw
option. Use shift-enter to view the attributes of a recipient object. You
will be able to view the detailed schema for recipients, including the
internal directory names for recipient attributes.
For the Notes address book, right-click the mouse on an address book entry
that contains the attributes of interest, and select Document Properties.
Select the Fields tab, and you will see a list box that shows you the
internal directory names for the attributes of the selected entry. You can
also display the contents of each attribute using this tab.
Note For Microsoft Exchange Server 2003 and Microsoft Exchange 2000 Server, the default path for mapping tables is C:\Program Files\Exchsrvr\CONNDATA\Dxamex.
- AMAP.TBL in the \Dxamex subdirectory defines the Exchange mailbox attributes that are to be synchronized.
- MAPNOTES.TBL in the \Dxamex subdirectory determines the attribute mapping from Lotus Notes to Exchange Server 2003. For example, the default path for this table is C:\Program Files\Exchsrvr\CONNDATA\Dxanotes.
- AMAP.TBL in the \Dxanotes subdirectory defines the Lotus Notes attributes that are to be synchronized.
- MAPMEX.TBL in the \Dxanotes subdirectory determines the attribute mapping from Exchange Server 2003 to Lotus Notes.