The use of operations in a Tivoli Directory Integrator Adapter

Directory Integrator, Version 7.1.1

The use of operations in a Tivoli Directory Integrator Adapter

To implement the Tivoli® Directory Integrator Connector modes, AL operations have to be created in the Adapter that correspond to the Connector primitives that any Connector has to implement, just as if it was implemented in Java or JavaScript.

The AL Connector will automatically determine what modes are available by inspecting what operations that have been defined in the Adapter. It is only necessary to implement the operations that correspond to the modes that you want the Adapter to expose. Operations that do not correspond to any in the table below are exposed as additional Adapter modes, and executed in call/reply mode by the AL Connector.

Mapping Adapter operations to Connector modes

The following are the methods that a developer has to consider when implementing a Tivoli Directory Integrator connector in Java or JavaScript. Please refer to Appendix F. Implementing your own Components in Java to fully understand the relationships between these methods and the Connector modes that they implement. For example, to implement Lookup mode in an Adapter, only the findEntry operation needs be defined.

Table 64. Operations versus modes
	Iterator	Lookup	AddOnly	Update	Delete	Delta⁽²⁾	CallReply	Server⁽³⁾
initialize	(X)	(X)	(X)	(X)	(X)	(X)	(X)	(X)
querySchema	(X)	(X)	(X)	(X)	(X)	(X)	(X)	(X)
selectEntries	(X)
getNextEntry	X							X
findEntry		X		X	X	(X)
modEntry				X		X
putEntry			X	X		X		(X)
deleteEntry					X	X
queryReply							X
getNextClient								X
terminate	(X)	(X)	(X)	(X)	(X)	(X)	(X)	(X)

Notes:

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

Implementing code in the Adapter for each operation

The Adapter AL is called by the AssemblyLine Connector according to the rules for the modes that are exposed - through the operations illustrated in the table above. The Adapter must check for what operation has been invoked and execute the corresponding code in the AL. The Switch Component is well suited for this purpose, but If-Else Components can be used as well by creating conditions using the op-entry.$operation attribute which will be set each time the AL is called with an operation. This attribute may of course be used in a script as well.

Op-entry is an Entry object available for use in Adapter ALs. Like the work object it is created by the AssemblyLine, but it doesn't get cleared every time the AL cycles. It is used to store attributes that the AL needs throughout its lifecycle. The next section will show further use of it.

Adapter configuration through the $initialization operation

All attributes that are defined in the schema of the $initialization operation of the Adapter are displayed in the configuration panel of the AL Connector that calls the Adapter. These attributes are passed to the Adapter at initialization time so that the Adapter can perform the necessary preparation and connection to the target systems.

The attributes defined in the $initialization schema are available to the Adapter throughout its lifecycle as attributes in the op-entry attribute.

Connectors in the Adapter can be configured with these attributes by using expressions in the connector parameter fields. For example, if the Adapter has defined an ou attribute in its $initialization schema, then the user of the Adapter will see "ou" as one of the configuration parameters in the AL Connector. The Adapter could then define a search base in an LDAP connector as:

cn=...,ou={op-entry.ou}

These attributes will be available at the initialization time of the Adapter, which by default is the same time as the calling AL is initialized, unless one of the mechanisms described above in section Flexible connector initialization is utilized.

Understanding the link criteria

The link criteria defined in the AL Connector is passed into the Adapter through the search object (SearchCriteria) in the op-entry object.

Extracting the individual criteria objects can be done with the following script code:

search = Task.getOpEntry().getObject("search");
criteria = search.getCriteria(0);	/* index ranges from 0 to search.size() */
name  = criteria.name; 					/* target attribute */
match = criteria.match; 					/* expression (less, greater, equal.. */
value = criteria.value; 					/* value to test the target attribute against through the expression */
negate = criteria.negate;  				/* Boolean flag */

Each criteria object contains the attributes: name, match, value, and negate (boolean).

The search object provides convenience methods to create LDAP, Domino and SQL search strings based on its link criterias. Please refer to the Javadocs for further information.

Attribute mapping

When the Adapter operations are called through the AL Connector, the work Entry is populated with the attributes in the output map of the AL Connector. On return, the AL Connector expects returned attributes either in work, or in the conn object as described in the next sections.

From the calling AL into the Adapter

The Adapter must use script methods such as:

email = work.getString("email");

to extract the value of the email attribute so that it can be used in further attribute mapping inside the Adapter. A practical suggestion is to insert an AL level Attribute Map (Attmap) component early in the Adapter to extract the desired attributes from conn and make them visible in work for easy reference in the rest of the Adapter.

Return data from the Adapter to the calling AL

The modes iterator, lookup and callreply, return data to the calling AssemblyLine and populate the output map of the AL Connector. The simplest way to return attributes to the calling AL is through the work object. Any attributes left in work at the end of the Adapter cycle will be passed back to the input map of the calling AssemblyLine Connector. It is therefore important to remove temporary work attributes at the end of the Adapter so that they aren't inadvertently returned as well, for example like this:

