To implement the TDI Connector modes, AssemblyLine 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 AssemblyLine 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 we 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 AssemblyLine Connector.
The following are the methods that a developer has to consider when implementing a TDI connector in Java or JavaScript. Please refer to Appendix E. Implementing our 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.
| Iterator | Lookup | AddOnly | Update | Delete | Delta(2) | CallReply | Server(3) | |
|---|---|---|---|---|---|---|---|---|
| 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:
The Adapter AssemblyLine 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 AssemblyLine. 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 AssemblyLine 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 AssemblyLine cycles. It is used to
store attributes that the AssemblyLine needs throughout its lifecycle. The next
section will show further use of it.
All attributes that are defined in the schema of the $initialization
operation of the Adapter are displayed in the configuration panel
of the AssemblyLine 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 AssemblyLine Connector. The Adapter could then define a search
base in an LDAP connector as:
These
attributes will be available at the initialization time of the Adapter, which by default is the same time as the calling AssemblyLine is initialized, unless one of the mechanisms described above in section Flexible connector initialization is utilized.
The link criteria defined in the AssemblyLine 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:
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.
When the Adapter operations are called through the AssemblyLine Connector, the work Entry is populated with the attributes in the output map
of the AssemblyLine Connector. On return, the AssemblyLine Connector expects returned
attributes either in work, or in the conn object
as described in the next sections.
The Adapter must use script methods such as:
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 AssemblyLine 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.
The modes iterator, lookup and callreply, return data to the calling AssemblyLine and populate the output map
of the AssemblyLine Connector. The simplest way to return attributes to the
calling AssemblyLine 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:
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 AssemblyLine Connector. To indicate end of data by the iterator, use
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 AssemblyLine Connector in the calling AssemblyLine.
The example illustrates two ways to return multiple records to
the calling AssemblyLine. 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.
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 AssemblyLine as in the work object.
To indicate an error situation where the AssemblyLine 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.
A user of the Adapter will want to discover the schema of the Adapter.
This is typically done when configuring the AssemblyLine 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 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.
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 AssemblyLine Connector
will simulate the Delta mode as described above. With the deltaSavvy
attribute in place, the AssemblyLine 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.
Throw exceptions in your Adapter code to let the calling AssemblyLine
drop the user into error hooks of the AssemblyLine Connector, such as:
Adapter configuration through the $initialization operation
cn=...,ou={op-entry.ou}
Understanding the link criteria
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 */
Attribute mapping
From the calling AssemblyLine into the Adapter
email = work.getString("email");
Return data from the Adapter to the calling AL
work.removeAttribute("attributeName");
...
work.newAttribute("conn");
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);
Status indication
Implementing Query Schema
Delta mode
Error handling
throw new java.lang.Exception ("error message");