GALSync: How to Customize TargetAddress on Export Attribute Flow

Purpose

The goal of this wiki page is to provide the necessary steps it takes to go through and set the TargetAddress attribute of a mail-enabled Contact object in a GalSync Solution to something specific using the mailNickName attribute and the msExchOriginatingForest attribute.

By the end of this document, you should be able to implement this into a test environment, and test this scenario and then implement it into production.

*NOTE: This wiki page is meant as a guide to illustrate how to customize the GalSync solution.  You do not have to utilize the same attributes documented here.  Your business rules may require that you utilize different attributes, or want the export to look differently.

Configuration Backup

This section will cover items to backup.  Backing up your configuration before you make a change like this is a best practice and/or a good habit.  It will allow you the ability to roll back a change if you it does not work for you.  Here our focus will be to backup:

1. The Target Management Agent
2. The Source Code

BACKUP: Management Agent

1. In the Synchronization Service Manager Console, select Management Agents
2. Select the Target Management Agent
   1. This is the management agent that will be exporting the modified TargetAddress attribute
3. From the Actions menu, select Export Management Agent
4. Save to a good location, and provide a good name for the agent
   1. Create a folder for your management agent backups, and store them there
   2. Suggested naming convention: <name of management agent>.xml
5. Click the Save button to save the file
6. Navigate to the location to confirm backup of the management agent

BACKUP: Source Code

Essentially, you will be making a code change to the GalSync.DLL.  This is a DLL that is delivered with the product.  It is very possible that in an hotfix update, or service pack install that we could overwrite the default GalSync.DLL file.  This is why we recommend to backup the source code, as well as rename the default GalSync Solution.  The steps below will guide you through backing up and renaming the default GalSync Solution.

1. Navigate to the location the source code location

   1. You will find the default GalSync Solution SourceCode in %programfiles%\Microsoft Identity Integration Server\SourceCode.  Depending on if you have renamed the GalSync Solution, you may find your GalSync solution here as well.

2. Make a copy of the GalSync Folder

3. Rename the copy to a unique name ( i.e. company acronym_galsync ) ( e.g. msft_galsync )

   *NOTE: Please note, that for the purpose of this wiki page, we will be using the name msft_galsync

4. Open Microsoft Visual Studio 2008 or Visual Studio 2010

5. Open your GalSync Solution (%programfiles%\Microsoft Identity Integration Server\Source Code\MSFT_GalSync)

   *NOTE: You may go through the conversion wizard, as the original project was developed using Visual Studio .NET 2003 with the Microsoft .NET Framework v1.1.  If you do get the wizard, then go through the wizard, and load the project normally.
   **
   **

6. In Solution Explorer, right click on the Project Name and choose Rename

7. Rename the solution to the name we provide for the copied folder ( e.g. msft_galsync )

8. From the Project menu item, select msft_galsync ( this would be the unique name you have provided for your solution )

9. Select Application ( It may already be selected by default )

10. Modify the Assembly Name so that it matches your new solution ( e.g. msft_galsync )

GUI Modifications - Updating the Management Agent

Now that we have backed up our management agent, and source code, we are ready to proceed with making the modifications.  This part of the wiki document will display the steps to make the modifications in the Target Management Agent to Export Attribute Flow ( EAF ).  The reason we are making the change in Export Attribute Flow ( EAF ) is because we want to leave the original value in the metaverse, and only change the value on export.

1. In the Synchronization Service Manager Console, select Management Agents

2. Select the Target Management

   1. This is the management agent that will be exporting the modified TargetAddress attribute

3. From the Actions menu, select Properties ( You can also just double click on the Management Agent to display the Properties )

4. From the menu on the left, select Configure Attribute Flow

5. Expand the section where: 
   Data Source Object Type = Contact and Metaverse Object Type = Person

6. Locate and Select the targetAddress attribute line
   Data Source Attribute = targetAddress and Metaverse Attribute = targetAddress

   

7. At the bottom, in the Build Attribute Flow section

   1. Mapping Type = Advanced

   2. Flow Direction = Export

      

8. In the listb box to the right for Metaverse Attribute

   1. Locate and Select mailNickName

   2. Press and Hold the CTRL Key

   3. Locate and Select msExchOriginatingForest

      *NOTE: If you do not have the Advanced option selected for Mapping Type, you will not be able to select both attributes

• Click the Edit button

• In the Advanced Export Attribute Flow Options Dialog Window

  1. Choose Rules Extension ( Selected by Default )

  2. Flow rule name: _MyNewTargetAddress

     

• Click the Ok button

• In the top section, you should see

  1. Data Source Attribute = targetAddress

  2. Metaverse Attribute = mailNickName, msExchOriginatingForest

  3. Type = Rules Extension

     

