GALSync: How to Provision Contacts to Specific OU Units Based Upon an Originating Forest

  • Article

The Global Address List Synchronization Solution (GALSync) allows you to take a mail-box enabled user from one forest, and create a mail-enabled contact object in another forest, allowing the ability to share Global Address Lists (GALs).

However, by default, GALSync puts all of the mail-enabled contacts into a single Organizational Unit (container).

The goal of this document is to provide the necessary steps and details on how to provision the mail-enabled contacts from multiple forests into separate Target Organizational Units.

This enables companies that have multiple management agents for multiple exchange forests to put the mail-enabled contact objects into separate organizational units.

The following steps are involved in this process:

  1. Configuring the Sync Engine 
  2. Configuring Active Directory
  3. Updating the GALSync solution
  4. Testing the GALSync solution

Configuring the synchronisation engine (ILM/FIM/MIM)

To enable the sync engine to make the provisioning decision, your source management agents need to populate the metaverse with an attribute that can used by your provisioning code to determine the source of an object.

For the scenario in this article, the msExchOriginatingForest attribute is used for this purpose.

All contributing management agents need to populate this attribute in the metaverse with a fully qualified distinguished name of the originating forest.

The following section provides the configuration steps.

Verifying the existence of msExchOriginatingForest

  1. In the Identity Manager select Management Agents.
  2. Select the Management Agent to where you will be pulling users, or importing users.
  3. From the Actions menu select Properties.
  4. Within the Management Agent properties, select Configure Attribute Flow.
  5. Expand Data Source Attribute Object Type: User to Metaverse Attribute Object Type: Person (User -> Person).
  6. In the list of configured attribute flows, locate msExchOriginatingForest in the Metaverse Attribute column.
  7. If it does not exist, then follow the below steps to add it:
    1. From the Metaverse Attribute list, select msExchOriginatingForest.
    2. Select Advanced as Mapping Type
    3. Select Import as Flow Direction
    4. To open the Advanced Import Attribute Flow Options dialog, click New.
    5. Select Constant
    6. In the Constant textbox, type the Exchange Originating Forest Fully Qualified Display Name (FQDN)
    7. To close the Advanced Import Attribute Flow Options dialog, click OK.
    8. To apply your configuration, click OK.

 

Note

You have to verify that all source management agents are configured to populate msExchOriginatingForest.

 

Configuring Active Directory

In this section, we will cover how to create the OrganizationalUnit structure(OU) in the Active Directory in order to have this work for us.

It is recommended that you have a starting OU for the Target Contacts, so that you can use that in the code later on, and in the Target Contacts container of the Export Management Agent.   

  1. Go to the Domain Controller that you will be separating the contact objects.
  2. On the Domain Controller, open Active Directory Users and Computers (ADUC).
  3. If you do not already, create a general target container for your contact objects:
    1. Select the Root
    2. From the Action menu, select New, and then Organizational Unit.
    3. Provide a Name (i.e. GALSync Target Contacts).
    4. Click OK.
    5. Verify that the OU is now created off of the root, and that it is selected.
  4. If not already selected, select the GALSync Target Contacts OU:
    1. From the Action menu, select New, and then Organizational Unit.
    2. Provide a name that is unique for the forest contacts that you will be putting here.
    3. Click OK.
    4. This creates an OU under the GALSync Target Contacts OU.
    5. Repeat these steps for each forest contacts that you will need.

 

Updating the GALSync solution

This section will walk us through step by step on how to update the GALSync solution to enable provisioning of mail-enabled contacts into separate Target Organizational Units.

It is important that you have the above steps completed before moving to this section as to avoid synchronization errors when testing the solution.

To update your GALSync solution, you perform the following steps:

  1. Creating a backup of your GALSync solution
  2. Updating the Build Output Path
  3. Modifying the provisioning code
  4. Building the solution

 

Creating a backup of your GALSync solution

As a first step, you need to backup and change the name of your GALSync solution

  1. Navigate to the location of your GALSync source code.

    (By default it is in %programfiles%\Microsoft Identity Integration Server\SourceCode)

  2. Make a copy of the GALSync Folder.

  3. Rename the copy to a unique name - e.g. msft_GALSync.

  4. Open Microsoft Visual Studio (2005, 2008 or 2010)

  5. Open the GALSync Solution (%programfiles%\Microsoft Identity Integration Server\Source Code\MSFT_GALSync)

    Note

You may go through a conversion wizard, as the project was originally developed in Visual Studio .NET 2003 using .NET Framework v1.1.

