Megosztás a következőn keresztül:

Developing a File-Based Export Management Agent

  • Cikk

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. You develop the custom ECMA by using the file-based export interface of the ECMA framework in MIIS 2003.

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 file-based export interface to export identity data into 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. MIIS 2003 provides the source data for a file-based export in the form of an intermediate file. To create the target export data file, your code reads the export data from the intermediate file, transforms it according to your scenario requirements into the required format, and then writes the transformed export data into the target file.

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 MyFileBasedImportECMA, 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.

Solution Explorer after adding the .dll file

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 IMAExtensibleFileExport interfaces for the scenario covered in this document.

The following code shows the abbreviated version of the ECMA code after you implement the required interfaces.

Imports Microsoft.MetadirectoryServices

Public Class MyImportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleFileExport

    Public Sub GenerateImportFile(…) Implements … 
    End Sub

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

To implement the required interfaces

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

  2. Type Implements IMAExtensibleFileImport, and then press ENTER.

  3. Type Implements IMAExtensibleFileExport, 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 reads the export data from an intermediate text file, and then writes it to an XML file. To write data to an XML file, and to read data from a text file, you must import the following namespaces into your code:

System.XML
System.IO

The following code shows the abbreviated version of the code after you have implemented the required interfaces.

Imports System.IO
Imports System.Xml
Imports Microsoft.MetadirectoryServices

Public Class MyFileBasedExportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleFileExport

    Public Sub GenerateImportFile(…) Implements … 
    End Sub

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

The file-based export component of the ECMA is implemented as a procedure named DeliverExportFile. The DeliverExportFile procedure performs the following actions:

  1. Reads the schema definition from the intermediate export file.

  2. Creates a new XML file to store the exported identity data.

  3. Reads the object information for each object stored in the intermediate file, and then write it into the XML file.

  4. Closes the XML file.

  5. Closes the intermediate file.

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

RootElementName

The name of the XML root element in the target XML file

ObjectElementName

The name of the object element in the target XML file

Your code assumes that these parameters are configured in the MyFileBasedExportECMA management agent, and that they have correct values.

In MIIS 2003, export operations are always deltas. If there are no pending export deltas staged in a connector space, the intermediate data file does not contain any data after an export run. However, if pending exports exist, the first line of the intermediate data file contains the attribute names of the exported objects followed by the attribute values for each object with pending export changes.

As a first step, your code reads the first line of the intermediate file with a stream reader. A stream reader supports a ReadLine method to read a line of characters from the current stream, and then return the data as a string. This is sufficient to read the schema information. The following code reads the schema information from the intermediate file.

  Dim srReader As New StreamReader(fileName)
  Dim header As String = srReader.ReadLine

If the header variable contains no data, you can exit the procedure because the intermediate file contains no data. However, if the header contains data, it is the attribute name information. In this case, your code stores the attribute names in a string array. The following code shows this.

If IsNothing(header) Then Exit Sub
Dim szAttributeNames() As String = header.Split(",")

If the header contains data, you must have at least one additional object data row in the intermediate data file. In this case, your code creates an XML output file in the folder for the management agent, reads all data rows from the intermediate file, and then stores them in the XML file. The following code shows this.

Dim attributes As String = srReader.ReadLine
Dim attributesList() As String
'Open a XML text writer in the MA folder
Dim xmlFileName As String = MAUtils.MAFolder.ToString + "\" + configParameters("ExportFileName").Value

Dim xmlExportWriter As New XmlTextWriter(xmlFileName, System.Text.Encoding.Default)
        xmlExportWriter.WriteStartElement(configParameters("RootElementName").Value)
While Not IsNothing(attributes)
   xmlExportWriter.WriteStartElement(configParameters("ObjectElementName").Value)
   attributesList = attributes.Split(",")
   For i As Integer = 0 To szAttributeNames.Length - 1
      mlExportWriter.WriteElementString(szAttributeNames(i).Trim(ControlChars.Quote), _
                                         attributesList(i).Trim(ControlChars.Quote))
   Next
   xmlExportWriter.WriteEndElement()
   attributes = srReader.ReadLine
