WebSphere Everyplace Synchronization Server - defining device-specific custom field mappings for the Domino Adapter

Last updated: March 29, 2005

• Using device specific custom field mappings with the Domino Adapter

• Using Palm Address Book custom fields in a Domino custom Mapping Table Database

1. device specific custom field mapping
2. non-device specific custom field mapping
3. default field mapping

• Define the CUSTOMMAPPING property in ESSConfig.xml
• Define a device specific custom design template
• Example for Palm
• Restart the ESS Server

Using Palm Address Book custom fields in a Domino custom Mapping Table Database

Define the CUSTOMMAPPING property in ESSConfig.xml

1. Backup file <ESS_HOME>/caf/cfg/ESSConfig.xml


2. Edit file <ESS_HOME>/caf/cfg/ESSConfig.xml


3. Add a CUSTOMMAPPING property to the Lotus Domino BackEndManager Component section of ESSConfig.xml.  The CUSTOMMAPPING property needs to contain the USERAGENT and MAPID attributes similar to the example given here:

<COMPONENT CLASSNAME="com.lotus.sync.domino.BackEndManager" COMPONENT_TYPE="BackEndManager" DISABLED="false" STARTUP_SEQ_NUMBER="4" SHUTDOWN_SEQ_NUMBER="7" INSTANTIATION_TYPE="one-step" NUMBER_OF_OBJECTS="1">

      <PROPERTY NAME="AuthServer" VALUE="$dominoHost$"/>

      <PROPERTY NAME="MonitorUsername" VALUE="$CAuser$"/>

      <PROPERTY NAME="MonitorPassword" VALUE="$CApwd$"/>

      <PROPERTY NAME="TimeSyncInterval" VALUE="300"/>

      <PROPERTY NAME="CAName" VALUE="DOMINOCA1"/>

      <PROPERTY NAME="RemoveContentWhenPreventCopying" VALUE="$removeContent$"/>

      <URI NAME="http://$dominoHost$/" ACCESSTYPE="PASSTHROUGH"/>

      <CUSTOMMAPPING USERAGENT="IBM Palm SyncML Client 5.0.1.2"    MAPID="Palm"/>


 </COMPONENT>


where USERAGENT and MAPID are defined as follows:


USERAGENT

For the USERAGENT string, insert the user agent name for the device client. An administrator can specify as many user agents as they wish and they can use wildcards (* = any number of any character, ? = any single character). Wildcards can be used to avoid having to specify a mapping for each version of a user agent. When a device logs in, its user agent value will be compared first for an exact match to CUSTOMMAPPING entries containing no wildcards,  and next as a wildcard match based on the order of the CUSTOMMAPPING entries in the ESSConfig.xml file. If nothing is matched, then there is no device specific custom mapping for this device. If there is a match, then the MAPID value is appended to the users template name when searching for a mapping database match.


The USERAGENT string value can be determined for a particular device by synchronizing that device with ESS Usage Logging turned on. Usage logging can be enabled from the Administration Server Logging  portlet. To activate usage logging, select the Usage logging check box on the portlet and save the setting. After synchronizing the devce with ESS view the ESS_Usage_date.log file and find the entry for the username of the device. The last value on the log entry will be the USERAGENT string value. (e.g. "IBM Palm SyncML Client 5.0.1.2"). Here is an example log entry:


2004-12-04 02:45:17 y.yy.yy.yy x.xx.xx.xx username GET http://myserver.ibm.com/mail/mydata.nsf 200 176 "IBM Palm SyncML Client 5.0.1.2"





        MAPID

The MAPID string is assigned by the administrator and is used as a template name suffix to locate the correct custom field mapping database.





    Note: The USERAGENT and MAPID values are case sensitive.





4. Save the ESSConfiig.xml file. These changes are enabled when you Restart the ESS Server.

Define a device specific custom design template