• The GUI modifications are complete.

  Source Code Modifications

  The GUI modifications are complete, and now we are ready to modify the source code.  This section of the wiki will cover the necessary steps to make the source code modifications.

  It will be beneficial if you have some knowledge of working with Microsoft Visual Basic .NET, as the GalSync solution is written using Microsoft Visual Basic .NET. 

  We will be focusing on the GalMA.vb file, which is the Management Agent Extension for GalSync.  We will be working in the MapAttributesForExport Sub Routine.

  Update Build Output Path ( Very Important )

  The build update path is where the compiled version of the DLL is written too.  By default, it will be referencing the Extensions folder under:

  • MIIS / ILM: %programfiles%\Microsoft Identity Integration Server\
  • FIM: %programfiles\Microsoft Forefront Identity Manager\2010\Synchronization Service

  We want to ensure that we do not overwrite the DLL without making a backup copy of it first.  We also do not want to overwrite the GalSync.XML file.  If by chance you do overwrite the GalSync.XML file, follow the information found in the Microsoft Knowledge Base Article 948167.  

  The steps below will guide you through updating the build output path.

  1. If not already open, open the MSFT_GALSYNC solution ( i.e. company acronym_galsync )
  2. %programfiles%\Microsoft Identity Integration Server\Source Code\GalSync\MSFT_GalSync.sln
  3. Update the Project Properties
     1. From the Project menu, select GalSync Properties
     2. Select the Compile Tab
     3. Click the Browse Button beside the textbox for "Build Output Path"
     4. Click the New Folder button, just to the left of the word Tools at the top
     5. Call the folder New GalSync Builds ( Provide a name that is unique, and explains what it is for )
     6. Click the Ok Button
     7. Click the Open Button
     8. Build update path should now be New GalSync Builds

  Modify the Source Code

  1. In Solution Explorer, double click on GalMA
  2. Press CTRL+F to bring up the Find Window
  3. Type: (without the quotes) "MapAttributesForExport" and then press the ENTER key

     1. This should tak you to the Public Sub MapAttributesForExport around line 276 in a default GalSync Solution.
        *NOTE: You can identify the line number by looking on the status bar in the lower right. (Example: Ln276)

     2. Look within this Sub Procedure for "Select Case FlowRuleName"

     3. Insert a few blank lines under the "Select Case FlowRuleName" and then copy and paste the following Case Statement

        *NOTE: A few things to note here:

        1. ** If the _MyNewTargetAddress does not match exactly, including case sensitive, to what is in the Advanced Export Attribute Flow Options Dialog, then this code will never be hit.**
        2. If you are using your own Flow Rule Name, ensure that you update the copy and paste, and that it matches your  Flow Rule Name in the Advanced Export Attribute Flow Options Dialog.

        _MyNewTargetAddress Case Statement Code

        By mailNickName and msExchOriginatingForest

        Case "_MyNewTargetAddress"
         
        Try
         
        csentry("targetAddress").Value = "smtp:" & _
         
        mventry("mailNickName").Value & "@" & _
         
        mventry("msExchOriginatingForest").Value
         
        Catch ex As Exception
         
        Throw New  Exception("Exception Occurred"  & vbCrLf & _
         
        ex.Message.ToString() & _
         
        vbCrLf & ex.InnerException.Message.ToString())
         
        End Try
        

        By First Name.Last Name and msExchOriginatingForest

         

        Case "_MyNewTargetAddress"
         
        Try
         
        csentry("targetAddress").Value = "smtp:" & _
         
        mventry("givenName").Value & "." & _
         
        mventry("sn").Value & "@" & _
         
        mventry("msExchOriginatingForest").Value
         
        Catch ex As Exception
         
        Throw New  Exception("Exception Occurred"  & vbCrLf & _
         
        ex.Message.ToString() & _
         
        vbCrLf & ex.InnerException.Message.ToString())
         
        End Try 
        

         

  Build Solution - Compiling source code modifications

  1. You should still be in Microsoft Visual Studio
  2. From the Build menu, select Build Solution
  3. Navigate to the New GalSync Builds folder we created above in the Update Build Output Path section
  4. You will find 2 - 3 files here
     1. MSFT_GALSYNC.DLL
     2. GALSYNC.XML
     3. MSFT_GALSYNC.XML

  Testing New Code - Test the updates you just made

  It is very important to test your new source code prior to allowing it to run in your production environment.  We strongly urge you to have a development/test environment.  If you do not have a test environment, ensure that you backup your existing GalSync.DLL.

  1. In the Extensions folder, make a backup copy of your MSFT_GALSYNC.DLL
  2. Copy, just the MSFT_GALSYNC.DLL from the New GalSync Builds folder to the Extensions folder
  3. GUI Changes:
     1. In the Synchronization Service Manager Console, select Tools > Options
     2. Click the Browse button beside Rules Extension Name
     3. Select MSFT_GALSYNC.DLL
     4. Click the Ok button
  4. View the Properties of each Management Agent, and select the Configure Extensions Tab
  5. Click the Browse button, and select MSFT_GALSYNC.DLL
  6. Test your solution
     1. You may want to use some export testing methods, by reviewing the wiki page:
        How to test the exporting of data before it is exported

  Additional Resources

  FIM LANDING PAGE: Resource Wiki and Troubleshooter Wiki Index