work.removeAttribute("attributeName");
...

The Adapter indicates end of data by returning an empty conn object in work. An empty work object is not sufficient since that is merely interpreted as an empty record by the AL Connector. To indicate end of data by the iterator, use

work.newAttribute("conn");

Lookup Mode

The lookup mode may return multiple records. If it is necessary to return more than one record, the Adapter must create the Entry attribute conn in the work Entry that can contain zero, one, or more values of type Entry. Further on in this section there is some script code to illustrate how this can be achieved in an Adapter.

The following is a mix of JavaScript and pseudo-code to illustrate the part of implementing the findEntry operation (that implements lookup mode) where attributes are mapped into a structure that can be returned to the AL Connector in the calling AL.

The example illustrates two ways to return multiple records to the calling AL. The example on the right hand side is simpler because work is cleared for each iterator cycle, and all the values in work are therefore a result of the iterator's output map, and can therefore be added to acc (acc is shorthand for accumulator) in a single operation. An important note is that getClone() needs to be used to ensure that the value of the attributes are copied into acc.

Clear work for each iterator cycle:

	Clear work for each iterator cycle:
`acc = system.newEntry().newAttribute("conn"); Loop on iterator (that returns attributes a,b,c from target into work) { /* all of the below would be located in a script component inside the Loop component */ temp = system.newEntry(); temp.setAttribute(work.getAttribute("a")); temp.setAttribute(work.getAttribute("b")); temp.setAttribute(work.getAttribute("c")); acc.addValue(temp) ; } work.setAttribute("conn", acc);`	`work.removeAllAttributes(); acc = system.newEntry().newAttribute("conn"); Loop on iterator (that returns attributes a,b,c from target into work) { acc.addValue(work.getClone()); work.removeAllAttributes(); } work.setAttribute("conn", acc);`

acc = system.newEntry().newAttribute("conn");
Loop on iterator (that returns attributes a,b,c from
 target into work)
{ 
/* all of the below would be located in a script 
  component inside the Loop component */
temp = system.newEntry();
temp.setAttribute(work.getAttribute("a"));
temp.setAttribute(work.getAttribute("b"));
temp.setAttribute(work.getAttribute("c"));
	acc.addValue(temp) ; 
}
work.setAttribute("conn", acc);

work.removeAllAttributes();
acc = system.newEntry().newAttribute("conn");
Loop on iterator (that returns attributes a,b,c
 from target into work)
{
	acc.addValue(work.getClone());
	work.removeAllAttributes();
}
work.setAttribute("conn", acc);

Status indication

A good practice is to return the attribute recordsProcessed to indicate how many records were deleted, modified, or otherwise processed. This attribute can be passed back to the calling AL as in the work object. To indicate an error situation where the AL Connector should invoke one of the error hooks in the calling AL, the Adapter needs to throw an exception. Please refer to the section on error handling for more details on this.

Implementing Query Schema

A user of the Adapter will want to discover the schema of the Adapter. This is typically done when configuring the AL Connector where there are buttons to connect and to query schema. If the Adapter implements a static schema, then the simple solution is to create a querySchema operation in the Adapter, and define the schema there. The schema defined in the querySchema operation will be common for all standard Connector modes. Specific schemas can be defined for any non-standard modes. For example, if the Adapter implements an "AddUser" operation, then it can have its own schema defined.

Delta mode

Delta mode is handled somewhat differently from other modes because there are two different scenarios for handling delta data - meaning an Entry that has been tagged for change at the Entry, attribute and/or value level.

If the target system (or implemented in the Adapter) supports change based modification (for example, LDAP allows individual values to be updated in a specific attribute in a specific entry without supplying any of the other values of the attribute). These systems are defined as "Delta savvy" and indicate that the Adapter can deal with a tagged Entry.
For other systems, Delta mode can be simulated by performing either delete, add, or a sequence of find and then applying the proper changes to the record before writing the entire record back with modify. This is something that the AL Connector can do by using the basic Adapter primitives, but the Adapter needs to indicate that this is desired functionality.

To enable Delta behaviour in an Adapter, first the Delta operation needs to be defined. The next option is to create an attribute deltaSavvy in the Delta schema. Without the deltaSavvy attribute, the AL Connector will simulate the Delta mode as described above. With the deltaSavvy attribute in place, the AL Connector not call findEntry first, but rather call modEntry operation directly where it is the Adapters job to inspect the attributes for tags and apply the appropriate commands against the target system.

Error handling

Throw exceptions in your Adapter code to let the calling AssemblyLine drop the user into error hooks of the AL Connector, such as:

throw new java.lang.Exception ("error message");

IBM Tivoli Directory Integrator 7.1.1