Sdílet prostřednictvím

Developing a Call-Based Export Management Agent

  • Článek

The primary responsibility of a management agent is to provide a bidirectional identity data transfer mechanism that enables Microsoft® Identity Integration Server 2003 (MIIS 2003) to import identity data from a connected data source and export identity data to a connected data source. MIIS 2003 provides rich, built-in support for various connected data sources, such as Active Directory® directory service, Microsoft SQL Server™, and even flat files that are built into MIIS 2003.

If your scenario includes a connected data source for which no built-in management agent exists, or if your scenario requires features that MIIS 2003 does not include in its built-in management agents, you can develop your own management agent. This custom management agent is known as an Extensible Connectivity Management Agent (ECMA). To exchange data with a connected data source, the ECMA architecture supports a file-based import interface, a file-based export interface, and a call-based export interface.

What This Document Covers

This document is part of a series of documents that outline the initial development process for an ECMA. After you complete this document, you will be able to successfully export identity data from the metaverse into an XML file of a new ECMA by using the call-based export interface.

The following illustration shows the setup for connected data sources that are used for the scenario in this document.

Setup for connected data sources

The scenario in this document is based on the following management agents:

  • One Management Agent for Delimited Text Files that contributes identity data

  • One ECMA that consumes identity data from the metaverse, and then exports it into an XML file

