Metamerge logo
Search

Advanced Search
*
*
*
* HOME DOCUMENTS & RESOURCES DOWNLOADS EARLY TECH ACCESS SUPPORT FAQ KNOWN ISSUES OLD VERSIONS
*

 

Hooks

An AssemblyLine relies on certain primitive functions like the Connector objects getnext() that will get the next record from the underlying Connector.

The AssemblyLine objects (EventHandler, Connector) have a mechanism called Hooks allowing you to

  1. Override  the basic fetch/put functions for Connectors (see Override Hooks)
  2. Respond to events signaled by the AssemblyLine: For example, an Iterator Connector will have a GetNext fail hook that can be programmed to log (or send mail about) input errors. See Failure Hooks
  3. Modify the flow of the AssemblyLine (like skipping a Connector).

Hooks are usually called in the AssemblyLine execution as part of the flow control. If for some good reason you actually want to call a hook yourself, that can be achieved by the JavaScript line  myConnector.trigger("hookName");   where myConnector is the name you gave your Connector and hookName is the internal name of the Hook.

Enabling/Disabling Hooks

By default, all Hooks are disabled. As soon as you add some code to a particular Hook, the Admin Tool will mark that Hook as enabled. If you do not want a Hook to be used, you can uncheck the Enabled flag for that Hook. This allows you to keep the code in your Hook in case you later want to use the code again.

In some cases, the control flow in an AssemblyLine depends on whether a particular Hook is enabled or not. Until version 4.6.5, a Hook would only be enabled if it contained some code, even if that code was only a comment. From version 4.6.6, a Hook is enabled if it is marked as enabled, even if it contains no code.

Override Hooks

'For every Connector mode (except Passive mode) there is a mode specific Override Hook. If this Hook is enabled, first the "Before Execute" Hook is called (if it is enabled), and then the Override Hook, before the flow control continues with the next Connector in the AssemblyLine. No other Hooks are called, except Failure Hooks (if necessary).

For a Connector in Update mode, there are also "Override Add and Override Modify Hooks. After the Connector has decided that it wants to perform a Modify or Add operation (based on whether there already exists a matching Entry in the data source), the appropriate Hook is called if it is enabled. After the Hook has finished, the flow control continues with the "After Update" and "Update OK" Hooks.

Failure Hooks

Failure Hooks allow you to respond to events signaled by the Connector. For example, an Iterator Connector will have an "On Error" hook that can be programmed to log (or send mail about) input errors, or you can modify the flow of the AssemblyLine (like skipping the rest of the AssemblyLine).

When a failure occurs in a Connector, this is what happens:

  1. The error counter is increased by one.
  2. The Connector's  mode specific "On Error" Hook is called
  3. If that Hook is not enabled, the Connector's default ("Top Level") "On Error" Hook is called.
  4. If no Hook is enabled to catch the error, the AssemblyLine will either ignore this Connector (if this is a Connector in Delete mode), skip the rest of the AssemblyLine (if this is a Connector in Lookup mode), or abort the entire task.
  5. After the Hook, the AssemblyLine continues with the next Connector. If you want another behavior, you should program it in the Hook with one of the methods described in .flow of the AssemblyLine.

Hooks called on other events

The following Hooks are not Failure Hooks, but still signal an event that could be taken care of:

o Multiple Entries Found - Lookup Mode
If the "Allow Duplicates" flag is not set and there are more than one matching entry, the Connector calls this Hook if it is enabled. If the Hook is not enabled, this is treated as a failure. After this Hook is called, the Lookup proceeds, using the Entry set by the myConnector.setCurrent() method. If you have neglected to call this method, the Entry used is the one returned by myConnector.getNextDuplicateEntry(). This is normally the first Entry found, but if you have browsed through all the Entries using the myConnector.getNextFindEntry() method, this will be null, causing a lookup failure.

o Multiple Entries Found - Update Mode
When there are more than one matching entry, the Connector calls this Hook if it is enabled, otherwise this is treated as a failure. After this Hook is called, the Update proceeds, using the Entry set by the connectorName.setCurrent() method. If you have neglected to call this method, the Entry returned by connectorName.getNextFindEntry() is used. This is normally the first Entry found, but if you have browsed through all the Entries using the connectorName.getNextFindEntry() method, this will be null, causing an add operation to be performed.

o Multiple Entries Found - Delete Mode
When there are more than one matching entry, the Connector calls this Hook if it is enabled, otherwise this is treated as a failure. After this Hook is called, the Delete proceeds using the Entry set by the myConnector.setCurrent() Method.

o Modify NoChanges - Called in some cases in a Connector in Update mode. This causes the "After Modify" Hook to be skipped, but the "After Update" and "Update OK" Hooks are still called.

List of Hooks

These Hooks are common for all Connectors

