Script Connector

The Script Connector enables you to write your own Connector in JavaScript.

A Script Connector must implement a few functions to operate. If you plan to use it for iteration purposes only (for example, reading, not searching or updating), you can operate with two functions only. If you plan to use it as a fully qualified Connector, you must implement all functions. The functions do not use parameters. Passing data between the hosting Connector and the script is enabled by using predefined objects. One of these predefined objects is the result object, which is used to communicate status information. Upon entry in either function, the status field is set to normal, which causes the hosting Connector to continue calls. Signaling end-of-input or error is done by setting the status and message fields in this object. Two other script objects are defined upon function entry, the entry object and the search object.

Predefined script objects

main

The Config Instance (RS object) that is running.

task

The AssemblyLine this Connector is a part of

system

A UserFunctions object.

The result object

setStatus (code)

• 0 - End of Input
• 1 - Status OK
• 2 - Error

setMessage (text)

Error message.

The config object

This object gives you access to the configuration of this AL component, and its Input and Output schema -- note that the getSchema() method of this object has a single Boolean parameter: true means to return the Input Schema while false gets you the Output Schema.

The entry object

The entry object corresponds to the conn Entry for a Connector (or Function, when scripting an FC.)

See The Entry object for more details.

The search object

The search object gives you access to the searchCriteria object (built based on Link Criteria settings.) See The Search (criteria) object for more details.

The connector object

A reference to this Connector.

This could be useful for example when returning multiple Entries found in the findEntry() function, with code similar to this:

	function findEntry() {
		connector.clearFindEntries();
		// Use the search object fo find Entries, and
		for ( entry = all Entries found) {
			connector.addFindEntry(entry)
		}
		if (connector.getFindEntryCount() == 1)
			result.setStatus(1);
		else
			result.setStatus(0);
	}

Functions

The following functions can be implemented by the Script Connector. Even though some functions might never be called, it is recommended that you insert the functions with an error-signaling code that notifies the caller that the function is unsupported.

initialize

This function initializes the Connector. It is called before any of the other functions and should contain code that initializes basic parameters, establishes connections, and so forth.

selectEntries

This function is called to prepare the Connector for sequential read. When this function is called it is typically because the Connector is used as an Iterator in an AssemblyLine.

getNextEntry

This function must populate the Entry object with attributes and values from the next entry in the input set. When the Connector has no more entries to return, it must use the result object to signal end-of-input back to the caller.

findEntry

The findEntry function is called to find an entry in the connected system that matches the criteria specified in the search object. If the Connector finds a single matching entry, then the Connector populates the entry object. If no entries are found, the Connector must set the error code in the result object to signal a failure to find the entry. If more than one entry is found, then the Connector might populate the array of duplicate entries. Otherwise, the same procedure is followed as when there are no entries found.

modEntry

This function is called to modify an existing entry in the connected system. The new entry data is given by the entry object, and the search object specifies which entry to modify. Some Connectors might silently ignore the search object, and use the entry object to determine which entry to modify.

putEntry

This function adds the entry object to the connected system.

deleteEntry

This function is called to delete an existing entry in the connected system. The search object specifies which entry to delete. Some Connectors might silently ignore the search object, and use the entry object to determine which entry to delete.

queryReply

This function is called when the Connector is used in Call/Reply mode.

querySchema

The querySchema() function is used to discover schema for this Connector. If implemented, a vector of Entry objects is returned for each column/attribute it discovered. The querySchema() function is only called when you "Open/Query" in the attribute map (not when you click the quick discovery button).

In order to support Schema discovery your Script Connector or -FC can contain code like this:

function querySchema() {
		config.getSchema(true).newItem("name-in");
		config.getSchema(true).newItem("address-in");
		config.getSchema(false).newItem("name-out");
		config.getSchema(false).newItem("address-out");
	}

This would create two items in the input and output schemas respectively. Check the SchemaConfig and SchemaItemConfig API (in the Javadocs) for more details.

terminate

This function is called when the Connector has finished its task. It should contain code that frees up any resources (for example, locks, connections) taken during its work.

According to the various modes, these are the minimum required functions you need to implement:

Configuration

The Connector needs the following parameters:

Edit Script...

This button opens a window where you can create your own script code. An empty skeleton will already be present.

Keep Global State

If this parameter is checked (default), then any global variables defined in the script will be kept after the Connector terminates, and they will be present with their last values when the Connector is re-initialized.

Note:

With this parameter checked (which is the default) the behavior of this Connector changed in Tivoli® Directory Integrator v7.1.1. If you need global variables to be reinitialized along with the Connector, you should either uncheck this parameter, or set these variables inside the initialize() method.

External Files

If you want to include external script files at runtime, specify them here. Specify one file on each line. These files are started before your script.

Include Global scripts

Include global scripts from the Script Library.

Detailed Log

If this parameter is checked, more detailed log messages are generated.

Examples

Navigate to the TDI_install_dir/examples/script_connector directory of your IBM® Tivoli Directory Integrator installation.

See also