Introducing Adapters with Tivoli Directory Integrator 6.1

Leverage the Adapter approach for developing custom connectors with TDI 6.1

The Adapter concept is introduced with the IBM® Tivoli® Directory Integrator (TDI) 6.1 release. This concept provides an alternative way to develop custom connectors for TDI. This article introduces the Adapter concept and illustrates how to develop, distribute and utilize a TDI-based Adapter using the comprehensive steps.

Dinesh Jain (dineshjain@in.ibm.com), Software Engineer, IBM Corporation

Dinesh JainDinesh Jain is from IBM's India Software Lab, Pune. He has been part of the Tivoli Directory Integrator team since joining IBM. Dinesh enjoys exploring the depth of TDI for developing integration solutions and helping the global TDI community. Before joining IBM, Dinesh completed a Masters of Computer Science degree from Pune University.



26 April 2007

Introduction to the Adapter concept

Welcome to the world of Adapters with TDI 6.1. The Adapter approach allows you to develop custom connectors for TDI, inside a TDI environment. This approach also allows users to develop and distribute the TDI-based solutions as Adapters. The Adapter architecture is a combination of several features from TDI 6.1, rather than a single feature itself. The following sections walk you through in-detail with the essential things you need to develop custom connectors using the Adapter approach.

At the time this article was under development, TDI V6.1.1 was released. Hence, the article illustrates practical steps for developing custom connectors using the Adpater approach with TDI V6.1.1. However, the same steps also can be followed with TDI V6.1.

Why Adapters?

Adapters serve as an efficient approach for developing custom connectors for TDI. Implementing custom connectors can also be achieved by writing your own Java™ or JavaScript code, outside the TDI environment. However, here are the specific advantages for developing custom connectors using the Adapter approach:

  • Leverage TDI development environment: Developers get a better development environment when TDI is used for developing custom connectors when compared to any Java or JavaScript development environment.
    1. Developing a custom connector inside the TDI environment allows you to leverage functionality provided with TDI. You can use existing default connectors, parsers, function components, and so forth inside your custom connector's implementation. This reduces the efforts required for developing custom connectors.
    2. The TDI Config Editor serves as a rich development environment where you can develop, debug, and test your solutions before publishing for consumption. The AssemblyLine debugger functionality is greatly revamped with the TDI 6.1 release, which is very helpful for debugging TDI solutions.
  • Simple from the end user's perspective: The Adapter approach allows you to implement your custom connector, which can expose its operations similar to normal connector operations. From the end-user's perspective, the custom connector functions like any other connector. You can also expose certain custom operations, which are specific to your need.
  • Easier to package and redistribute: After a custom connector is developed using the Adapter approach, it is easier to package and distribute. End-users of the custom connector can use it just like other connectors. Making changes to an already developed custom connector and re-distribution of newer versions is also an easy task if the Adapter approach is followed.
  • Better way to develop TDI solutions: Using the Adapter approach, a complex TDI solution, managing multiple data sources, can be addressed as a custom connector. This makes TDI-based solutions more reusable, adaptable to changes, easy to package and deploy.

Key features of TDI for developing Adapters

Terms used with this article

  • Adapter: This is a new approach for developing TDI-based solutions, introduced with the TDI 6.1 release. This approach allows users to develop custom connectors as TDI solutions.
  • Custom connector: TDI provides a rich set of connectors to connect to various data sources. TDI also allows users to write their own connectors. Users can develop their own custom connectors by implementing certain standard operations. Prior to the Adapter approach, connectors had to be developed in either Java or JavaScript.

Developing custom connectors using the Adapter approach is addressed by developing a TDI-based solution. A custom connector is developed with the AssemblyLine methodology, using several new features introduced in TDI 6.1. Most of these features are not developed specifically for the Adapter concept, so they have many use cases for non-Adapter use as well. The section below describes these features, which help to create and use Adapters.

  • AL operations: AssemblyLine operations defines the entry points for Adapters. In order to expose connector modes, an Adapter needs to define and implement AL operations.
  • Switch/case component: Switch/case component provides the capability to control the flow of execution in an AssemblyLine. The Config Editor provides the ability to generate a Switch/Case sequence of branches based on the operations defined inside the AssemblyLine.
  • Flexible connector initialization: This feature provides a configurable option to decide upon when you want a particular connector to establish connection with its target data source, at the time of AssemblyLine execution. Prior to this feature, it was achieved by writing script-based logic.
  • Using an iterator in flow: This feature helps to implement Iterator mode in an Adapter.
  • AssemblyLine publishing: This feature helps to publish AssemblyLine as a package. Since an Adapter is developed using the AssemblyLine methodology, it is published as a package by using the AssemblyLine Publishing feature.
  • Improved GUI to facilitate use of re-usable components: A "resource library" user interface has been added with Config Editor. It acts as a place to keep reusable TDI components such as Connectors, Parsers, and AssemblyLines. Adapters have their own tab section in the resources library.
  • AssemblyLine connector: The AssemblyLine connector acts as a primary mechanism to use an Adapter in your AssemblyLine. The AssemblyLine connector is improved with the TDI 6.1 release to deal with Adapter AssemblyLines.

