Developing a File-Based Import Management Agent

The primary responsibility of a management agent is to provide a bidirectional identity data transfer mechanism that enables MIIS 2003 to import identity data from a connected data source and export identity data to a connected data source. , MIIS 2003 already provides a rich support for various connected data sources such as Active Directory, SQL Server and even flat files out of the box. If your scenario includes a connected data source for which no built-in management agent exists or if your scenario requires features that are not included in the built-in management agents, you can develop your own management agent. These management agents are also known as Extensible Connectivity Management Agents (ECMA). To exchange data with a connected data source, the ECMA architecture supports three different interfaces—a file-based import, a file-based export and a call-based export. This document is part of a series of documents discussing the initial development steps for an Extensible Connectivity Management Agent. The focus of this document is the file-based import interface provided in an ECMA.

What This Document Covers

This document is part of a series of documents that outline the initial development process of an Extensible Connectivity Management Agent.

After completing this document, you will be able to successfully extract identity data from an XML file and get it staged in the connector space by running an import run profile on the new ECMA.

The following illustration shows the setup for connected data sources discussed in this document.

This document is only based on one management agent, which is an extensible connectivity management agent.

Prerequisite Knowledge

This document assumes that you have a good understanding of the basic MIIS 2003 concepts. Read the following documents if you need a basic understanding of MIIS 2003 features and functionality:

