| |
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
- Override the basic fetch/put functions for Connectors (see Override Hooks)
- 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
- 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.
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.
'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 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:
- The error counter is increased by one.
- The Connector's mode specific "On Error" Hook is called
- If that Hook is not enabled, the Connector's default ("Top Level") "On
Error" Hook is called.
- 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.
- 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) |
| |
|