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.
- 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.
- 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
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.
The custom connector will be developed as an AssemblyLine-based TDI solution. Below are the initial steps to get ready for Adapter development.
- After installing TDI 6.1.1, launch the Config Editor(ibmditk).
- Create a config file with name "AdapterDemo.xml".
- Add an AssemblyLine to it with name "AdapterAL".
Figure 1. 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
- (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.
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" .
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.
- Inside the AssemblyLine "AdapterAL", click on Operations tab.
- Click on the image button Insert new object for adding a new operation.
- Name the operation as "putEntry". Note that default operations are case sensitive.
- Click OK.
- Select the operation putEntry from the operations list.
- Go to the "Input Attributes" tab page shown on the right side of the operations list.
- Add new attributes to the Schema section: "firstName", "lastName", "city" one by one.
- Now, select all three attributes added in Schema section and drag them to the Work attribute list.
Figure 2. Defining the 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.
- Inside the AssemblyLine "AdapterAL", go to the "Data Flow" tab.
- 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
- Select the option AssemblyLine operations shown with the right side switch component panel.
- Click on Add Case components. It will pop-up a message for adding "putEntry" case.
- Click Yes to proceed. The new case "switch_operations_putEntry" will be added under switch component.
- Select the case switch_operations_putEntry. This is shown in Figure 4 below.
Figure 4. Adding operation inside Switch
- 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
- Right-click on and select Add Connector component.
- Select the connector of type "ibmdi.LDAP" with Mode as "AddOnly".
- Name the connector as "LDAP1_add". Click OK to proceed.
- Specify appropriate LDAP connection details with it, pointing to one LDAP server.
- Again, add another LDAP connector in AddOnly mode pointing to second LDAP server.
- Inside the AssemblyLine "AdapterAL", go to "Data Flow" tab.
- 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.
- Select the AssemblyLine AdapterAL.
- Right click on it and select Publish option.
- The Package information panel will be displayed. Fill in the details accordingly. Specify the Package ID as "MyLDAPAdapter".
- 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
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.
- Copy the Adapter XML file (published as package) inside the "packages" sub-directory of the TDI solution directory.
- Launch Config Editor.
- Go to the "Packages" panel displayed on left side corner of the Config Editor.
- Ensure that the "MyLDAPAdapter" package is displayed in the list as shown in Figure 7 below.
Figure 7. Adapter displayed as a package
- Create a config file named "Client.xml" and add an AssemblyLine to it named "ClientAL".
- Inside the AssemblyLine, add a connector of type "FileSystem" connector in Iterator mode with CSV parser.
- Specify a valid CSV file t contaatins entries with the firstName, lastName, and city attributes.
- As shown with Figure 8 below, add a connector of type "AssemblyLine Connector" inside the same AssemblyLine.
- From the "Connection" tab of the connector configuration, click the Query button to query AssemblyLines.
- From the drop-down list, select "Adapter : MyLDAPAdapter:/AssemblyLines/AdapterAL"
- The connector mode will be automatically switched to "AddOnly" mode.
- Inside the AssemblyLine "AdapterAL", go to "Data Flow" tab.
- Enable "Automatically map all attributes".
- Run the Assemblyline.
Figure 8. 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.
|Demo Config files created with this article||DemoConfigs_TDI_Adapters.zip||6KB|
- Learn more about IBM Tivoli Directory Integrator.
- TDI 6.1 User's Guide, sub-section "Adapters" provides in depth details about the Adapter approach.