Platform SDK: Exchange Server

Importing and Exporting with DIRSYNC

Building and running DIRSYNC demonstrates a basic mechanism for synchronizing directories between a Microsoft Exchange Server system and a foreign mail system, or between Microsoft Exchange Server and a nonmail database. For example, the DIRSYNC agent can be integrated into a mail gateway application that coordinates address books between Microsoft Exchange Server and a foreign system such as PROFS.

The DIRSYNC sample application creates a file for export, or incorporates the changes from an import file to the directory. (Note: How the export file is used, or how to create the import file, is determined outside the scope of this sample application). The import and export files are identical, so if there is a Microsoft Exchange Server system at each end, DIRSYNC can be used both to export and import changes.

The following instructions explain how to build a gateway, run DIRSYNC to create an export file, and use DIRSYNC to import that file into the other system to incorporate its changes into the address book for two Microsoft Exchange Server sites. For purposes of this example, the two sites are created within the same organization. The following objects are created:

In this example, the sample gateway is installed on Server1 and Server2 to connect the sites together for DIRSYNC.

To create a gateway for DIRSYNC

  1. Gather the necessary information for creating the gateway:
  2. Install the sample gateway on both Server1 and Server2 following the instructions found in Sample Gateway and Applications.
  3. In the Address Type field, type the address type for the other site. For example, if one site is EDK and the other is SMTP, the SMTP site will have EDK typed in this field and the EDK site will have SMTP typed here. A proxy generation DLL that generates addresses of the other type must be associated with each site. For more information, see the Gateway Programmer's Reference.

    For this example, set the address type of both servers to EDK, which allows the PROXYGEN.DLL to be used as the proxy generation DLL.

  4. Verify that the sample gateway has been created on both servers by finding it in the Connections container within the Microsoft Exchange Server Administrator program for each site. See the Microsoft Exchange Server Administrator's Guide for more information.
  5. Create the following mailboxes:

To create a mailbox

  1. Start the Administrator program and connect it to the server on which you plan to create the mailbox.
  2. Change to the Recipients container.
  3. From the File menu, choose New Mailbox.
  4. Enter the information for the new mailbox. You can attach it to an existing Windows NT account or create a new account.
  5. Verify that the new mailbox has been created by finding it in the Recipients' container.

The following procedure demonstrates how to connect the two sites together through the gateway.

To connect two sites together through their gateways

  1. Start the Administrator program and connect it to Server1.
  2. Open the Connections container.
  3. Double-click the gateway icon to view its property sheet.
  4. Select the Sample Gateway property page. Find the Directory entry in the Outbound column. Change this entry to be the inbound directory of the other site. This path consists of the share name for the gateway plus \IN. For example: \\Server2\SAMPLEGW\IN.
  5. Follow the same procedure on Server2, connecting it to \\Server1\SAMPLEGW\IN. When you have finished, the OUT directory for each server should match the IN directory for the other server.

The following procedure demonstrates how to create a custom recipient on Server2 for Mailbox11. and a custom recipient on Server1 for Mailbox21. This allows the mailboxes to send test messages across the gateway.

To create a custom recipient

  1. At Server1, open the Recipients container and double-click Mailbox11. Select E-Mail Addresses.
  2. Find the EDK address type for the foreign system. The address is Mailbox11@Site1.Testorg.com.
  3. Start the Administrator program on Server2.
  4. Open the Recipients container.
  5. From the File menu, select New Custom Recipient.
  6. Fill in the fields for the custom recipient to match Mailbox11 information. The address of the custom recipient is the address you found on Server1, Mailbox11@Site1.Testorg.com. The address type is EDK.
  7. Click OK.
  8. Verify that the custom recipient has been created by making sure it appears in the Recipients container.
  9. Create a custom recipient on Server1 for Mailbox21 following the same procedure. This allows test messages to be sent in the opposite direction.