End While

As a final step, you must complete the XML file with an end element and close all file handles. The following code shows this.

xmlExportWriter.WriteEndElement()
xmlExportWriter.Flush()
srReader.Close()

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 MyFileBasedExportECMAProperties.

  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 MyFileBasedExportECMA, 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.

The Configure Connection Information page

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 File-based.

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

  4. From the Files list, select MyFileBasedExportXMA.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 GenerateImportFile procedure of the import component.

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

The Configure Additional Parameters page

Connection Parameter Parameter name Value

Parameter 1

ExportFileName

Export.xml

Parameter 2

RootElementName

sample-objects

Parameter 3

ObjectElementName

object

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("MyFileBasedExportECMA")
     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 MyFileBasedExportECMA. 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 C:\Program Files\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 Profile 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 MyFileBasedExportECMA.

  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 MyFileBasedExportECMA 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 MyFileBasedExportECMA management agent. The following illustration shows the synchronization statistics for a successful full synchronization run.

Ful synchronization of the new identity data

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 MyFileBasedExportECMA 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 MyFileBasedExportECMA 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 MyFileBasedExportECMA.

  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 MyFileBasedExportECMA 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 MyFileBasedExportECMA.

  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 "%Program Files%\Microsoft Identity Integration Server\MaData\MyFileBasedExportECMA\Export.xml".

Summary

This document describes the process of developing a file-based export component for an ECMA. In the simplest implementation, the development of such a component is a straight-forward task that you can accomplish by writing one procedure that is provided by the ECMA development framework. The main challenge of such development work is to find a proper solution for communicating with a connected data source to provide the export data. When you have determined a solution for pushing out the data, your code must extract it from the intermediate file, and then store it in the format that the target system requires.

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.IO
Imports System.Xml

Public Class MyFileBasedExportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleFileExport
    '-----------------------------------------------------------------------------
    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 DeliverExportFile(ByVal fileName As String, _
                                 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.IMAExtensibleFileExport.DeliverExportFile
        '-----------------------------------------------------------------------------
        'Open the intermediate export file
        Dim srReader As New StreamReader(fileName)
        Dim header As String = srReader.ReadLine
        '-----------------------------------------------------------------------------
        'If the header is nothing, there is no data in the export file
        If IsNothing(header) Then Exit Sub
        'Extract the attribute names from the first row of the intermediate file
        Dim szAttributeNames() As String = header.Split(",")
        '-----------------------------------------------------------------------------
        'If there is a header in the intermediate file, there must be at least
        'one data row 
        Dim attributes As String = srReader.ReadLine
        Dim attributesList() As String
        'Open a XML text writer in the MA folder
        Dim xmlFileName As String = MAUtils.MAFolder.ToString + "\" + configParameters("ExportFileName").Value
        Dim xmlExportWriter As New XmlTextWriter(xmlFileName, System.Text.Encoding.Default)
        xmlExportWriter.WriteStartElement(configParameters("RootElementName").Value)
        'Read all the data rows
        While Not IsNothing(attributes)
            xmlExportWriter.WriteStartElement(configParameters("ObjectElementName").Value)
            attributesList = attributes.Split(",")
            'Write all attributes and attribute values for an object into the XML file
            For i As Integer = 0 To szAttributeNames.Length - 1
                xmlExportWriter.WriteElementString(szAttributeNames(i).Trim(ControlChars.Quote), _
                                                   attributesList(i).Trim(ControlChars.Quote))
            Next
            xmlExportWriter.WriteEndElement()
            attributes = srReader.ReadLine
        End While
        '-----------------------------------------------------------------------------
        xmlExportWriter.WriteEndElement()
        xmlExportWriter.Flush()
        xmlExportWriter.Close()
        srReader.Close()
        '-----------------------------------------------------------------------------
    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("MyFileBasedExportECMA")
      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