Microsoft

Blog Categories

Subscribe to RSS feed

Archives

Object Filtering with the Microsoft Notes Connector

Although I might be one of just a few currently working on the bleeding-edge technology of synchronizing Lotus Domino/Notes directories with Microsoft Active Directory via Exchange 2003, I figure I’d share this little tidbit of information. According to Microsoft Product Support this is not documented anywhere in TechNet and I had to open a ticket just to find this information out.

After successfully establishing Directory Synchronization with a Notes 6.5 directory, the default behavior of the native Notes Connector is to synchronize every known object in the Domino directory. From what I understand this behavior can not be modified for contacts and distribution lists, but it can be controlled for user objects. In a particular migration I only wanted to bring a certain number of objects into AD and had already narrowed that scope down to a specific list of probably 75% of the total number of people in Notes. I discovered there are two ways to filter out the unwanted objects and have the Notes Connector ignore these: either by setting the Notes Directory to exempt those objects from participation in any foreign directory synchronization, or by configuring the Connector itself to look for a specific attribute match and either filter in what I want, or filter out what I don’t.

Disable Foreign Directory Sync

To simply exempt a user from participating in any foreign directory sync, hence making it invisible to the Notes Connector, just edit a specific user in Domino Administrator and on the Administration tab change the value of the "Allow foreign directory synchronization" setting to No. (Yes, I see the irony in my test Notes Domain name).

image

This first option would have been the easiest to implement, but if the source Notes directory was already synchronizing with other foreign directories (e.g. MIIS), changing that setting could have a negative impact on the source organization’s current processes.

Attribute Filtering Rules

Here’s a list of Microsoft TechNet articles which cover how to configure the Notes Connector to either include or exclude objects by specific attribute matching rules. The main problem is take a look at the dates and applicable products; most reference Exchange 5.5 and are dated far older than anything I have in my refrigerator. My contact at MS Product Support said that these articles still apply to the current version of the Connector for Exchange 2003, but I was unable to get any kind of filtering to work correctly.

After a number of unsuccessful attempts to filter out any objects I noticed a line in the first article that stated to "modify the Exchconn.ini file located in the ExchsrvrConnectExchconn folder" but the problem was this file did not exist on the Exchange server were I installed the Connector. I previously found that the there were two instances of that exchconn.ini file, one located in the Exchsrvrbin folder and another in Exchsrvrconndatatables. When I added a filtering rule as per the instructions to either file, it would not work. I even experimented with moving a duplicate of the INI file into the path referenced above by the article but still no luck.

After triple-checking everything I ended up contacting MS Product Support as I could not find any further documentation on the functionality of this feature. After I walked through the entire configuration with someone from the mail connector team we decided that everything was correct and it ‘should’ have worked. After he did some research on his end he can back and found that the same behavior can also be configured via the registry and not just the INI file. As a test I reverted the INI file to it’s original configuration, made one simple change to the registry, and voila; it worked as expected. I had set a filter to match only for objects which had a CompanyName field equal to "Sync" and had previously entered that string into the Company field in roughly half of the Notes people in the directory. All previous tests created a new object in AD for all Notes people after an Immediate Full Reload from Notes to Exchange, but this time only the people with their Company set to "Sync" were created in AD. Success.

After a little more testing we decided that the INI file settings should have worked, but filtering was now working as expected via the registry change, so that was good enough for me.

Here is the setting required to enable object filtering via attribute matching in the registry:

Location: HKEY_LOCAL_MACHINESystemCurrentControlSetServicesLME-NOTESParameters
Name: DXANOTES_<UniqueFilterName>
Value: <NotesFieldName>,EQ,<FieldData>
Type: REG_SZ

<UniqueFilterName> can be any text string as long as it is unique, it is only used to identify the filter entry. I know you can have multiple filters but I have not experimented with how the order may be applied in the case of any conflicts. The suggested naming scheme of Filter1, Filter2, etc in the documentation leads me to believe it might be top-down alphabetical, but that is just a guess.

<NotesFieldName> can be any valid field name in the Notes directory, regardless as to how the Connector is configured. Even if an attribute value is not being migrated or matched via the Connector configuration it still can be used for filtering as the connector looks at the Notes objects data and searches for the field name supplied, and then attempts to match the value to the filter string.

EQ means to only include objects that match this rule (as in Equal) , and NE means to exclude any matches (as in Not Equal).

<FieldData> should include the actual string begin searched for in the Notes directory.

Below is a specific example of the registry setting in action:

Location: HKEY_LOCAL_MACHINESystemCurrentControlSetServicesLME-NOTESParameters
Name: DXANOTES_Filter1
Value: CompanyName,EQ,Sync
Type: REG_SZ

Clearly using a common attribute like CompanyName would not be a good idea for controlling the scope of directory synchronization as if any administrators changed that value on any objects then some users would stop synching and other unwanted accounts might appear in AD. I poked around in the Notes directory to look for a better field selection: one that was both unpopulated and hidden from the standard Notes Administrator view.

To take a look at the field names in Notes, right-click and choose Document Properties on a Notes User in the Domino Administrator. Select the second tab (with the icon of the right-triangle) and scroll down the list to view fields and values. I chose the inconspicuous carLicense field as it was not being used for storing any information and it’s not visible (nor modifiable) in the user’s properties.

image

In order to test using this field I needed to add a value to it. The simplest way I’ve found was to create an Agent in the domino Administrator to stamp (And another to null) the desired string. From the Domino Administrator, do the following on the People & Groups tab.

  1. Select Create > Agent…
  2. Enter any descriptive name, like "Set carLicense field to Sync".
  3. Close that properties window and then select Formula from the actions drop-down menu.
  4. Insert the cursor in the blank-window and add the following text:

field carLicense := "Sync"
select @All

Save the changes and close the current tab. Now select any people in the directory by highlighting or ticking the checkmark, and then choose the new agent in from the Actions menu. Afterwards look at the document properties for a selected user and verify the field has been correctly populated.

I then created a second agent to reverse the change to that field. Just perform the same steps as above but select a unique name for the agent, but change the "Sync" to simply "" and the field value will be removed when executing this agent.

In order to update the Notes Connector to now use this field and string for filtering, the DXANOTES registry setting was modified.

image

The end result is a clean, definitive way to control the exact scope of user objects to be synchronized from Notes into Exchange. Too bad the same can’t be performed on groups and contacts, but the useful life of the Notes Connector for Exchange 2003 is ticking down. As more and more migrations will target Exchange 2007, the more flexible Transporter can be used.

Leave a Reply