• To get an overview of identity integration and how MIIS 2003 fills this role, read MIIS 2003 Overview (MIIS_Overview.doc) in the MIIS 2003 Technical Reference (https://go.microsoft.com/fwlink/?LinkId=30737).

• TO get a list of all management agents available in MIIS 2003 and the features supported by each of them, read the MIIS 2003 Management Agent Guide (https://go.microsoft.com/fwlink/?LinkId=75311)

• To try out the basic MIIS 2003 features, including some MIIS 2003 concepts, read the Getting Started with MIIS 2003 Walkthrough (https://go.microsoft.com/fwlink/?LinkId=83357)

• For a description of all MIIS 2003 documentation, see Microsoft Identity Integration Server 2003 Documentation Roadmap (https://go.microsoft.com/fwlink/?LinkID=82465).

This document also assumes that you have a basic understanding of Visual Studio .NET. A description of advanced Visual Studio .NET coding practices is out of the scope of this document.

Audience

This guide is intended for IT planners, systems architects, developers and IT personnel who plan and develop a connected data source extension for MIIS 2003.

Time requirements

This 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 the testing environment is already configured and ready for testing to begin and do not include the time required to set up the test environment.

Scenario Description

Fabrikam, a fictitious corporation, needs to import identity data from a connected data source for which no built-in management agent exists. To get a better understanding of the complexity involved in the process of developing a connected data source extension, Fabrikam decided on developing a proof of concept solution to import identity data from a XML file.

The Testing Environment

The scenario in this doc is designed to run on a stand-alone MIIS computer. All you need to complete this document is a MIIS computer with MIIS Service Pack 2 (SP2) and Visual Studio 2005 installed. To install MIIS 2003 SP2, you need to have either SQL Server 2000 or SQL Server 2005 installed on the MIIS computer.

Implementing the Procedures in This Document

In this document, you develop an Extensible Connectivity management agent to import identity data from an XML data file. The following sections provide detailed information about the procedures and steps you need to complete during the development. To implement the procedures in this document, you must complete the following steps in the following order:

1. Create the schema and the sample data files

2. Update the metaverse schema

3. Develop the Extensible Management Agent DLL

4. Create the management agent

5. Configure run profiles

6. Test the configuration

Creating the Schema and the Sample Data Files

To use the extensible connectivity management agent described in this documents, you need to create the following files:

• One text file that contains the object schema definition.

• One XML file that contains the identity data for a full import.

• One XML file that contains the identity data for a delta import.

The schema file includes the attribute names for the object used in the scenario of this document. This file is required during the configuration of the extensible connectivity management agent and by the import component that you will develop later in this document. The identity object used in the scenario of this document is made of the following attributes:

• objectclass

• delta

• anchor-attribute

• name

• email

You need to include these attributes into the coma-separated schema definition file, which contains only the following line:

objectclass, delta, anchor-attribute, name, email

The schema definition file also defines the XML structure used to store the identity object information in the full import and the delta import data file:

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

The XML file used for the full import operation contains two identity objects called Object1 and Object2. The following xml shows the content of this file:

<sample-objects>
    <object>
        <objectclass>Person</objectclass>
        <delta>Add</delta>
        <anchor-attribute>1</anchor-attribute>
        <name>Object1</name>
        <email>Object1@fabrikam.com</email>
    </object>
    <object>
        <objectclass>Person</objectclass>
        <delta>Add</delta>
        <anchor-attribute>2</anchor-attribute>
        <name>Object2</name>
        <email>Object2@fabrikam.com</email>
    </object>
</sample-objects>

After you have successfully imported these two objects into MIIS 2003, you will also import an attribute change for the object called Object1 as delta import. The attribute change consists of an updated e-mail address for this object. The following element definition shows the content of the XML file used for the delta import:

<sample-objects>
    <object>
        <objectclass>Person</objectclass>
        <delta>Modify</delta>
        <anchor-attribute>1</anchor-attribute>
        <name>Object1</name>
        <email>newemail@fabrikam.com</email>
    </object>
</sample-objects>

The following section provides instructions for creating the required schema and sample data files.

• One text file that contains the object schema definition

• One XML file that contains the identity data for a full import

• One XML file that contains the identity data for a delta import

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 full import identity data XML 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.xml

To create the delta import identity data XML file

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

2. Save the Notepad file on your local drive as C:\DeltaImportSample.xml.

Note

You must save the schema and the sample data files with the same name and at the same location as outlined in the instructions above because the name and the location of these files are hard coded in the import component code of the scenario in this document.

Updating the Metaverse Schema

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

• ObjectID

• ObjectName

• mail

• displayName

The ObjectID and the ObjectName are new attributes you have to create. The displayName and the mail attribute are attributes from the existing metaverse schema. The following illustration shows the newly-created 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. On the Actions menu, click Create Object Type to open the Create Object Type dialogbox.

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

5. In the Available attributes box, select mail and displayName.

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

   1. Click New attribute to open the New Attribute dialog box.

   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

Developing the Extensible Management Agent DLL

The objective of this walkthrough is to develop an extensible management agent to import object information from an XML data file and to stage the data in the connector space. Developing an import component for an extensible management agent requires that the source data is read from a connected data source and then the data is to be written into an intermediate file that is used by MIIS for the actual data import. The intermediate file used in this walkthrough is a text file with a comma as delimiter. One step in the previous section was to create the schema file for the intermediate file. The schema file is also used by the code for the extensible management described in this section to extract the attribute names and to write the correct data structure into the intermediate file.

The development of an extensible management agent consists of three major steps:

1. Creation of the extensible management agent framework

2. Implementation of the import component

3. Building the Extensible Management Agent DLL

Creation of the extensible management agent framework

The first development steps for an extensible management agent are always the same. You need to:

1. Create a new Class Library project

2. Add a reference to the Microsoft.MetadirectoryServices dll

3. Implement the required interfaces

Creating a new class library project

The code for an Extensible Connectivity management agent is encapsulated within a dll. To develop a dll, you need to 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, point to New, and then click Project.

3. From the Templates list, select Class Library.

4. In the Name box, type MyImportECMA.

5. Close the New Project dialog box.

Adding a reference to the Microsoft.MetadirectoryServices.dll

You need to add a reference to the Microsoft.MetadirectoryServices.dll file to each Extensible Connectivity management agent related project. The following illustration shows the Solution Explorer after the dll has been added to a project.

Note

If you the References node is not visible in your Solution Explorer, select “Show All Files” from the Project menu.

To add a reference to the Microsoft.MetadirectoryServices.dll file

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

2. Click the .NET tab.

3. From the Component Name list, select Microsoft.MetadirectoryServices.

4. Close the Add Reference dialog box.

Implementing the required interfaces

The Extensible Connectivity management architecture supports three interfaces:

• IMAExtensibleFileImport

• IMAExtensibleFileExport

• IMAExtensibleCallExport

The following table shows the interfaces you need to implement according to the various configuration scenarios that can be used for the ECMA:

Step types	Export modes	Interfaces to implement
Import and export	Call-based	IMAExtensibleFileImport and IMAExtensibleCallExport
Import and export	File-based	IMAExtensibleFileImport and IMAExtensibleFileExport
Import-only	Call-based	IMAExtensibleFileImport* and IMAExtensibleCallExport
Import-only	File-based	IMAExtensibleFileImport* and IMAExtensibleFileExport
Export	Call-based	IMAExtensibleFileImport and IMAExtensibleCallExport*
Export	File-based	IMAExtensibleFileImport and IMAExtensibleFileExport*

Note

Although the MIIS server requires the listed methods to be implemented, only the starred interfaces are currently used by the MIIS server in this type of connected data source extension. For interfaces that are required but not used by the MIIS Server, it is recommended you throw the EntryPointNotImplementedException in the methods.

To implement the required interfaces, you only need to type “Implements <name of the interface>” under the class definition of your code and press Enter. When you press Enter, the definitions for the procedures that are implemented by an interface are automatically added to your code. According to the table above, you need to implement the MAExtensibleFileImport and the IMAExtensibleFileExport interfaces for the scenario covered in this document. The following code shows the abbreviated version of your ECMA code after implementing 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 your ECMA code, change the class name from Class1 to MyImportECMA, and then press Enter.

2. Type Implements IMAExtensibleFileImport, and then press Enter.

3. Type Implements IMAExtensibleFileExport, and then press Enter.

Implementing the import component

For the implementation of the import component, you need to provide the code to exchange data between your extensible connectivity management agent and a connected data source. In the scenario of this document, you extract the schema information from a text file and the object data from a XML data file and write the data into an intermediate file that is used by the management agent to provide the information to MIIS. To read data from a XML file and to read data from and write data into a text file, you must import the following namespaces into your code:

System.XML
System.IO 

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

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

Public Class MyImportECMA
    Implements IMAExtensibleFileImport
    Implements IMAExtensibleFileExport

    Public Sub GenerateImportFile(…) Implements … 
    End Sub

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

The import component of the extensible management agent is implemented in form of a procedure called GenerateImportFile. The GeneratImportFile procedure has the following steps:

1. Read the schema definition from the schema file.

2. Write the schema definition as the first row into the intermediate file.

3. Load the XML data file.

4. Read the object information for each object stored in the XML data file.

5. Save the information in the intermediate file.

6. Close the intermediate file.

The code of your import component needs to access the schema definition and depending on the import type either the full or the delta import data file. To keep your solution flexible, you should avoid having parameters such as file names and file locations hard coded in your source code. The extensible connectivity management agent framework provides a convenient mechanism to specify the actual values for these parameters during the configuration of a management agent in the “Configure Additional Parameters” page. The names of the parameters you specify during the configuration of the management agent need to match the parameter names used in your source code. You can then later modify the parameter values any time without the need to modify your source code again. The parameters in the scenario of this document are as follows:

• SchemaFilePath

  The name and the location of your schema file.

• FullImportFilePath

  The name and the location of your full import source data file.

• DeltaImportFilePath

  The name and the location of your full import source data file.

Your source code assumes that these parameters are configured in your MyImportECMA configuration and that they have correct values.

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

Dim swSchema As New StreamReader(configParameters("SchemaFilePath").Value)
Dim header As String = swSchema.ReadLine
swSchema.Close()

During the configuration of an import run profile for a XMA, you specify the name of a file that is used by the run profile to read the import information from. This file is the intermediate file that needs to be filled with data by the import component. The name of the intermediate file is passed into the GenerateImportFile method as a parameter called “fileName”. For the example in this document, you use a stream writer to write the schema information into the intermediate file. The following code shows an example for this:

Dim swImport As New StreamWriter(fileName)
swImport.WriteLine(header)

As a next step, the object data needs to be extracted from the connected data source. The GenerateImportFile method provides a parameter called “fFullImport” to indicate whether the current run is a full or a delta import. This parameter is required to open the correct data file.

The following code shows an example for this:

Dim doc As New XmlDocument
If (fFullImport) Then
    doc.Load(configParameters("FullImportFilePath").Value)
Else
    doc.Load(configParameters("DeltaImportFilePath").Value) 
End If

To read the object information, you implement two nested loops; an outer loop to extract each individual object and an inner loop to access the attribute information for each object. The complete set of attribute values for each object need to be stored separated by a comma in a variable and is written into the intermediate file. The following code shows an example for this:

Dim node As XmlNode
For Each node In doc.DocumentElement.ChildNodes
    Dim objectAttributes As String = ""
    Dim attributeName As String = ""
    For Each attributeName In header.Split(",")
        If (objectAttributes.Length > 0) Then objectAttributes += ","
        objectAttributes +=         node.SelectSingleNode(attributeName).InnerXml
    Next
    swImport.WriteLine(objectAttributes)
Next node

As a last step, you need to close the stream writer the data into the intermediate file. The following code shows an example for this:

swImport.Close()

To implement the import component

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

Building the Extensible Management Agent DLL

Before you build your Extensible Connectivity management agent, you should modify output path to build your new extension into the MIIS 2003 extensions folder.

To modify the default output path of you extension

1. From the Projects menu, select MyImportECMA Properties to open the properties tab.

2. Select the Compile tab on the left pane.

3. Click Browse to open the Select Output Path dialog box.

4. Navigate to the Microsoft Identity Integration Server Extensions folder

   For example: “C:\Program Files\Microsoft Identity Integration Server\Extensions”.

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

After adjusting the output path, you can build your extension.

To build the extension

• From the Build menu, select Build Solution.

Creating the Management Agent

This section provides the configuration information for the Extensible Connectivity Management Agent you need to create for this document.

Creating the Extensible Connectivity Management Agent

To create the management agent for Active Directory, you use the Create Management Agent Wizard.

To create an Extensible Connectivity Management Agent

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. On the Actions menu, click Create to start the Create Management Agent Wizard.

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

   The instructions for each page are provided as separate procedures below.

5. Click Finish to create the management agent.

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. In the Management agents for list, select Extensible Connectivity.

2. In the Name box, type MyImportECMA, 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 can also specify a server name, a user name and a password for the remote system the management agent needs to connect to.

The following illustration shows an example of this.

To complete the Configure Connection Information page

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

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 MyImportXMA.dll and then click OK to close the dialog.

5. 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 need to add connection parameters for the schema file, the full import data file and the delta import data file. This parameter collection is passed as input parameter to the GenerateImportFile procedure of your import component.

The following illustration shows an example for the Configure Additional Parameters dialog box after you have specified all required parameters.

The following table lists the parameter names and the associated values that you use to complete the Configure Additional Parameters page.

Connection Parameter	Parameter name	Value
Parameter 1	SchemaFilePath	C:\MyECMASchema.txt
Parameter 2	FullImportFilePath	C:\FullImportSample.xml
Parameter 3	DeltaImportFilePath	C:\DeltaImportSample.xm

To complete the Configure Additional Parameters page

1. For each connection parameter in the table immediately above this procedure, complete the following steps:

   1. To open the Parameter dialog, 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, click OK.

2. Click Next.

Select Template Input File page

On this page, you provide the name, the location, and the file format of your template input file.

The following illustration shows an example for the Select Template Input File page after you have specified all required parameters.

To complete the Select Template Input File page

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

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

Delimited Text Format page

On this page, you provide information on how MIIS has to interpret your schema information. The first row in your schema file contains the header names, which are comma separated. The following illustration shows an example for the Delimited Text Format page after you have specified all required parameters.

To complete the Delimited Text Format page

1. Select Use first row for header names.

2. Under Delimiter, select Comma.

3. Under Text qualifier, select the quotation mark ("), and then click Next.

Configure Attributes page

On this page, you specify all required configuration parameters about your attributes. For the scenario in this document, you need to 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 the object class and the change type attribute have been configured.

To complete the Configure Attributes page

1. Click Set Anchor to open the Set Anchor dialog box.

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

3. Click OK to close the dialog box.

4. Click Advanced, to open the Advanced dialog box.

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

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

7. Click OK to close the dialog box, and then click Next.

Map Object Types page

On this page, you define your object classes. For the scenario in this document, you need to define one object class – Person. The following illustration shows the Map Object type dialog box after the new object type has been defined.

When you are done with the instructions in this document, you should extend this scenario with additional object classes and familiarize yourself with using them.

To complete the Map Object Types page

1. Click New to open the New Object Class dialog box.

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

3. Click OK to close the dialog box, 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

On this page, you configure the required join and projection rules for your scenario. This document requires you to 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 for this document.

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. In the Metaverse object type list, select ECMAPerson, and then click Next.

Configure Attribute Flow page

On this page, you provide the import and export attribute flow rules for your scenario. For the scenario in this document, you need to 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 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 for the object type user

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, complete the following steps:

   1. In 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.

Configuring Run Profiles

This section provides instructions for creating and configuring the required run profiles. For this document, you must configure several run profiles for the MyImportECMA management agent.

The following illustration shows the Configure Run Profiles for dialog box after you have configured all run profiles.

The following table shows the import run profiles that you must create for the MyImportECMA management agent.

Profile	Run profile name	Step type	Input File Name
Profile 1	Full Import	Full Import (Stage Only)	FullImport.txt
Profile 3	Delta Import	Delta Import (Stage Only)	DeltaImport.txt

To create the import run profiles for the MyImportECMA management agent

1. .In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. In the management agent list, select MyImportECMA.

4. On the Actions menu, click Configure Run Profiles to open the Configure Run Profiles for dialog box.

5. For each run profile in the table immediately above this procedure, complete the following steps:

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

   2. In the Name box, type the profile name shown in the table, and then click Next.

   3. In the type list, select the step type shown in the table, and then click Next.

   4. In the Input file name textbox, type the input file name shown in the table, and then click Next.

   5. Click Finish to create the run profile.

The following table shows the synchronization run profiles that you must create for the MyImportECMA management agent.

Profile	Run profile name	Step type
Profile 1	Full Synchronization	Full Synchronization
Profile 2	Delta Synchronization	Delta Synchronization

To create the synchronization run profiles for the MyImportECMA management agent

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. In the management agent list, select MyImportECMA.

4. On the Actions menu, click Configure Run Profiles to open the Configure Run Profiles for dialog box.

5. For each run profile in the table immediately above this procedure, complete the following steps:

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

   2. In the Name box, type the profile name shown the table, and then click Next.

   3. In the type list, select the step type shown in the table, and then click Next.

   4. Click Finish to create the run profile.

Testing the Configuration

This section contains instructions for testing your MyImportECMA configuration. The configuration tests consist of the following steps:

1. Full import of the sample identity data

2. Verification of the full import results

3. Full Synchronization of the new identity data

4. Verification of the full synchronization results

5. Delta Import of the identity data update

6. Verification of the delta import results

7. Delta Synchronization of the identity data update

8. Verification of the delta synchronization result

The following sections provide procedures for all steps of the configuration tests.

Full Import of the Sample Identity Data

As a first configuration test, you import the identity data from the FullImportSample XML data file into the connector space of your MyImport ECMA. 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 of a successful full import run.

To fully import data from the XML identity data file

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA.

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

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

6. To start the run profile, click OK.

Verification of the Full Import Results

As outlined in the previous section, you can get a first impression of the full import results from checking the synchronization statistics. To complete the verification of the full import results, you perform a connector space search. Since the synchronization statistics reports two Adds, the connector space search should also return two objects as outlined in the following illustration:

In addition to verifying that all objects have been successfully staged in the MyImportECMA connector space, you should also determine whether the new objects have the expected attribute values. To do so, you need to open the Connector Space Object Properties dialog box. The following illustration shows the properties of Object1 in the current scenario.

To verify the full import results

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA

4. On the Actions menu, click Search Connector Space to open the Search Connector Space dialog box.

5. To search the connector space, click Search.

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

7. In 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, 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 XML object data file.

11. Close the Search Connector Space dialog box.

Full Synchronization of the New Identity Data

To process the newly staged objects towards the metaverse, you must run the full synchronization run profile. At the end of a successful full synchronization run, the two objects are projected into the metaverse. The following illustration shows the synchronization statistics of a successful full synchronization run:

To fully synchronize the new identity data

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA.

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

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

6. To start the run profile, click OK.

Verification of the Full Synchronization Results

You can get again a first impression of the full synchronization results from checking the synchronization statistics. To complete the verification of the full import results, you perform a metaverse search. Since the synchronization statistics reports two Projections, the metaverse search should also return two objects as outlined in the following illustration:

In addition to verifying that all objects have been projected into the metaverse, you should also determine whether the new metaverse objects have the expected attribute values. To do so, you need to open the Metaverse Object Properties dialog box. The following illustration shows the properties of Object1 in the current scenario.

To verify the full synchronization results

1. In MIIS 2003, open Identity Manager.

2. Switch to the Metaverse Search view.

3. On the Actions menu, click Search to start a metaverse search.

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

5. In the displayName column of the result list, select Object1.

6. On the Actions menu, click Properties to open the Metaverse Objects Properties dialog box.

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

8. Close all open dialog boxes

Delta Import of the Identity Data Update

At this point, you have verified that your MyImportECMA is capable of importing identity data from your XML source data file and you can project these objects into the metaverse. One important feature of MIIS 2003 is the ability to process delta information. The objective of this section is to test whether you can successfully import delta changes for one of the already processed objects. This is accomplished by running a delta import with the XML data file that contains one update for Object1 as source. The following illustration shows the synchronization statistics of a successful delta import run.

To delta import data from the XML identity data file

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA.

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

5. In the list of run profiles, select Delta Import.

6. To start the run profile, click OK.

Verification of the Delta Import Results

As indicated by the synchronization statistics, 1 update has been staged in the connector space of your MyImportECMA. Since only one update for an existing object has been staged, the connector space search should still return two objects. The connector space search should still return two objects as outlined in the following illustration.

To complete the verification of the delta import result, you verify whether Object1 has a modified email attribute value by opening the Connector Space Object Properties dialog box of it. The following illustration shows the properties of Object1 in the current scenario.

To verify the delta import results

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA

4. On the Actions menu, click Search Connector Space to open the Search Connector Space dialog box.

5. To search the connector space, click Search.

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

7. In 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, 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 XML object data file.

11. Close the Search Connector Space dialog box.

Delta Synchronization of the Identity Data Update

To process the newly staged object update towards the metaverse, you run the delta synchronization run profile. At the end of a successful delta synchronization run, the updated email attribute value of Object 1 is applied to the metaverse object that is linked to it. The following illustration shows the synchronization statistics of a successful delta synchronization run:

To delta synchronize the new identity data

1. In MIIS 2003, open Identity Manager.

2. Switch to the Management Agents view.

3. From the management agent list, select MyImportECMA.

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

5. In the list of run profiles, select Delta Synchronization.

6. To start the run profile, click OK.

Verification of the Delta Synchronization Result

The synchronization statistics indicate 1 connector with a flow update. To verify whether the expected update has been applied to Object1 in the metaverse, you should determine the current value of its email attribute value. As a first step, you perform again a metaverse search, which should still return two objects as outlined in the following illustration:

The attribute details for Object1 should now show the updated value for the email attribute of Object1 as outlined in the following illustration:

To verify the full synchronization results

1. In MIIS 2003, open Identity Manager.

2. Switch to the Metaverse Search view.

3. On the Actions menu, click Search to start a metaverse search.

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

5. In the displayName column of the result list, select Object1.

6. On the Actions menu, click Properties to open the Metaverse Objects Properties dialog box.

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

8. Close all open dialog boxes.

Summary

In this document, you have been introduced to the process of developing an import component for an extensible connectivity management agent. The development of such a component is a straight forward task that can be—in the simplest implementation—accomplished by writing one single procedure provided by the extensible connectivity management development framework. The main challenge of this development is to find a proper solution for communicating with a connected data source in order to extract the required data. As soon as a solution for requesting the desired data has been determined, the requested data needs to be stored in an intermediated file that is consumed by MIIS 2003 for the import operation.

Appendices

Appendix A: The content of the schema definition file

objectclass, delta, anchor-attribute, name, email

Appendix B: The Content of the Object Data XML File for Full Import

<sample-objects>
    <object>
        <objectclass>Person</objectclass>
        <delta>Add</delta>
        <anchor-attribute>1</anchor-attribute>
        <name>Object1</name>
        <email>Object1@fabrikam.com</email>
    </object>
    <object>
        <objectclass>Person</objectclass>
        <delta>Add</delta>
        <anchor-attribute>2</anchor-attribute>
        <name>Object2</name>
        <email>Object2@fabrikam.com</email>
    </object>
</sample-objects>

Appendix C: The Content of the Object Data XML File for Delta Import

<sample-objects>
    <object>
        <objectclass>Person</objectclass>
        <delta>Modify</delta>
        <anchor-attribute>1</anchor-attribute>
        <name>Object1</name>
        <email>newemail@fabrikam.com</email>
    </object>
</sample-objects>

Appendix D: The Import Component Source Code

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


Public Class MyImportECMA
    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

        '--------------------------------------------------------------
        'Read the schma definition from the schema file
        Dim swSchema As New StreamReader(configParameters("SchemaFilePath").Value)
        Dim header As String = swSchema.ReadLine.ToLower
        swSchema.Close()
        '--------------------------------------------------------------
        'Write the header into the file
        Dim swImport As New StreamWriter(fileName)
        swImport.WriteLine(header)
        '--------------------------------------------------------------
        'Load the correct XML data file
        Dim doc As New XmlDocument
        If (fFullImport) Then
            doc.Load(configParameters("FullImportFilePath").Value)
        Else
            doc.Load(configParameters("DeltaImportFilePath").Value)
        End If
        '--------------------------------------------------------------
        Dim node As XmlNode
        'Loop through each object in the XML data file
        For Each node In doc.DocumentElement.ChildNodes
            Dim objectAttributes As String = ""
            Dim attributeName As String = ""
            'Read the attribute values for each attribute 
            For Each attributeName In header.Split(",")
                If (objectAttributes.Length > 0) Then objectAttributes += ","
                objectAttributes += node.SelectSingleNode(attributeName).InnerXml
            Next
            swImport.WriteLine(objectAttributes)
        Next node
        '--------------------------------------------------------------
        'Close the stream writer
        swImport.Close()
        '--------------------------------------------------------------

    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
        Throw New EntryPointNotImplementedException()
    End Sub
End Class