Managing Events and Actions
When a map is run, the transformation engine executes various events (for example, TransformationStarted and TransformationEnded) at different times during the transformation. You can choose to perform different actions when these events occur. For example, the engine executes a TransformationStarted event before any source records are read. You can use this event to initialize variables, create tables, or perform other actions.
Thus, events allow users to perform tasks when specified conditions are met. For example, you can:
• Receive notifications from the engine that certain things have occurred.
• Pre-process or post-process the records.
• Perform memory management tasks, such as initializing memory and cleaning up memory.
The advantage of event handling is that complex transformations with multiple record types on both source and target can be accomplished. Complex data manipulations, such as record aggregation, unrolling of data, transposing of data, can be performed in a simple way. These transformation capabilities are very powerful and can be controlled using the Event, Condition, and Action (ECA) rules.
ECA Rules
What the data looks like on the target side is determined by Field Mappings and Event Actions:
Field Mapping: What the target field value will be is determined by its "Field Mapping". Each target field can have a very simple field mapping like that of a constant string [for example, "myFieldValue"] or take on of the source field's values [for example, FieldAt("/SOURCE_1/Sheet1/StateName")]. A target field can take the value of some aggregated other field, or the target field can also take a value that is calculated using a very complex expression script.
Event Actions: How and when Field Mappings get executed is determined by ECA rules. The transformation engine executes various events at different times during a transformation. You can choose to perform different actions when these events occur. Most events return a TRUE or FALSE based on a condition. Separate actions can be defined for TRUE and FALSE conditions. For example, a condition can state that "if the balance field is <=2000" is TRUE then write the record to the target otherwise, reject the record because the balance should never be greater than 2000.
Note: Events and actions are filtered based on the connector capabilities and the nature of the schema. For example, for connectors that do not support hierarchical schemas, SubTreeStarted and SubTreeEnded events and their corresponding actions are not available.
Rules for Events added Using Map Wizard
The following are the rules that will be added for Map Wizard events.
Condition | Details |
|---|---|
Source is single record type and Target is single record type | Add a single source record to target record RecordStarted event, OutputRecord action. |
Source is single record, Target is multi-record or hierarchical with > 1 record type | Add SourceRecord event to each target record (can add for fivetargets). If target is hierarchical with a single root record, then the first event is SourceStarted, OutputRecord action. For records 2-X where X is not > 5 of the target, add a RecordStarted event, OuputRecord action. This may not be exactly what you need but will give an idea of what is required. You can later edit the events in the Map Editor. This scenario will likely be accurate for new hierarchical files that is based on the source schema or hierarchical files that have a single root record and few child records. |
Source is multi-record or hierarchical with > 1 record type and target has single record | Add a source record to the single record RecordStarted event, OutputRecord action for each source record. This may not be exactly what you need but will give an idea of what is required. You can later edit the events in the Map Editor. |
Both source and target are multi-record or hierarchical. | Add up to three source record to each of the first three RecordStarted events, OutputRecord events. This may not be exactly what you need but will give an idea of what is required. You can later edit the events in the Map Editor. |
For Joins, both the source and the join must be single record. The target must be single record. | Add one RecordStarted, Output record event/action from source to join and one RecordStarted, Output record event/action from join to target. |
Events and Actions
This topic provides the events and actions that are applicable for Actian DataConnect artifacts.
The following types of events are available:
• Map events: These are events and actions for the overall map. For more information, see Configuring Map Events.
• Record Events: Events occur during processing of source records.
• Source Events: Set conditions and actions for specific source.
• Target Events: Set conditions and actions for specific target
You can add, edit, and delete events in Simple and Advanced Views:
• In Simple View > Mapping tab, click Events to add events. To view the fields, click Fields.
• In Advanced View > Mapping tab, click the required source or target record for which you want to add the events.
The following topics are covered:
Adding Record Event
Each source record event is linked to a target record. You can add, delete, duplicate, and reorder record events. Only the source grid will have record specific events.
To add record events for a source record:
1. Do any of the following:
• In Simple View, click Events and in the source grid, click 
and select Record Event.
and select Record Event.• In Advanced View > Source tree view, click Events under the source record for which you want to add an event and click 
.
.The Add Record Events wizard is displayed.
You can also add record events for source records in the All Events view. To do this, in the source tree view, click All Events, click the arrow next to 
icon and select Record Event.
icon and select Record Event.2. Select the target for which you want to add an event and click Next.
A window is displayed where you can select an event and define event parameters, condition expressions, true and false actions, and action parameters.
3. In the Events section, click 
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters.
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters. You can do the following:
– Click 
to move the event up or click 
to move the event down.
to move the event up or click to move the event down. Note: The order of events is important because they will be executed in the order they are listed.
– To change the event, click within the cell and from the drop-down list, select another event.
– Click 
to delete an event.
to delete an event.– Click 
to copy an event.
to copy an event.4. On the True Actions tab, in the Actions section, click 
and select the required action. In the Action Parameters section, specify the values for the action parameters. For information about the actions and action parameters, see Actions and Action Parameters.
and select the required action. In the Action Parameters section, specify the values for the action parameters. For information about the actions and action parameters, see Actions and Action Parameters.You can do the following:
– Click 
to move the action up or click 
to move the action down.
to move the action up or click to move the action down. Note: The order of action is important because they will be executed in the order they are listed.
– To change the action, click within the cell and from the drop-down list, select another action.
– Click 
to delete an action.
to delete an action.– Click 
to copy an action.
to copy an action.5. In Condition Expression section, click 
and specify an expression in the EZscript Editor.
and specify an expression in the EZscript Editor.6. On the False Actions tab, specify the Actions and Action Parameters. The available actions and the action parameters are same as True Actions.
Note: If a conditional expression is added, you must specify the false action.
7. Click Finish.
The event is added to the Events view in the source grid.
Adding Source Event
To add source event:
1. Do any of the following:
• In Simple View, click Events. In the source grid, click 
and select Source Event.
and select Source Event.• In Advanced View > Source tree view, click Source Events under the source record for which you want to add an event and click 
.
.The Add Source Event wizard is displayed.
You can also add source events in the All Events view. To do this, in the source tree view, click All Events, click the arrow next to 
icon and select Source Event.
icon and select Source Event.The window to define events, actions, and conditions is displayed.
2. In the Events section, click 
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters.
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters. You can do the following:
– Click 
to move the event up or click 
to move the event down.
to move the event up or click to move the event down. Note: The order of events is important because they will be executed in the order they are listed.
– To change the event, click within the cell and from the drop-down list, select another event.
– Click 
to delete an event.
to delete an event.– Click 
to copy an event.
to copy an event.3. On the True Actions tab, in the Actions section, click 
and select the required action. In the Action Parameters section, specify the values for the action parameters.For information about the actions and action parameters, see Actions and Action Parameters.
and select the required action. In the Action Parameters section, specify the values for the action parameters.For information about the actions and action parameters, see Actions and Action Parameters.You can do the following:
– Click 
to move the action up or click 
to move the action down.
to move the action up or click to move the action down. Note: The order of action is important because they will be executed in the order they are listed.
– To change the action, click within the cell and from the drop-down list, select another action.
– Click 
to delete an action.
to delete an action.– Click 
to copy an action.
to copy an action.4. In Condition Expression section, click 
and specify an expression.
and specify an expression.5. On the False Actions tab, specify the Actions and Action Parameters. The available actions and the action parameters are same as True Actions.
Note: If a conditional expression is added, you must specify the false action.
6. Click Finish.
The event is added to the Source Events view in the source grid.
Adding Target Event
To add target event:
1. Do any of the following:
• In Simple View, click Events. In the target grid, click 
.
.• In Advanced View > Target tree view, click Target Events under the target record for which you want to add an event and click 
.
.The Add Target Event wizard is displayed.
You can also add target events in the All Events view. To do this, in the target tree view, click All Events, click the arrow next to 
icon and select Target Event.
icon and select Target Event.The window to define events, actions, and conditions is displayed.
2. In the Events section, click 
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters.
and select the required event. In the Event Parameters section, specify the values for the parameters. For information about the events and event parameters, see Events and Event Parameters. You can do the following:
– Click 
to move the event up or click 
to move the event down.
to move the event up or click to move the event down. Note: The order of events is important because they will be executed in the order they are listed.
– To change the event, click within the cell and from the drop-down list, select another event.
– Click 
to delete an event.
to delete an event.– Click 
to copy an event.
to copy an event.3. On the True Actions tab, in the Actions section, click 
and select the required action. In the Action Parameters section, specify the values for the action parameters.For information about the actions and action parameters, see Actions and Action Parameters.
and select the required action. In the Action Parameters section, specify the values for the action parameters.For information about the actions and action parameters, see Actions and Action Parameters.You can do the following:
– Click 
to move the action up or click 
to move the action down.
to move the action up or click to move the action down. Note: The order of action is important because they will be executed in the order they are listed.
– To change the action, click within the cell and from the drop-down list, select another action.
– Click 
to delete an action.
to delete an action.– Click 
to copy an action.
to copy an action.4. In Condition Expression section, click 
and specify an expression.
and specify an expression.5. On the False Actions tab, specify the Actions and Action Parameters. The available actions and the action parameters are same as True Actions.
Note: If a conditional expression is added, you must specify the false action.
6. Click Finish.
The event is added to the Target Events view in the target grid.
Events and Event Parameters
The following table provides information about the events and event parameters that can be defined for record, source, and target events.
Event Type | Event Name | Event Description | Event Parameter | Event Parameter Description |
|---|---|---|---|---|
Record Event | ErrorFound | Triggered when an error occurs during map execution. | - | - |
Record Event | GroupEnded | Triggered when the end of a group of records is detected in the input and before the next group starts. | group type | Determines the group boundary. The values are: • field list: The group boundary is determined by watching values for the specified list of fields from the source record. • expression: The group boundary is determined by watching the value computed by an expression. This event also occurs when the input stream ends. |
group key | Based on the selected group type, specify the group key: • If group type is field list, then click  to open the Create Field List window. Select the Source Fields and click  to move it to the Field List box. Click OK. The value appears in the Value column.• If group type is expression, then click  to open the EZscript Experssion Editor and specify an expression. | |||
Record Event | GroupStarted | Triggered when the start of a group of records is detected in the input. | group type | Determines the group boundary. The values are: • field list: The group boundary is determined by watching values for the specified list of fields from the source record. • expression: The group boundary is determined by watching the value computed by an expression. This event also occurs when the input stream ends. |
group key | Based on the selected group type, specify the group key: • If group type is field list, then click  to open the Create Field List window. Select the Source Fields and click  to move it to the Field List box. Click OK. The value appears in the Value column.• If group type is expression, then click  to open the EZscript Experssion Editor and specify an expression. | |||
Record Event Source Event | RecordEnded | Triggered after processing a record is completed, before reading the next record. This event is useful for working with grouped sets of records where there are no distinct boundaries between the different groups. Note: Field values for the new record are not visible to mapping expressions when this event occurs. | - | - |
Record Event | RecordRejected | Triggered when a source record rejected target. | reason | Specify the reason for rejecting the record. |
Record Event Source Event | RecordStarted | Triggered after reading each instance of the source record. | - | - |
Record Event Source Event | SourceStarted | Triggered before records are read in the input. | - | - |
Record Event Source Event | SourceEnded | Triggered when processing a source has been completed. | - | - |
Record Event | SubTreeStarted | Triggered when the start of a new instance of a sub-tree is detected in the input. | - | - |
Record Event | SubTreeEnded | Triggered after all the records representing a complete subtree of a hierarchical structure are read from the input stream. This event occurs before the source transitions to the parent or to a sibling of the current tree. This event also occurs when the input stream ends. | - | - |
Record Event | UserDefinedEventDetected | Triggered when a user-defined event is raised. | user-defined event name | Specify a name for the user-defined event. You can define and raise user-defined events to monitor events other than the pre-defined events. You can use the RaiseUserDefinedEvent event action and the UserDefinedEventDetected event. In a map, you can define the RaiseUserDefinedEvent event action on the False Action tab and specify the event name and the parameter string. The UserDefinedEventDetected event collects the User Defined Event based on the event name. When the map is run, the parameter string defined in the UserDefinedEventDetected event is executed. |
Target Event | RecordOperationStarted | Triggered just before modifying an output record (insert, delete, update, upsert, blank for any operation). | target record address | If the record address parameter is specified, this event is triggered every time that record is output (operation is ignored). If no record address is specified, then any record whose operation matches the operation parameter will trigger the event. If neither is specified, then every record will trigger the event. |
operation | Select one of the following as the operation that must be performed when the event is triggered: • insert • update • delete • upsert | |||
Target Event | RecordOperation Ended | Triggered after modifying an output record (insert, delete, update, upsert, blank for any operation). If the record address parameter is specified, this event is triggered every time that record is output (operation is ignored). If no record address is specified, then any record whose operation matches the operation parameter will trigger the event. If neither is specified, then every record will trigger the event. | Same as RecordOperationStarted. | |
Actions and Action Parameters
The following table provides information about the actions and action parameters that can be defined for record, source, and target events.
Event Type | Action | Action Description | Action Parameter | Action Parameter Description |
|---|---|---|---|---|
Record Event | Stop | Stops the transformation and returns the return code. | reason code | Returns the integer value as the return code. |
Record Event | Aggregate | Evaluates the aggregation functions for aggregate fields in the target record. | - | - |
Record Event | Break | Breaks the execution process. Execution resumes with the next link on the current source record. | - | - |
Record Event | ClearRecord | Clears the data values from the fields for the target record. | target record name | Select the target record. |
cascade | Select True to clear child records. Else, select False | |||
Record Event | ClearRecordSet | Deletes all the rows in the intermediate target. | intermediate target name | Select the intermediate target name. |
Record Event | Discard | Current input record is rejected. | - | - |
Record Event Source Event Target Event | ExecuteCommand | Triggers the command that must be executed by the target. Note: Only multimode connectors support the ExecuteCommand action | target name | Select the target. |
command | Specify the command to be executed. | |||
command type | Indicates how the SQL string or command is processed before it is passed to the connector. Select any of the following command type processor: • plain_text: Uses the string as the SQL command and additional processing of the command is not required. • expression: Command is evaluated as an expression and the return value is passed to the connector as the SQL command. • preprocessor: Command is preprocessed using the SQL statement preprocessor (DJX/DJXBEGIN/DJXEND) and the result is passed to the connector. | |||
Record Event Source Event Target Event | ExecuteExpression | Executes the expression. | expression | Click  to open the EZscript Experssion Editor and specify an expression. |
Record Event | OutputRecord | Evaluates the target field expressions for a record and writes it to the target. This action does not evaluate the aggregate fields. | preserve | After the output operation, the target record values are cleared if this parameter is set to false. |
record count | Click  to open the EZscript Experssion Editor and specify an expression. | |||
Record Event | OutputRecordSet | Uses a secondary source or an intermediate target as a source for a downstream target. | source name | Select the source or to be processed. |
preserve | After the output operation, the target record values are cleared if this parameter is set to false. | |||
max record count expression | Click  to open the EZscript Experssion Editor and specify an expression to limit the number of records computed in the output. | |||
Record Event | RaiseUserDefinedEvent | Raise a user-defined event and optionally pass a string containing event parameter data. | event name | Name of the user-defined event. |
parameter string | String containing event parameter data. | |||
Record Event | Reject | Signals that the current input record must be rejected. | reason code | Allows you to associate the reject with an integer value that can be mapped to the reason for the reject. |
Record Event | Terminate | Terminates the map execution and causes the engine to return a successful return code. | - | - |
Editing Event Records
You can only edit the event parameters, associated actions and the action parameters for the defined events. If you want to change the events, then delete the event and add a new event.
To edit an event record:
1. Go to any of the following views as required:
• In Simple View, click Events - Displays source and target grids with the defined events.
• In Advanced View:
– Source tree > All Events - Displays source and record events defined for a map
– Source tree > Events - Displays all events defined for a source record
– Source tree > Source Events - Displays source events defined for a specific source
– Target tree > All Events - Displays all target events defined for a map
– Target tree > Target Events - Displays target events defined for a specific target
2. Click the event record that you want to edit and click 
.
.The window where you can edit the event parameters, actions, and action parameters is displayed.
3. Edit the required details and click Finish. For information about the event parameters and actions, see Events and Event Parameters and Actions and Action Parameters.
Duplicating Events to Other Targets
You can duplicate single or multiple source events to other targets in Advanced View. You cannot do it in Simple View.
To duplicate events:
1. In Advanced View, go to the following node:
• Source tree > Source Events - Displays source events defined for a specific source.
2. Click the event record that you want to duplicate and click 
. To select multiple events, press and hold the Ctrl key.
. To select multiple events, press and hold the Ctrl key.The Duplicate Event window is displayed.
3. Select one or more targets to which you want to duplicate the selected event.
4. Select any of the following options:
• Insert Only: Adds the event to the selected targets.
• Insert and Override: Overrides existing events in the selected targets.
5. Click Finish.
The copy of the event is added to the selected targets.
Reordering Events in Source and Target Grids
To reorder events:
1. Go to any of the following views as required:
• In Simple View, click Events - Displays source and target grids with the defined events.
• In Advanced View:
– Source tree > All Events - Displays source and record events defined for a map
– Source tree > Events - Displays all events defined for a source record
– Source tree > Source Events - Displays source events defined for a specific source
– Target tree > All Events - Displays all target events defined for a map
– Target tree > Target Events - Displays target events defined for a specific target
2. Click the event record that you want to move up and click 
.
.3. Click the event record that you want to move down and click 
.
.Deleting Events in Source and Target Grids
To delete an event:
1. Go to any of the following views as required:
• In Simple View, click Events - Displays source and target grids with the defined events.
• In Advanced View:
– Source tree > All Events - Displays source and record events defined for a map
– Source tree > Events - Displays all events defined for a source record
– Source tree > Source Events - Displays source events defined for a specific source
– Target tree > All Events - Displays all target events defined for a map
– Target tree > Target Events - Displays target events defined for a specific target
2. Click the event record that you want to delete and click 
.
.A message asking for confirmation is displayed.
3. Click Yes.
The event is deleted.
Managing Events and Actions in Advanced View
In Advanced View, you can add, edit, and delete events for the following nodes in both Source and Target tree view:
• All Events node
• All Records > Individual Record > Events node
• Source Events node (only in Source tree view)
• Target Events node (only in Target tree view)
Note: The procedure to add, edit, and delete events is the same. Only the initial navigation is different.
Managing Events in All Events
You can manage both record events and source events when you are in Source > All Events view.
Similarly, you can manage record events and target events when you are in Target > All Events view.
To manage events for source or target in All Events node:
1. In the Source or Target tree view, click All Events.
2. To add an event, see Adding Event.
3. To edit an event, see Editing Event.
4. To delete an event, see Deleting Event.
Managing Events for Each Record
To manage events for each record in source or target:
1. In the Source or Target tree view, expand All Records.
2. Expand the required record number. For example, R1, R2, R3, and so on.
3. Click Events.
4. To add an event, see Adding Event.
5. To edit an event, see Editing Event.
6. To delete an event, see Deleting Event.
Managing Events in Source Events
To manage source events:
1. In the Source tree view, click Source Events.
2. To add an event, see Adding Event.
3. To edit an event, see Editing Event.
4. To delete an event, see Deleting Event.
Managing Events in Target Events
To manage target events:
1. In the Target tree view, click Target Events.
2. To add an event, see Adding Event.
3. To edit an event, see Editing Event.
4. To delete an event, see Deleting Event.
Adding Event
To add an event:
1. Click 
.
.The Add Event(s) window is displayed.
2. If you have clicked 
for All Events node, then select the type of event that you want to add:
for All Events node, then select the type of event that you want to add:• Record Events - Select the individual record from the drop-down list. By default, R1 is selected.
• Source Events
You can select only one type of event at a time.
This step is not applicable if you have clicked 
for Source Events node or Target Events node.
for Source Events node or Target Events node.3. Select the required event handlers or search for the event handler by typing the word in the Search field.
If an event handler is already added, the check box for that event handler is grayed-out and you cannot select it.
4. Click Next.
If you have selected OnDataChange as the event handler, then a page that allows to set the event parameters is displayed. Go to Step 5.
If you have selected any other event handler, then a page that allows you to select actions and specify the parameters for the selected event handlers is displayed. Go to Step 7.
5. For OnDataChange event handlers, specify the following for each event handler:
• Data Change Monitor Expression
• Trigger Suppression
6. Click Next.
A page that allows you to select actions and specify the parameters for the selected event handlers is displayed.
7. In the Action section, click 
to add an action. By default, Stop action is added.
to add an action. By default, Stop action is added.8. If you want to change the Stop action, click the name and from the drop-down list, select the required action.
You can also do the following:
• To delete an action, click the action and then click 
.
.• To copy an action, click the action that you want to copy and then click 
.
.• To move the order of the actions:
– Click 
to move the action up.
to move the action up.– Click 
to move the action down.
to move the action down.Note: The order of actions is important because they will be executed in the order they are listed.
9. After adding the actions, click each action.
The Parameters section displays the relevant parameters for the selected action.
10. For each parameter, click the Value field and specify a value. When you click within the Value field, 
or a drop-down list may be available. If you click 
, you can add an EZscript expression. If you select the drop-down list, you can either select a value or select <Build Expression...> to add an EZscript expression. For information about adding EZscript expressions, see Scripting.
or a drop-down list may be available. If you click , you can add an EZscript expression. If you select the drop-down list, you can either select a value or select <Build Expression...> to add an EZscript expression. For information about adding EZscript expressions, see Scripting.11. Click Finish.
The events are saved.
Editing Event
To edit an event:
1. Click the event that you want to edit and click 
.
.The Edit Event window is displayed.
2. Edit the event parameters, actions, and action parameters and click Finish.
For information about the fields, see Adding Event.
The changes are saved.
Deleting Event
To delete an event:
1. Click the event name that you want to delete and click 
.
.A message asking for confirmation is displayed.
2. Click Yes.
The selected event is deleted.
Last modified date: 02/01/2024