These features are combined into an AssemblyLine, which consists of actual implementation of the custom connector functionality. The developed AssemblyLine solution (custom connector) is published and distributed as a package for others to use this custom connector. The TDI 6.1 User's Guide, sub-section "Adapters" provides in-depth details about each of features described above to build a custom connector using the Adapter approach.


Creating your custom connector using the Adapter approach

Previous sections provided an introduction to the Adapter concept, its importance, and features required to develop an Adapter based solution. This section illustrates how to create a custom connector using the Adapter approach.

Prerequisites

The custom connector will be developed as an AssemblyLine-based TDI solution. Below are the initial steps to get ready for Adapter development.

Steps

  1. After installing TDI 6.1.1, launch the Config Editor(ibmditk).
  2. Create a config file with name "AdapterDemo.xml".
  3. Add an AssemblyLine to it with name "AdapterAL".
Figure 1. Getting ready for Adapter development
Getting ready for Adapter development

Implementing a custom connector with default connector modes

A connector implements one or more operations that interact with the target data source. These operations are exposed as modes of the connector, so that users can utilize the connector at various places in the data flow of an AssemblyLine.
The following table shows methods (operations) that a developer has to consider when implementing a TDI connector in various modes

Table 1. Mapping Adapter operations to connector modes
IteratorLookupAddonlyUpdateDeleteDeltaCallReplyServer
initialize(X)(X)(X)(X)(X)(X)(X)(X)
querySchema(X)(X)(X)(X)(X)(X)(X)(X)
selectEntries(X)-------
getNextEntryX------X
findEntry-X-XX(X)--
modEntry---X-X--
putEntry--XX-X-(X)
deleteEntry----XX--
queryReply------X-
getNextClient-------X
terminate(X)(X)(X)(X)(X)(X)(X)(X)

Note

  • (X) means optional. Will be called if they exist.
  • Delta mode requires implementation in a special manner.
  • Server mode is not currently supported in Adapters.
  • The operation names are case sensitive.

Depending upon the operations implemented, modes are exposed by the custom connector. To implement TDI connector modes, AssemblyLine operations have to be created in the Adapter AssemblyLine. These operations are connector primitives that any connector has to implement, just as if it was implemented in Java or JavaScript.

For example, a connector in "AddOnly" mode allows users to insert data into the data source. In order to implement "AddOnly" mode, you need to implement operation "putEntry" .

Scenario
Let's now get started with developing a custom connector having an "AddOnly" mode. Here, we will develop an Adapter-based solution exposing the "AddOnly" mode. The custom connector in "AddOnly" mode receives attributes such as firstName, lastName and city. The connector formats this information into proper LDAP entry format and will add the same entry into two different LDAP servers configured at the back-end.

Defining the putEntry operation
In order to expose the AddOnly mode, AssemblyLine must define and implement the "putEntry" operation. The "initialize","querySchema" and "terminate" operations are optional. The Table mentioned above shows this mapping. For more information about each connector operation, refer to section "Implementing your own Components" from TDI 6.1 Reference Guide. Below are the steps for defining the "putEntry" operation.

Steps

  1. Inside the AssemblyLine "AdapterAL", click on Operations tab.
  2. Click on the image button Insert new object for adding a new operation.
  3. Name the operation as "putEntry". Note that default operations are case sensitive.
  4. Click OK.
  5. Select the operation putEntry from the operations list.
  6. Go to the "Input Attributes" tab page shown on the right side of the operations list.
  7. Add new attributes to the Schema section: "firstName", "lastName", "city" one by one.
  8. Now, select all three attributes added in Schema section and drag them to the Work attribute list.
Figure 2. Defining the putEntry operation
Defining putEntry operation

Implementing the putEntry operation
When the operation is defined, it’s time to implement actual code in the Adapter for that operation. Here, code is written that deals with the target data source. We can utilize existing one or more connectors, function components, and so forth for implementing actual business logic to deal with the target data sources. You can also write script-based logic as the implementation of an operation. TDI provides you the ability to customize your solution for your needs. Below are the steps to implement the putEntry operation. Here, we will use two LDAP servers as target data sources. So, whenever this Adapter is used in AddOnly mode, it will add the same entry into two different LDAP servers configured at the back-end.

Steps

  1. Inside the AssemblyLine "AdapterAL", go to the "Data Flow" tab.
  2. Add a new switch component with the name "switch_operations". This is shown in Figure 3 below.
    Figure 3. Adding a switch of type AssemblyLine operations
    Adding Switch of type AssemblyLine operations
  3. Select the option AssemblyLine operations shown with the right side switch component panel.
  4. Click on Add Case components. It will pop-up a message for adding "putEntry" case.
  5. Click Yes to proceed. The new case "switch_operations_putEntry" will be added under switch component.
  6. Select the case switch_operations_putEntry. This is shown in Figure 4 below.
    Figure 4. Adding operation inside Switch
    Adding operation inside Switch
  7. As shown in Figure 5, add a script component named "script" to modify the work entry object according to LDAP object format.
    Figure 5. Implementing the putEntry operation
    Implementing putEntry operation
  8. Right-click on and select Add Connector component.
  9. Select the connector of type "ibmdi.LDAP" with Mode as "AddOnly".
  10. Name the connector as "LDAP1_add". Click OK to proceed.
  11. Specify appropriate LDAP connection details with it, pointing to one LDAP server.
  12. Again, add another LDAP connector in AddOnly mode pointing to second LDAP server.
  13. Inside the AssemblyLine "AdapterAL", go to "Data Flow" tab.
  14. Enable "Automatically map all attributes".