1. Configure a custom Lotus Notes template as documented in the IBM WebSphere Everyplace Access V5.0 InfoCenter. See the following section:  Everyplace Synchronization Server-->Administering--> Working with the PIM adapters-->Configuring the Lotus Domino Adapter-->Configure custom Lotus Notes templates.
2. Append the MAPID value configured above on the CUSTOMMAPPING property in ESSConfig.xml to the end of your custom template name located in your custom MapDir.nsf file. For example, if MAPID="Palm" and the custom template name is StdR4PersonalAddressBook then change the custom template name to StdR4PersonalAddressBookPalm.
3. These changes are enabled when you Restart the ESS Server.
   

Palm device specific custom design template example using Palm Address Book custom fields in a Domino custom Mapping Table

1.  Copy the custom mapping directory database file MapDir.nsf from the <ESS_HOME)/NotesData/esm/custom directory to a system on which you can open and modify it with a Lotus Notes client.
2.  Copy all the files from <ESS_HOME>/NotesData/esm directory to same system as in step 1 but to a different directory.
3.  Create custom mapping table databases for the Domino address book templates.
   
ESS ships 3 address book mapping table databases (PersonMap.nsf, R6PersonMap.nsf, and iNotesPMap.nsf) for the Domino address book templates. Copy and rename these 3 database from the directory in  which they were copied  in step 2 to the directory with the MapDir.nsf file in step 1. It is suggested you rename the files to append  the MAPID value specified in the ESSConfig.xml (see Define the CUSTOMMAPPING property in ESSConfig.xmlsection). In this case the names for your custom mapping table databases would be PersonMapPalm.nsf, R6PersonMapPalm.nsf, and iNotesPMapPalm.nsf.



4. Copy all the address book template entries from the mapping directory database (MapDir.nsf in directory of step 2) and paste to the custom mapping directory database (MapDir.nsf of step 1)
a. Open both MapDir.nsf databases in a Lotus Notes client.

b. Copy all the entries from the mapping directory database whose Info Type field has a value of Contact.

c. Paste these entries to the custom mapping directory database.


5. Modify custom mapping directory database entries with MAPID value and custom mapping table database location.
a. Edit each entry using the Notes client and make the following changes:

Change the NTFName field value to append the MAPID value (e.g. Palm) for the device. Example: StdR6Mail would become StdR6MailPalm.  For entries that have a language suffix, the MAPID value goes after the suffix.  For example, StdR6Mail/de becomes StdR6Mail/dePalm.

Change the FieldMapDbName to point to the custom mapping table database. All custom mapping databases reside in the <ESS_HOME>/NotesData/esm/custom directory on the ESS system.  For example, if the FieldMapDbName value is esm/R6PersonMap.nsf then change it to esm/custom/R6PersonMapPalm.nsf.

b. Close the MapDir.nsf databases.


6. Modify the custom mapping table databases to map the Palm address book custom 1-4 fields to the Domino home address fields.
a. Open the custom mapping table databases (PersonMapPalm.nsf, R6PersonMapPalm.nsf, and iNotesPMapPalm.nsf) in the Notes client.

b. Edit the database properties and change the database Title to distinguish it from the base mapping table databases (this step is not required).

c. Edit the following 4 entries in each database as shown in tables below.
d. Close the databases.





FROM


Field Name	Sync Property Name	Sync Property ID	Sync Property Type	Field Type
StreetAddress	Home Street	Home Address	Text	Text
City	Home City	Home City	Text	Text
State	Home State	Home State	Text	Text
Zip	Home Zip Code	Home Zip Code	Text	Text





TO


Field Name	Sync Property Name	Sync Property ID	Sync Property Type	Field Type
StreetAddress	Field_User_1	User 1	Text	Text
City	Field_User_2	User 2	Text	Text
State	Field_User_3	User 3	Text	Text
Zip	Field_User_4	User 4	Text	Text



7. Copy the updated custom MapDir.nsf and the R6PersonMapPalm.nsf to the <ESS_HOME>/NotesData/esm/custom directory on the ESS server.
8. These changes are enabled when you Restart the ESS Server.

Restart the ESS Server

Trademarks

Microsoft, Active Directory, ActiveSync, Exchange, Pocket PC, Internet Explorer, Windows, Windows 2003, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.