If you do get the wizard, go through the wizard, and “*Load Project Normally*”.

  1. In Solution Explorer, right click on the project name and choose Rename.

  2. Give it a unique name (i.e. MSFT_GALSync)

  3. From the Project menu, select unique name GALSync properties.

  4. Select Application. (it may already be selected by default)

  5. Modify the Assembly Name so that it matches your new solution name. (e.g. MSFT_GALSync)

 

Updating the Build Output Path

You need to update the Build Output path to prevent the GALSync.XML file from being overwritten.

This is a configuration file that holds the different GALSync Management Agents we have built in the Identity Manager.

If by chance you do overwrite this file, follow the steps outlined in KB 948167 (http://support.microsoft.com/kb/948167).

  1. If not already open, open the MSFT_GALSync Solution ("%programfiles%\Microsoft Identity Integration Server\Source Code\GALSync\MSFT_GALSync.sln")
  2. Update Project Properties: (we do this to prevent the GALSync.XML (configuration file) from being overwritten with each new build of GALSync)
    1. From the Project menu select GALSync Properties.
    2. Select the Compile tab.
    3. To open the Select Output Path dialog, click Browse.
    4. To create a new folder, click New Folder and assign New GALSync Builds to it.
    5. Doubleclick the new folder, and then click Select Folder.
    6. Verify that your Build output path is set to the new New GALSync Builds folder.

Modifying the provisioning code

In this section, you find the required modification steps for your provisioning code.

  1. In Solution Explorer, doubleclick GalMV

  2. In your source code, locate Create a DN for the new object.

  3. You should notice the word Try just above the comment line that you are on.

  4. In the line following the Try statement, add the following code:

    '//////////////////////////////////////////////////////////////////////////////
'// SAMPLE CODE
'// PURPOSE: Illustrate how to have contact objects exported to different
'// organizational Units.
'//
'// MEMORY VARIABLES:
'// myTargetOrganizationalUnit: Sets the Target Organizational Unit for us
'// myOriginatingForest: Captures the originating forest information from the 
'// metaverse person object type (msExchOriginatingForest attribute).
'// we force it to lower case to be sure that we can match the data.

 Dim myTargetOrganizationalUnit As String = ""
 Dim myOriginatingForest As String = mventry("msExchOriginatingForest").Value.ToLower()

 '// Sets the OU to Provision to
 If myOriginatingForest = "sample.microsoft.com" Then
    myTargetOrganizationalUnit = "ou=Sample MSFT Contacts, " '// the comma is needed

 ElseIf myOriginatingForest = "sample.net" Then
    myTargetOrganizationalUnit = "ou=Sample CONTACTS, " '// the comma is needed 

'// NOTE:
'// If you have additional forests, you will need to add additional ElseIF 
'// statements to match those conditions.
'// END NOTE:

End If
'// END OF SAMPLE CODE
'//////////////////////////////////////////////////////////////////////////////

  5. In your source code, replace MA.EscapeDNComponent(rdn).Concat(MAConfig.SynchronizationOU) with MA.EscapeDNComponent(rdn).Concat(myTargetOrganizationalUnit & MAConfig.SynchronizationOU)

  6. Build the Solution.

 

Building Solution

In this section you find the required steps for building the solution.

  1. In Microsoft Visual Studio, from the Build menu, select Build Solution.
  2. Copy the new MSFT_GALSync.DLL file from New GALSync Builds folder to %programfiles%\Microsoft Identity Integration Server\Extensions folder.

 

Testing the solution

In this section, you will find the steps for testing the updated solution.

The test consist of a verification that the updated solution provisions to the correct OU.

To test the solution:

  1. You will need to do Full Import (Stage Only) first as we have modified the Active Directory schema and will need to import that structure/schema information into the metaverse.
  2. If this information is not there, you will receive errors such as “missing parent” in the Stack Trace.
  3. You can confirm this through the following steps:
    1. Select the importing management agent.
    2. To open the Search Connector Space dialog, from the Actions menu, select Search Connector Space.
    3. In the Scope list, select RDN.
    4. In the RDN textbox type OU=.
    5. Click Search.
    6. If the new organizational unit exists in the metaverse, it will be listed here.
  4. You will then need to do a Full Synchronization because of the Schema and Management Agent changes done.
  5. Once you have completed the Full Synchronization follow the steps to confirm before export:
    1. Select the management agent.
    2. To open the Search Connector Space dialog, from the Actions menu, select Search Connector Space.
    3. Click Search.
    4. Locate and doubleclick a user object type to display the properties for that user object.
    5. To open the Preview dialog, click Preview.
    6. Click Generate Preview.
    7. Click Connector Updates.
    8. You should have a record indicating the operation “added”.
    9. Doubleclick this record.
    10. Review the DistinguishedName(DN): information.
    11. You should see the objects new contact folder within the DN.

See Also