This completes the implementation of our Adapter AssemblyLine "AdapterAL". The ZIP file in the Download section at the end of this article contains the AdapterDemo.xml file with "AdapterAL" AssmeblyLine.

Implementing a custom connector with custom connector modes

The previous section described how to create a custom connector with default connector modes. Similarly, we can also develop custom modes for a custom connector.

When are custom modes required?

Generally custom modes are implemented for exposing certain operations that do not suit the standard modes. For example, you can implement a custom connector exposing "disable_account" as a custom mode to disable a user account from a particular data source. Or you can implement a custom connector exposing "getEmployeeID" as a custom mode to retrieve only the EmployeeID attribute from a particular data source.

How are custom modes implemented?

The implementation of a custom mode is similar to what we have seen in the section above with implementation of a default mode, except for the fact that default modes are implemented using standard operation names listed in Table 1in the earlier section. For example, in order to expose the "disable_account" mode with the Adapter AssemblyLine, we need to define and implement operation "disable_account" with it. Refer to the steps mentioned in the sections above for implementing custom modes.


Packaging Adapter for distribution

By this time, we are done with the implementation of our Adapter(custom connector). Now it is ready for publishing so that others can use it. The AssemblyLine publishing feature allows an Adapter to be exported as a package. Publishing an AssemblyLine performs resolution of all inheritance and dependencies between the Adapter AssemblyLine and the rest of the development environment in which Adapter AL was developed. The Package consists of a standard stand-alone config XML file that only contains the Adapter code that can be sent to other TDI developers for inclusion in their resource library. Below are the steps to do this.

Steps

  1. Select the AssemblyLine AdapterAL.
  2. Right click on it and select Publish option.
  3. The Package information panel will be displayed. Fill in the details accordingly. Specify the Package ID as "MyLDAPAdapter".
  4. Click on Save so that the package file will be saved inside the "packages" sub-directory of the TDI solution directory.

You can find this package file MyLDAPAdapter.xml present with the "packages" sub-directory inside the ZIP file in the Download section at the end of this article.

Figure 6. Publishing Adapter as a package
Publishing Adapter as a package

Using the Adapter

There are several ways of using an Adapter inside the TDI environment. After an Adapter is distributed as a package, copy the XML file inside the "packages" sub-directory of the TDI solution directory. Now, you can see the Adapter listed as a connector in the connector list. Alternatively we can also use AssemblyLine Connector to invoke operations on Adapter.
The AssemblyLine Connector is enhanced with the TDI 6.1 release which deals with Adapter style AssemblyLines. The steps below describe how to use the Adapter developed in the previous sections.

Steps

  1. Copy the Adapter XML file (published as package) inside the "packages" sub-directory of the TDI solution directory.
  2. Launch Config Editor.
  3. Go to the "Packages" panel displayed on left side corner of the Config Editor.
  4. Ensure that the "MyLDAPAdapter" package is displayed in the list as shown in Figure 7 below.
    Figure 7. Adapter displayed as a package
    Adapter displayed as a package
  5. Create a config file named "Client.xml" and add an AssemblyLine to it named "ClientAL".
  6. Inside the AssemblyLine, add a connector of type "FileSystem" connector in Iterator mode with CSV parser.
  7. Specify a valid CSV file t contaatins entries with the firstName, lastName, and city attributes.
  8. As shown with Figure 8 below, add a connector of type "AssemblyLine Connector" inside the same AssemblyLine.
  9. From the "Connection" tab of the connector configuration, click the Query button to query AssemblyLines.
  10. From the drop-down list, select "Adapter : MyLDAPAdapter:/AssemblyLines/AdapterAL"
  11. The connector mode will be automatically switched to "AddOnly" mode.
  12. Inside the AssemblyLine "AdapterAL", go to "Data Flow" tab.
  13. Enable "Automatically map all attributes".
  14. Run the Assemblyline.
Figure 8. AssemblyLine connector
AssemblyLine Connector

This completes the client side development part that invokes Adapter operations. For more details, refer to the file client.xml in the ZIP file in the Download section at the end of this article.


Conclusion

As described in this article, the Adapter concept provides a new approach of developing custom connectors with TDI 6.1. This approach makes TDI act as the most suitable environment for developing custom connectors as compared to any Java or JavaScript development environment. The detailed procedure mentioned with the article can be used by solution developers for developing custom connectors as TDI-based solutions (Adapters).


Download

DescriptionNameSize
Demo Config files created with this articleDemoConfigs_TDI_Adapters.zip6KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Tivoli (service management), Tivoli
ArticleID=204583
ArticleTitle=Introducing Adapters with Tivoli Directory Integrator 6.1
publish-date=04262007