Admin Tool Name Internal Name Description
Before Initialize  before_initialize  Called before initialize of the Connector is attempted
After Initialize  after_initialize  Called after the Connector has been initialized
On Error (In Prolog) initialize_fail  Called when the Connector initialization fails. If no Hook is enabled to catch the error, the AssemblyLine aborts. If a Hook is enabled, it should take the proper action, which could possibly be to abort the AssemblyLine.
Before Execute  before_execute  Called before every execution of the Connector
On Success (Dataflow, After ConnectorMode) default_ok Called when a Connector operation has succeeded, after all other OK hooks.
On Error (Dataflow, After ConnectorMode) default_fail Called when an error occurs during a Connector operation, unless the mode specific fail Hook is enabled. (GetNext fail, AddOnly fail, etc.)
Before Close  before_close  Called before the Connector is closed. The work object is the last entry processed by the AssemblyLine
After Close  after_close  Called after the Connector was closed. The work object is the last entry processed by the AssemblyLine
On Error (After Epilog) close_fail  Called when the Connector fails to close after the AssemblyLine has finished. If no Hook is enabled to catch this error, it is ignored. This Hook is only available from version 4.6.6.

These Hooks are available for Connectors in Iterator mode

Before Selection  before_selectEntries  Called before the Connector selects entries as part of the initialization
After Selection  after_selectEntries  Called after the Connector has selected entries (in the initialization)
Before GetNext  before_getnext  Called before the Connector attempts to get the next item
After GetNext  after_getnext Called after a getnext is successfully performed on the Connector, before mapping is done. An object named conn is available for inspecting or changing the attributes retrieved from the Connector
On Success  get_ok  Called after a successful get operation
On Error  get_fail  Called when the getnext operation fails

These Hooks are available for Connectors in AddOnly mode

Before Add  before_add  Called before an add operation is attempted
After Add   after_add  Called after an entry was successfully added
On Success  addonly_ok  Called after a successful add operation
On Error  addonly_fail  Called when the add operation fails

These Hooks are available for Connectors in Delete mode

On Multiple Entries delete_multiple When more than one entry matches the Link Criteria,, the Connector calls this Hook if it is enabled, otherwise delete fail is called. See Multiple Entries Found - Delete Mode
Before Delete  before_delete  Called before delete is attempted
After Delete after_delete  Called after an entry was deleted
On Success delete_ok  Called after a successful delete operation
On Error delete_fail  Called when the delete operation fails

These Hooks are available for Connectors in Lookup mode

Before Lookup before_lookup  Called before lookup is attempted
On Multiple Entries lookup_multiple When the result is more than one matching entry, and the "Allow Duplicates" flag is not set, the Connector calls this Hook if it is enabled, otherwise Lookup fail is called. See Multiple Entries Found - Lookup Mode
After Lookup  after_lookup  Called after an entry was found, before mapping is done. An object named conn is available for inspecting or changing the attributes retrieved from the Connector
On Success lookup_ok  Called after a successful lookup operation.  If Allow Duplicates is checked, you might want to iterate through the entries found using the getNextDuplicateEntry() function of rscTaskComponent.  An example of how this is used is found in the following example.  Unpack the zip-file and look at the On Success hook of the Lookup Connector where the following code is found:

if ( Lookup.getDuplicateEntryCount () > 1 ) {
  var nextEntry;
  while ( ( nextEntry = Lookup.getNextDuplicateEntry () ) != null ) {
  work.addAttributeValue ( "EMAIL_ADDR", nextEntry.getString (     "EMAIL_ADDR" ) );
}
}

On Error lookup_fail  Called when the lookup operation fails (no entries found, or multiple entries found and the corresponding Hook not enabled)

These Hooks are available for Connectors in Update mode

Before Update  before_update  Called before an update is attempted (add or modify)
Multiple Entries Found update_multiple Called when there are more than one matching entry. If the Hook is not enabled and there are multiple entries, the update is not performed. See Multiple Entries Found - Update Mode
Before Modify  before_modify  Called before a modify operation is attempted
Modify NoChanges  modify_nochange  Called when an Update Connector with the Compute Changes flag set, reports no changes to update
Before Applying Changes  modify_apply Called immediately before a modification is performed. This Hook is called only when the Compute Changes flag is set. If no changes apply, the Modify No Changes Hook is called instead
After Modify  after_modify  Called after an entry was modified
Before Add  before_add  Called before an add operation is attempted
After Add   after_add  Called after an entry was successfully added
After Update  after_update  Called after successful update (add/modify)
On Success  update_ok  Called after a successful update operation (add / modify)
On Error  update_fail  Called when the update operation fails (add / modify)
 

 

*
  Metamerge Integrator version 4.6 ©Copyright Metamerge AS 2000-2002 Last edited 2002-06-10 contact us