To make sure the gateway is operating properly, send several messages back and forth from Mailbox11 on Server1 through the gateway to Mailbox21 on Server2. When you start Microsoft Exchange client on the receiving computer, you should be able to see, open, and read the messages.

After the gateway is operating between the two sites, begin synchronization by exporting all existing mailboxes from one server to the other, then updating that server as changes occur.

To synchronize two sites

  1. Set up a new instance called INSTANCE1 (see the previous procedure). Use either the /SET command or the command line. This new instance should export information about mailboxes that have changed on Server1 to Server2. For example, export the Common-Name and Display-Name attributes for each mailbox to a file called SYNC1.
  2. Use INSTANCE1 to export all the existing mailboxes. This step should be followed even though custom recipients already exist at the other site. Add the /EXPFULL parameter on the command line (because this is the first export), but do not add it to the registry (because /EXPFULL will be used only once). For the first export, type the following command:
    DIRSYNC /EXPFULL INSTANCE1
  3. Import the attributes you exported from Server1 to Server2. At Server2, set up a new instance, INSTANCE2, to import the attributes that were exported from Server1 by INSTANCE1 (that is, Common-name and Display-name). Use the same name for the import file, SYNC1, that you used for the export file in INSTANCE1. Copy SYNC1 from Server1 to Server2. Type the following command:
    DIRSYNC INSTANCE2

    This command causes custom recipients for each mailbox exported from Server1 to be added to Server2.

  4. Verify that the custom recipients have been added by opening the Recipients container of the Administrator program on Server2 and viewing each mailbox.
  5. On Server2, create INSTANCE3 to export changes to Server1. Again, export the Common-Name and Display-Name for each mailbox. Select a different name for the export file than you selected for the export file from Server1. For example: SYNC2.
  6. Export all the mailboxes from Server2 to Server1 using INSTANCE3 along with the /EXPFULL parameter on the command line:
    DIRSYNC /EXPFULL INSTANCE3
  7. On Server1, create INSTANCE4 to import the changes from Server2 to Server1. Use the same file name, SYNC2, for your import file.
  8. Import the changes by copying SYNC2 from Server2 to Server1. Type the following command:
    DIRSYNC INSTANCE4
  9. Make some incremental changes on Server1. For example, add a new mailbox, Mailbox14. Change the display name for Mailbox12 on Server1. Delete Mailbox11 on Server1.
  10. Export the incremental changes using INSTANCE1 but not including the /EXPFULL parameter. Type the following command:
    DIRSYNC INSTANCE1
  11. Import these changes at Server2 by copying the newly created SYNC1 file from Server1 to Server2. Type the following command:
    DIRSYNC INSTANCE2
  12. Create incremental changes at Server2 in the same way you created changes at Server1. Export these changes to a new SYNC2 file by typing the following command:
    DIRSYNC INSTANCE3
  13. Import these changes at Server1 by copying the new SYNC2 file to Server1. Type the following command:
    DIRSYNC INSTANCE4

After you have established an import and export instance at each server they can be used to synchronize the two servers as further changes occur.

Should one server become disabled, another server at the site can be used for synchronizing, but the entire process — including the export of all the mailboxes — must be repeated between the servers. This is necessary because the attributes used to determine which mailboxes to export are specific to the now disabled server and the old instances cannot be used successfully.

Using DIRSYNC with Multiple Instances

DIRSYNC can be used to demonstrate how a single directory synchronization agent can coordinate requests from several sources, such as from two instances of the same gateway or from different gateways, with each source represented by a separate Windows NT Registry instance.

You can save multiple instances of DIRSYNC calls in the Windows NT Registry, but some precautions should be taken when running DIRSYNC with multiple instances:

If you are making incremental updates, create a different instance to run DIRSYNC from another container. Otherwise, DIRSYNC will use the state information stored from the first container and this may produce unpredictable results. However, if you request a full update with the /EXPFULL flag, you can use a single DIRSYNC instance to export from multiple containers or multiple directories.