For more information on management agents, see Management Agents in MIIS 2003 (https://go.microsoft.com/fwlink/?LinkID=91962).

Prerequisite Knowledge

This document assumes that you understand basic MIIS 2003 concepts. For information on MIIS 2003 features and functionality, see the following documents:

This document assumes that you have a basic understanding of the Microsoft Visual Studio® .NET development system. A description of advanced coding practices for Visual Studio .NET is beyond the scope of this document.

Audience

This document is intended for information technology (IT) planners, systems architects, developers, and IT personnel who plan and develop a connected data source extension for MIIS 2003.

Time requirements

The procedures in this document require 40 to 60 minutes for a new user to complete. An experienced MIIS 2003 user can complete them in 20 to 30 minutes.

Note

These time estimates assume that you have already set up and configured the testing environment and that it is ready for testing to begin.

Scenario Description

Fabrikam, a fictitious corporation, has to export identity data to a connected data source for which no built-in management agent exists. To better understand the complexity of developing a connected data source extension, Fabrikam develops a proof-of-concept solution. The solution uses a call-based export interface to export identity data to an XML file.

The testing environment

To complete the procedures in this document, you must have a stand-alone server running MIIS 2003 Service Pack 2 (SP2) that has Microsoft Visual Studio 2005 installed. To install MIIS 2003 SP2, you must install Microsoft SQL Server 2000 or Microsoft SQL Server 2005 on the server running MIIS 2003.

Implementing the Procedures in This Document

In this document, you develop an ECMA to export data to a connected data source for XML data files. The topics in this section describe how to develop an ECMA. You must implement the procedures in the order that they are presented.

  1. Create the schema and the sample data files

  2. Update the metaverse schema

  3. Develop the ECMA DLL

  4. Create the management agents

  5. Enable Object Provisioning

  6. Configure run profiles

  7. Test the configuration

Create the schema and the sample data files

To use the ECMA described in this document, you must create the following files:

  • One text file that contains the object schema definition

  • One text file that contains source identity data for a full import operation

The schema file has the attribute names for the identity objects that the scenario in this document uses. MIIS 2003 requires this schema file to configure the Management Agent for Delimited Text Files and the ECMA.

The identity object used for the scenario in this document has the following attributes:

  • objectclass

  • delta

  • anchor-attribute

  • name

  • email

You must include these attributes in the coma-separated schema definition file, which contains only the following code:

objectclass, delta, anchor-attribute, name, email

The schema definition file also defines the XML structure that you use to store the identity object information in the XML file of the ECMA when you run an export run profile:

<sample-objects>
    <object>
        <objectclass/>
        <delta/>
        <anchor-name/>
        <name/>
        <email/>
    </object>
</sample-objects>

The data file that you use for the full import operation contains identity objects named Object1 and Object2. The following code shows the content of this file.

objectclass,delta,anchor-attribute,name,email
Person,Add,1,Object1,Object1@fabrikam.com
Person,Add,2,Object2,Object2@fabrikam.com

To create the object schema definition file

  1. In Appendix A, copy the text, and then paste it into a new Notepad file.

  2. Save the Notepad file on your local drive as C:\MyECMASchema.txt.

To create the identity data source file

  1. In Appendix B, copy the text, and then paste it into a new Notepad file.

  2. Save the Notepad file on your local drive as C:\FullImportSample.txt.

Note

You must save the schema and the sample data files with the same name, and to the same location, as described in the previous procedures because the name and the location of these files are hard-coded in the import component code for the scenario in this document.

Update the metaverse schema

To simplify the provisioning logic, you create one new metaverse object type: ECMAPerson. The following attributes are required for this object type:

  • ObjectID

  • ObjectName

  • mail

  • displayName

ObjectID and ObjectName are new attributes that you must create. The displayName and the mail attributes are from the existing metaverse schema.

The following illustration shows the newly-created object types in Metaverse Designer, a feature of MIIS 2003.

New object types in Metaverse Designer

Custom Attribute Attribute name Attribute type

Attribute 1

ObjectID

String (indexable)

Attribute 2

ObjectName

String (indexable)

To update the metaverse schema

  1. In MIIS 2003, open Identity Manager.

  2. Switch to Metaverse Designer.

  3. To open the Add Attribute to Object Type dialog box, on the Actions menu, click Create Object Type.

  4. In the Object type name box, type ECMAPerson.

  5. From the Available attributes list, select mail, and then select displayName.

  6. For each row in the table immediately above this procedure, perform the following steps:

    1. To open the New Attribute dialog box, click New attribute.

    2. In the Attribute name box, type the attribute name shown for that row in the table.

    3. From the Attribute type list, select the attribute type shown for that row in the table.

    4. To add the new attribute to this object type, click OK.

  7. To add the new object type, click OK.

Develop the ECMA DLL

As noted earlier, in this document, you develop an ECMA to export object information to an XML data file that you store in the data folder for the ECMA. For a call-based export, the ECMA framework provides the following procedure calls to generate the export data:

  • BeginExport

  • ExportEntry

  • EndExport

To create the target export data file, your code initializes an in-memory data structure when MIIS 2003 calls BeginExport during an export run. Then, your code reads the export data and inserts it into the in-memory XML structure during each call to ExportEntry. Finally, your code stores the in-memory structure in an target XML file that it stores in the data folder for the ECMA when MIIS 2003 calls EndExport to complete an export run.

To develop an ECMA DLL, you perform the following steps:

  1. Create the ECMA framework.

  2. Implement the export component.

  3. Build the ECMA DLL.

Create the ECMA framework

The first development steps for an extensible management agent are always the same. You must perform the following steps:

  1. Create a new class library project.

  2. Add a reference to the Microsoft.MetadirectoryServices DLL.

  3. Implement the required interfaces.

Create a new class library project

The code for an ECMA is encapsulated in a DLL. To develop a DLL, you must create a class library project.

To create a new class library project

  1. Start Visual Studio .NET.

  2. To open the New Project dialog box, on the File menu, click Project, and then click New.

  3. From the Templates list, select Class Library.

  4. In the Name box, type MyCallBasedExportECMA, and then close the New Project dialog box.

Add a reference to Microsoft.MetadirectoryServices.dll

You must add a reference to Microsoft.MetadirectoryServices.dll to each project that is related to ECMA.

The following illustration shows the Solution Explorer after you add the DLL to a project.

Call-Based Export MA

Note

If References is not visible in the console tree in Solution Explorer, on the Project menu, click Show All Files.

To add a reference to the Microsoft.MetadirectoryServices.dll

  1. To open the Add References dialog box, on the Project menu, click Add Reference.

  2. On the .NET tab, click Microsoft.MetadirectoryServices dll.

  3. Close the Add References dialog box.

  4. At the beginning of your code, type Imports Microsoft.MetadirectoryServices.

Implement the required interfaces

The ECMA supports the following interfaces:

  • IMAExtensibleFileImport

  • IMAExtensibleFileExport

  • IMAExtensibleCallExport

Solution Explorer after the .dll has been added

The following table shows the interfaces that you must implement according to the various configuration scenarios that you can use for the ECMA.

Step types Export modes Interfaces to implement

Import and Export

Call-based
  • IMAExtensibleFileImport

  • IMAExtensibleCallExport

Import and Export

File-based
  • IMAExtensibleFileImport

  • IMAExtensibleFileExport

Import

Call-based
  • IMAExtensibleFileImport*

  • IMAExtensibleCallExport

Import

File-based
  • IMAExtensibleFileImport*

  • IMAExtensibleFileExport

Export

Call-based
  • IMAExtensibleFileImport

  • IMAExtensibleCallExport*

Export

File-based
  • IMAExtensibleFileImport

  • IMAExtensibleFileExport*

Note

The server running MIIS 2003 requires you to implement all of the interfaces shown in the preceding table. However, in this type of connected data source extension, the server running MIIS 2003 uses only the interfaces with the asterisks (*). For required interfaces that are not used by the server running MIIS 2003, we recommend that you throw the EntryPointNotImplementedException exception in their methods.

To implement the required interfaces, you must type Implements <name of the interface> under the class definition of your code, and press ENTER. When you press ENTER, MIIS 2003 adds the definitions for the procedures that an interface implements to your code automatically. As the preceding table shows, you must implement the MAExtensibleFileImport and IMAExtensibleCallExport interfaces for the scenario covered in this document.

The following code shows the abbreviated version of the ECMA code after you implement the required call-based export interfaces.

Imports Microsoft.MetadirectoryServices

Public Class MyCallBasedExportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleCallExport

    Public Sub GenerateImportFile(…) Implements … 
    End Sub

    Public Sub BeginExport(…) Implements …
    End Sub
   
    Public Sub EndExport(…) Implements…
    End Sub

    Public Sub ExportEntry(…) Implements…
    End Sub    
End Class

To implement the required interfaces

  1. In the ECMA code, change the class name from Class1 to MyCallBasedExportECMA, and the press ENTER.

  2. Type Implements IMAExtensibleFileImport, and then press ENTER.

  3. Type Implements IMAExtensibleCallExport, and then press ENTER.

Implement the export component

To implement the export component, you must provide the code to exchange data between the ECMA and a connected data source. For the scenario in this document, your code creates an in-memory XML file, and then saves its content as an XML file in the data folder for the ECMA. To work with XML data in your code, you must import the following namespace into your code:

System.XML

A call-based export component consists of three export-related procedures. Each of these procedures must access the in-memory representation of the XML export data. The shared access to the in-memory XML data is implemented in the form of a global variable named m_xmlDoc.

To keep the solution flexible, avoid using hard-coded parameters, such as file names and file locations, in your code. The ECMA framework provides a convenient mechanism to specify the values for these parameters when you configure a management agent on the Configure Additional Parameters page. The names of the parameters that you specify when you configure the management agent must match the parameter names that you use in your code. Later, you can modify the parameter values without having to modify your code again.

The following table shows the parameters for the scenario in this document.

Parameter Description

ExportFileName

The name of the target XML file

XMLRoot

The XML root element

ObjectElementName

The name of the object element in the target XML file

DeltaElementName

The name of the delta element in the target XML file

In the ECMA framework, the values for these parameters are provided by the export procedure named BeginExport. For parameter values that must be accessed by the other procedures of the call-based export component, you must implement additional global variables. For the scenario in this document, you implement additional global variables for the parameters that name the target XML file, the XML object element, and the XML delta element.

The following code shows the abbreviated version of the code after you have implemented all required interfaces and defined the global variables.

Imports Microsoft.MetadirectoryServices
Imports System.Xml

Public Class MyCallBasedExportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleCallExport
    Dim m_xmlDoc as XmlDocument = nothing
    Dim m_szExportFileName as String = ""
    Dim m_szObjectElementName as String = ""
    Dim m_szDeltaElementName as String = ""

    Public Sub GenerateImportFile(…) Implements … 
    End Sub

    Public Sub BeginExport(…) Implements …
    End Sub
   
    Public Sub EndExport(…) Implements…
    End Sub

    Public Sub ExportEntry(…) Implements…
    End Sub

You implement the first call-based export component of the ECMA as a procedure named BeginExport. MIIS 2003 calls this procedure only once during each export run. This procedure initializes your call-based export component. For the scenario in this document, the BeginExport procedure performs the following actions:

  1. Reads the values of the additional parameters and initializes global variables

  2. Creates a new, in-memory XML document

  3. Loads the document root element

The BeginExports procedure has a variable named configParameters. This variable contains the custom parameters that you specified when you configured the ECMA. Your code reads these parameters from the configParameters variable of the BeginExport procedure, and then initializes the global variables m_szExportFileName, m_szDeltaElementName and m_szObjectElementName. Next, your code initializes the global variable for the XML in-memory document, and then assigns the corresponding configParameters value for the root element to the XML document. The following code shows the abbreviated version of the BeginExport procedure:

    Public Sub BeginExport(…) Implements …
       Try
            m_szExportFileName = _
                 configParameters("ExportFileName").Value
            m_szObjectElementName = _
                 configParameters("ObjectElementName").Value
            m_szDeltaElementName = _
                 configParameters("DeltaElementName").Value
            m_xmlDoc = New XmlDocument
            m_xmlDoc.LoadXml(configParameters("XMLRoot").Value)
       Catch ex As Exception
          Throw ex
       End Try
    End Sub

Your code implements the second call-based export component of the ECMA as a procedure named ExportEntry. The code calls this procedure for each object that has pending export changes. For example, if three objects in the connector space of the ECMA have pending export changes, the procedure is called three times.

For the scenario in this document, the ExportEntry procedure performs the following actions:

  1. Creates a new XML element for the changed object

  2. Attaches the new object element for the changed object to the XML in-memory tree

  3. Attaches a delta element that contains the modification type to the object element

  4. Loops through the list of changed attributes

  5. Attaches to the object element a changed attribute element that contains the name and value of the attribute

  6. The ExportEntry procedure provides the modification type and changed attributes as parameters. Your code reads these values, and then initializes the XML element representing the changed object with them. The following code shows the abbreviated version of the ExportEntry procedure:

    Public Sub ExportEntry(…) Implements …
       Try      
            Dim objElem As XmlElement
            objElem = m_xmlDoc.CreateElement(m_szObjectElementName)
            m_xmlDoc.DocumentElement.AppendChild(objElem)

            Dim myElem As XmlElement
            myElem = m_xmlDoc.CreateElement(m_szDeltaElementname)
            myElem.InnerXml = modificationType.ToString
            objElem.AppendChild(myElem)

            Dim changedAttribute As String
            For Each changedAttribute In changedAttributes
                myElem = m_xmlDoc.CreateElement(changedAttribute)
                myElem.InnerXml = _
                    csentry(changedAttribute).Value.ToString
                objElem.AppendChild(myElem)
            Next
        Catch ex As Exception
            Throw ex
        End Try    End Sub

The last call-based export component of the ECMA is implemented as a procedure named EndExport. This procedure closes all open resources and releases allocated memory. For the scenario in this document, this procedure also writes the in-memory XML representation of the export data into a file. The following code shows the abbreviated version of the ExportEntry procedure:

   Public Sub EndExport() Implements …
       Try
            Dim filePath As String
            filePath = MAUtils.MAFolder.ToString + _
                       "\" + m_szExportFileName
            m_xmlDoc.Save(filePath)
            m_xmlDoc = Nothing
       Catch ex As Exception
            Throw ex
       End Try
    End Sub

To implement the export component

  • Copy the code from Appendix C, and then replace the complete code of your project with it.

Build the ECMA DLL

Before you build the ECMA DLL, you modify the output path to build the new extension into the MIIS 2003 extensions folder.

To modify the default output path of the new extension

  1. To open the Properties tab, on the Projects menu, click MyCallBasedExportECMAProperties.

  2. Click the Compile tab.

  3. To open the Select Output Path dialog box, click Browse.

  4. Browse to the Microsoft Identity Integration Server Extensions folder.

    This folder is located at %Program Files%\Microsoft Identity Integration Server\Extensions.

  5. To select this folder, and to close the Select Output Path dialog box, click Open.

To build the ECMA DLL

  • On the Build menu, click Build Solution.

Create the management agents

For the scenario in this document, you must create two management agents: one Management Agent for Delimited Text Files and one ECMA. The topics in this section describe how to configure these management agents.

Create the Management Agent for Delimited Text Files

To create the Management Agent for Delimited Text Files, you use the Create Management Agent Wizard.

To create the Management Agent for Delimited Text Files

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. To start the Create Management Agent Wizard, on the Actions menu, click Create.

  4. Specify the required parameters for each page, and then click Next.

    Separate instructions for each page follow this procedure.

  5. To create the management agent, click Finish.

Create Management Agent page

On this page, you select the type of management agent that you want to create, and then name it.

To complete the Create Management Agent page

  1. From the Management agents for list, select Delimited text file.

  2. In the Name box, type MyFileMA, and then click Next.

Select Template Input File page

On this page, you provide the template input file, the code page, and the file format of the template input file. The following illustration shows an example of this.

The Select Template Input File page

To complete the Select Template Input File page

  1. In the Template Input File box, type C:\MyECMASchema.txt.

  2. From the Code Page list, select Western Europe (Windows), and then click Next.

Configure Delimited Text Format page

On this page, you define how to interpret the data in the source data file. The following illustration shows an example of this.

The Configure Delimited Text Format page

To complete the Delimited Text Format page

  1. On the Delimited Text Format page, select the Use first row for header names check box.

  2. From the Text qualifier list, select the quotation mark ("), and then click Next.

Configure Attributes page

On this page, you specify all required configuration parameters for the attributes. For the scenario in this document, you must define the correct anchor, object class, and change type attribute.

The definition of all attributes consists of a selection of the appropriate attribute from the schema attributes. The following illustration shows the Advanced dialog box after you configure the object class and the change type attribute.

The Configure Attributes page

To complete the Configure Attributes page

  1. To open the Set Anchor dialog box, click Set Anchor.

  2. From the Available attributes list, select anchor-attribute, and then click Add.

  3. To close the Set Anchor dialog box, click OK.

  4. To open the Advanced dialog box, click Advanced.

  5. Click Object classattribute, and then, from the Object class attribute list, select objectclass.

  6. From the Change type attribute list, select delta.

  7. To close the Advanced dialog box, click OK, and then click Next.

Map Object Types page

On this page, you define object classes. For the scenario in this document, you must define one object class—Person. The following illustration shows the Map Object type dialog box after you define the new object type.

The Map Object Types page

When you finish all of the procedures in this document, extend this scenario with additional object classes, and then familiarize yourself with using them.

To complete the Map Object Types page

  1. To open the New Object Class dialog box, click New.

  2. In the New Object class box, type Person.

  3. To close the dialog box, click OK, and then click Next.

Define Object Types page

You do not have to configure anything on this page.

To complete the Define Object Types page

  • Click Next.
Configure Connector Filter page

You do not have to configure anything on this page.

To complete the Connector Filter page

  • Click Next.
Configure Join and Projection Rules page

On this page, you configure the required join and projection rules. For the scenario in this document, you must configure a projection rule for the Person object type.

The following illustration shows the Configure Join and Projection Rules dialog box after you have applied the projection rule.

The Configure Join and Projection Rules page

To complete the Configure Join and Projection Rules page

  1. In the Data Source Object Type column, select Person.

  2. To open the Projection dialog box, click New Projection Rule.

  3. Select Declared.

  4. From the Metaverse object type list, select ECMAPerson.

  5. To close the Projection dialog box, click OK, and then click Next.

Configure Attribute Flow page

On this page, you provide the import and export attribute flow rules. For the scenario in this document, you must configure direct import attribute flow mappings for the anchor, the name, and the email attribute of the connected data source to the ECMAPerson object.

The following illustration shows the Configure Attribute Flow dialog box after you have applied all attribute flow rules for the user object.

The Configure Attribute Flow page

The following table shows the data source and metaverse attribute pairs for which you must configure a flow rule.

Flow rule Data source attribute Metaverse attribute

Rule 1

anchor-attribute

ObjectID

Rule 2

email

mail

Rule 3

name

ObjectName

Rule 4

name

displayName

To complete the Configure Attribute Flow page

  1. In the Data source object type box, select Person.

  2. In the Metaverse object type box, select ECMAPerson.

  3. Under Mapping Type, select Direct.

  4. Under Flow Direction, select Import.

  5. For each row in the table immediately above this procedure, perform the following steps:

    1. From the Data source attribute list, select the data source attribute shown for that row in the table.

    2. In the Metaverse attribute list, select the metaverse attribute shown for that row in the table.

    3. Click New, and then click Next.

Configure Deprovisioning page

You do not have to configure anything on this page.

To complete the Configure Deprovisioning page

  • Click Next.
Configure Extensions page

You do not have to configure anything on this page.

To complete the Configure Extensions page

  • To create the management agent, click Finish.

Create the ECMA

To create the ECMA, you use the Create Management Agent Wizard.

To create an ECMA

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. To start the Create Management Agent Wizard, on the Actions menu, click Create.

  4. Specify the required parameters for each page, and then click Next.

    Separate instructions for each page follow this procedure.

  5. To create the management agent, click Finish.

Create Management Agent page

On this page, you select the type of management agent you want to create, and then name it.

To complete the Create Management Agent page

  1. From the Management agents for list, select Extensible Connectivity.

  2. In the Name box, type MyCallBasedExportECMA, and then click Next.

Configure Connection Information page

On this page, you select the step types, the export modes, and the name of the connected data source extension. If required, you also specify a server name, a user name, and a password for the remote system to which the management agent connects. The following illustration shows an example of this.

Call-Based Export MA

To complete the Configure Connection Information page

  1. Under Specify the step types supported by this management agent, select Export.

  2. Under Specify the export mode supported by this management agent, select Call-based.

  3. To open the Select file dialog box, click Browse.

  4. From the Files list, select MyCallBasedExportECMA.dll.

  5. To close the Select file dialog box, click OK, and then click Next.

Configure Additional Parameters page

On this page, you specify additional connection parameters for the connected data source extension.

For the scenario in this document, you add connection parameters for the schema file, the full import data file, and the delta import data file. As mentioned earlier, MIIS 2003 passes this parameter collection as the input parameter to the BeginExport procedure of the import component.

The following illustration shows the Configure Additional Parameter dialog box after you specify all required parameters.

Call-Based Export MA

Connection Parameter Parameter name Value

Parameter 1

ExportFileName

Export.xml

Parameter 2

XMLRoot

<sample-objects/>

Parameter 3

ObjectElementName

object

Parameter 4

DeltaElementName

delta

To complete the Configure Additional Parameters page

  • For each connection parameter in the table immediately above this procedure, perform the following steps:

    1. To open the Parameter dialog box, click New.

    2. In the Parameter name box, type the parameter name shown in the table.

    3. In the Value box, type the value shown in the table.

    4. To close the Parameter dialog box, click OK, and then click Next.

Select Template Input File page

On this page, you provide the template input file, the code page, and the file format of the template input file. The following illustration shows an example of this.

The Select Template Input File page

To complete the Select Template Input File page

  1. In the Template Input File box, type C:\MyECMASchema.txt.

  2. From the Code Page list, select Western Europe (Windows).

  3. From the File format list, select Delimited, and then click Next.

Configure Delimited Text Format page

On this page, you define how to interpret the data in the source data file. The following illustration shows an example of this.

The Configure Delimited Text Format page

To complete the Delimited Text Format page

  1. On the Delimited Text Format page, select the Use first row for header names check box.

  2. From the Text qualifier list, select the quotation mark ("), and then click Next.

Configure Attributes page

On this page, you specify all required configuration parameters for the attributes. For the scenario in this document, you define the correct anchor, object class, and change type attribute.

To define each attribute, you select the appropriate attribute from the schema attributes.. The following illustration shows the Advanced dialog box after you configure the object class and the change type attribute.

The Configure Attributes page

To complete the Configure Attributes page

  1. To open the Set Anchor dialog box, click Set Anchor.

  2. From the Available attributes list, select anchor-attribute, and then click Add.

  3. To close the Set Anchor dialog box, click OK.

  4. To open the Advanced dialog box, click Advanced.

  5. Click Object class attribute.

  6. Under Object class attribute, select objectclass.

  7. From the Change type attribute list, select delta.

  8. To close the Advanced dialog box, click OK, and then click Next.

Map Object Types page

On this page, you define the object classes. For the scenario in this document, you must define one object class—Person. The following illustration shows the Map Object type dialog box after you define the new object type.

The Map Object Types page

When you finish the procedures in this document, extend this scenario with additional object classes, and then familiarize yourself with using them.

To complete the Map Object Types page

  1. To open the New Object Class dialog box, click New.

  2. In the New Object class box, type Person.

  3. To close the New Object Class dialog box, click OK, and then click Next.

Define Object Types page

You do not have to configure anything on this page.

To complete the Define Object Types page

  • Click Next.
Configure Connector Filter page

You do not have to configure anything on this page.

To complete the Connector Filter page

  • Click Next.
Configure Join and Projection Rules

You do not have to configure anything on this page.

To complete the Configure Join and Projection Rules page

  • Click Next.
Configure Attribute Flow page

On this page, you provide the export attribute flow rules. For the scenario in this document, you configure direct export attribute flow mappings for the name attribute and the email attribute of the ECMAPerson object to the connected data source.

The following illustration shows the Configure Attribute Flow dialog box after you have applied all attribute flow rules for the Person object.

The Configure Attribute Flow page

The following table shows the data source and metaverse attribute pairs for which you must configure a flow rule.

Flow rule Data source attribute Metaverse attribute

Rule 1

email

mail

Rule 2

name

ObjectName

To complete the Configure Attribute Flow page

  1. In the Data source object type box, select Person.

  2. In the Metaverse object type box, select ECMAPerson.

  3. Under Mapping Type, select Direct.

  4. Under Flow Direction, select Export.

  5. For each row in the table immediately above this procedure, perform the following steps:

    1. From the Data source attribute list, select the data source attribute shown for that row in the table.

    2. From the Metaverse attribute list, select the metaverse attribute shown for that row in the table.

    3. Click New, and then click Next.

Configure Deprovisioning page

You do not have to configure anything on this page.

To complete the Configure Deprovisioning page

  • Click Next.
Configure Extensions page

You do not have to configure anything on this page.

To complete the Configure Extensions page

  • To create the management agent, click Finish.

Enable object provisioning

To enable object provisioning, you perform the following steps:

  1. Write code for the provisioning method.

  2. Build a metaverse rules extension.

  3. Enable the metaverse rules extension.

First, you write code for the provisioning method. During provisioning, MIIS 2003 detects only whether a change was applied to an object that has the new type. If MIIS 2003 detects a change, it calls another custom method, ProvisionToECMA.

The following code shows an abbreviated version of the provisioning code.

Public Sub Provision(…) Implements …
   Try
      If (mventry.ObjectType.Equals("ECMAPerson")) Then _
         ProvisionToECMA(mventry)
   Catch ex As Exception
      Throw ex
   End Try
End Sub

The ProvisionToECMA method reacts only if no connector to the connector space of the ECMA is available. If a connector is required, the method creates a new connector, and then initializes its anchor attribute with an appropriate value. For the scenario in this document, the anchor attribute value is the same as the value in the source identity data file.

The following code shows the ProvisionToECMA method.

Private Sub ProvisionToECMA(ByVal mventry As MVEntry)
   Try
     Dim myMA As ConnectedMA = _
                 mventry.ConnectedMAs("MyCallBasedExportECMA")
     If myMA.Connectors.Count <> 0 Then Exit Sub

     Dim obCS As CSEntry
     obCS = myMA.Connectors.StartNewConnector("Person")
     obCS("anchor-attribute").Value = mventry("ObjectID").Value
     obCS.CommitNewConnector()

   Catch ex As Exception
      Throw ex
   End Try
End Sub

Next, you build the metaverse rules extension, which is based on the provisioning code in Visual Studio .NET.

Finally, you enable the metaverse rules extension in MIIS 2003. The following illustration shows the Options dialog box in MIIS 2003, which you use to create the rules extension.

Building a metaverse rules extension

To build a metaverse rules extension

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. On the Tools menu, click Options to open the Options dialog box.

  4. Select the Enable metaverse rules extension check box.

  5. Select the Enable Provisioning rules extension check box.

  6. To open the Create Extension Project dialog box, click Create Rules Extension Project.

  7. In the Project name box, type MVExtension.

  8. Select the Launch in VS.Net IDE check box, and then click OK to start Visual Studio .NET.

  9. To open Visual Studio .NET, click OK.

  10. Copy the code from Appendix D, and then paste that code into the body of the Provision method for your new project.

  11. Copy the code for the ProvisionToECMA method from Appendix E, and then paste that code under the Provision method.

  12. On the Build menu, click Build Solution.

  13. In MIIS 2003, in the Options dialog box, click Browse.

  14. From the list of available files, select MVExtension.dll.

  15. To activate the metaverse rules extension, click OK.

Configure run profiles

For the scenario in this document, you must configure several run profiles for the Management Agent for Delimited Text Files, named MyFileMA, and for the ECMA, named MyCallBasedExportECMA. The topics in this section describe how to create and configure the required run profiles.

Configure run profiles for the Management Agent for Delimited Text Files

For the scenario in this document, the Management Agent for Delimited Text Files contributes the source identity data. Therefore, you must create an import run profile and a synchronization run profile for this management agent. The following illustration shows the Configure Run Profiles for dialog box after you configure all run profiles for the MyFileMA management agent.

Configuring run profiles for Delimited text file

To create the run profiles

  1. Copy the identity data source file from C:\FullImportSample.txt to the data folder for the MyFileMA management agent.

    The folder is located at %ProgramFiles%\Microsoft Identity Integration Server\MaData\MyFileMA.

  2. In MIIS 2003, open Identity Manager.

  3. Switch to the Management Agents view.

  4. Under Management Agents, from the Name column, select MyFileMA.

  5. To open the Configure Run Profiles for dialog box, on the Actions menu, click Configure Run Profiles.

  6. To open the Configure Run Profile Wizard, click New Profile.

  7. In the Name box, type Full Import, and then click Next.

  8. From the Type list, select Full Import (Stage Only), and then click Next.

  9. In the Input file name box, type FullImportSample.txt.

  10. To create the run profile, click Finish.

  11. To open the Configure Run Profiles Wizard, click New Profile.

  12. In the Name box, type Full Synchronization, and then click Next.

  13. From the Type list, select Full Synchronization, and then click Next.

  14. To create the run profile, click Finish.

Configure run profiles for the ECMA

Because the ECMA is the target for the source identity data in this document, you must create an export run profile for this management agent. The following illustration shows the Configure Run Profiles for dialog box after you configure all run profiles for the ECMA.

Creating the export run profile

To create the export run profile

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. Under Management Agents, from the Name column, select MyCallBasedExportECMA.

  4. To open the Configure Run Profiles for dialog box, on the Actions menu, click Configure Run Profiles.

  5. To open the Configure Run Profile Wizard, click New Profile.

  6. In the Name box, type Export, and then click Next.

  7. From the Type list, select Export, and then click Next.

  8. To create the run profile, in the Output file name box, type Export.txt, and then click Finish.

Test the configuration

The topics in this section describe how to test the configuration for the MyCallBasedExportECMA management agent.

Fully import the sample identity data

For the first configuration test, you import the identity data from the FullImportSample.txt text data file into the connector space of the MyFileMA management agent. This identity data file contains two objects that are staged in the connector space after a successful run of the full import run profile. The following illustration shows the synchronization statistics for a successful full import run.

Full import of the sample identity data

To fully import sample identity data from the text file

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. Under Management Agents, from the Name column, select MyFileMA.

  4. On the Actions menu, click Run to open the Run Management Agent dialog box.

  5. From the list of run profiles, select Full Import.

  6. To start the run profile, click OK.

Verify the full import results

For a first impression of the full import results, you check the synchronization statistics. Then, you perform a connector space search to finish verifying the full import results. Because the synchronization statistics reports two Add operations, the connector space search should return two objects. The following illustration shows an example of this.

Verification of the full import results

In addition to verifying that MIIS 2003 successfully staged all objects in the MyFileMA connector space, you must determine whether the new objects have the attribute values that you expect. The following illustration shows the properties of Object1 in the scenario for this document.

Verifying the full import results

To verify the full import results

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. Under Management Agents, from the Name column, select MyFileMA.

  4. To open the Search Connector Space dialog box, on the Actions menu, click Search Connector Space.

  5. To search the connector space, click Search.

  6. Verify that all test objects are listed in the search results.

  7. From the list of objects, select the object with the distinguished name value of 1.

  8. To open the Connector Space Object Properties dialog box, click Properties.

  9. To open the View Attribute Details dialog box, click the button in the New Value column of the member attribute.

  10. Verify that the object attributes values are identical to the values in the text data file.

  11. Close the Search Connector Space dialog box.

Fully synchronize the new identity data

To process the newly staged objects towards the metaverse, you run the full synchronization run profile. After a successful full synchronization run, the two objects are projected into the metaverse and provisioned into the connector space of the MyCallBasedExportECMA management agent. The following illustration shows the synchronization statistics for a successful full synchronization run.

Call-Based Export MA

To fully synchronize the new identity data

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. Under Management Agents, from the Name column, select MyFileMA.

  4. On the Actions menu, click Run to open the Run Management Agent dialog box.

  5. From the list of run profiles, select Full Synchronization.

  6. To start the run profile, click OK.

Verify the full synchronization results

For a first impression of the full synchronization results, you check the synchronization statistics. Then, you perform a metaverse search to finish verifying the full synchronization results. Because the synchronization statistics report two Projection operations, the metaverse search should return two objects. The following illustration shows an example of this.

Two objects returned by the metaverse search

In addition to verifying that MIIS 2003 projected all objects into the metaverse, you must determine whether the new metaverse objects have the attribute values that you expect. The following illustration shows the properties of Object1 in the current scenario.

Properties of Object1 in this scenario

During the synchronization run, MIIS 2003 provisions the newly created metaverse objects into the connector space for the MyCallBasedExportECMA management agent. You use a connector space search to verify whether the provisioned objects have the attribute values that you expect.

The following illustration shows an example for the attribute details of a newly provisioned object in the connector space of the MyCallBasedExportECMA management agent. Because MIIS 2003 has just provisioned the object, the old value column is empty for all attributes. The following illustrations shows an example of this.

The old value is empty for all attributes

To verify the full synchronization results

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Metaverse Search view.

  3. To start a metaverse search, on the Actions menu, click Search.

  4. To verify that all objects are projected, review the list of returned objects.

  5. From the displayName column of the results list, select Object1.

  6. To open the Metaverse Objects Properties dialog box, on the Actions menu, click Properties.

  7. Verify that the object attributes values are identical to the values in the text object data file.

  8. Close all open dialog boxes.

  9. Switch to the Management Agents view.

  10. Under Management Agents, from the Name column, select MyCallBasedExportECMA.

  11. To open the Search Connector Space dialog box, on the Actions menu, click Search Connector Space.

  12. To search the connector space, click Search.

  13. Verify that all test objects are listed in the search results.

  14. From the list of objects, select the object with the distinguished name value of 1.

  15. To open the Connector Space Object Properties dialog box, click Properties.

  16. Verify that the object attributes values are identical to the values in the text object data file.

  17. Close the Search Connector Space dialog box.

Export the sample identity data

At this point, you have verified that MIIS 2003 has staged new identity data updates in the connector space of the MyCallBasedExportECMA management agent. You can now export the data. After successfully completing an export run, the Export Statistics reports two Adds. The following illustration shows an example of this.

Export of the sample identity data

To export the sample identity data

  1. In MIIS 2003, open Identity Manager.

  2. Switch to the Management Agents view.

  3. Under Management Agents, from the Name column, select MyCallBasedExportECMA.

  4. To open the Run Management Agent dialog box, on the Actions menu, click Run.

  5. From the list of run profiles, select Export.

  6. To start the run profile, click OK.

Verify the export results

As stated earlier, the purpose of the scenario in this document is to export identity data changes into an XML data file. As a last step, you open the new XML file with Internet Explorer to verify that it has the results that you expect. The following illustration shows an example of this.

Verification of the export results

To verify the export results

  1. To open the Run dialog box, click the Start menu, and then click Run.

  2. In the Open box, type iexplore "%ProgramFiles%\Microsoft Identity Integration Server\MaData\MyCallBasedExportECMA\Export.xml".

Summary

This document describes the process of developing a call-based export component for an ECMA. For a call-based export component, you implement three procedures that are predefined by the ECMA framework. The main challenge of developing such a component is to find a workable solution for communicating with a connected data source to provide the export data. When you have determined a solution for transferring the data, developing a call-based export component is a straightforward task.

Appendices

Appendix A: The content of the schema definition file

objectclass, delta, anchor-attribute, name, email

Appendix B: The content of the object data text file for full import

objectclass,delta,anchor-attribute,name,email
Person,Add,1,Object1,Object1@fabrikam.com
Person,Add,2,Object2,Object2@fabrikam.com

Appendix C: The export component source code

Imports Microsoft.MetadirectoryServices
Imports System.Xml

Public Class MyCallBasedExportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleCallExport
    '------------------------------------------------------
    Dim m_xmlDoc As XmlDocument = Nothing
    Dim m_szExportFileName As String = ""
    Dim m_szObjectElementName As String = ""
    Dim m_szDeltaElementName As String = ""
    '------------------------------------------------------

    Public Sub GenerateImportFile(ByVal fileName As String, ByVal connectTo As String, ByVal user As String, ByVal password As String, ByVal configParameters As Microsoft.MetadirectoryServices.ConfigParameterCollection, ByVal fFullImport As Boolean, ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection, ByRef customData As String) Implements Microsoft.MetadirectoryServices.IMAExtensibleFileImport.GenerateImportFile
        Throw New EntryPointNotImplementedException()
    End Sub

    Public Sub BeginExport(ByVal connectTo As String, ByVal user As String, ByVal password As String, ByVal configParameters As Microsoft.MetadirectoryServices.ConfigParameterCollection, ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection) Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.BeginExport
        Try
            m_szExportFileName = _
                 configParameters("ExportFileName").Value
            m_szObjectElementName = _
                 configParameters("ObjectElementName").Value
            m_szDeltaElementName = _
                 configParameters("DeltaElementName").Value
            m_xmlDoc = New XmlDocument
            m_xmlDoc.LoadXml(configParameters("XMLRoot").Value)
        Catch ex As Exception
            Throw ex
        End Try
    End Sub

    Public Sub EndExport() Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.EndExport
        Try
            Dim filePath As String
            filePath = MAUtils.MAFolder.ToString + _
                       "\" + m_szExportFileName
            m_xmlDoc.Save(filePath)
            m_xmlDoc = Nothing
        Catch ex As Exception
            Throw ex
        End Try
    End Sub

    Public Sub ExportEntry(ByVal modificationType As Microsoft.MetadirectoryServices.ModificationType, ByVal changedAttributes() As String, ByVal csentry As Microsoft.MetadirectoryServices.CSEntry) Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.ExportEntry
        Try
            '-----------------------------------------------------
            Dim objElem As XmlElement
            objElem = m_xmlDoc.CreateElement(m_szObjectElementName)
            m_xmlDoc.DocumentElement.AppendChild(objElem)
            '-----------------------------------------------------
            Dim myElem As XmlElement
            myElem = m_xmlDoc.CreateElement(m_szDeltaElementName)
            myElem.InnerXml = modificationType.ToString
            objElem.AppendChild(myElem)
            '-----------------------------------------------------
            Dim changedAttribute As String
            For Each changedAttribute In changedAttributes
                myElem = m_xmlDoc.CreateElement(changedAttribute)
                myElem.InnerXml = _
                    csentry(changedAttribute).Value.ToString
                objElem.AppendChild(myElem)
            Next
            '-----------------------------------------------------
        Catch ex As Exception
            Throw ex
        End Try
    End Sub
End Class

Appendix D: The provision source code

Try
   If (mventry.ObjectType.Equals("ECMAPerson")) _
      Then ProvisionToECMA(mventry)
Catch ex As Exception
   Throw ex
End Try

Appendix E: The ProvisionToECMA source code

Private Sub ProvisionToECMA(ByVal mventry As MVEntry)
   Try
      Dim myMA As ConnectedMA = mventry.ConnectedMAs("MyCallBasedExportECMA")
      If myMA.Connectors.Count <> 0 Then Exit Sub

      Dim obCS As CSEntry
      obCS = myMA.Connectors.StartNewConnector("Person")
      obCS("anchor-attribute").Value = mventry("ObjectID").Value
      obCS.CommitNewConnector()

   Catch ex As Exception
        Throw ex
   End Try
End Sub