OIEP - Event-Based - Event Triggering Definitions Tab

When Event Queue has been selected as the data source in an outbound integration endpoint (OIEP), or when setting up an event processor (EP), you can specify if core events (modify, delete, or create events) should be collected by the OIEP or EP for specific object types.

Workspace revisable objects, such as a product, generate an event when data changes are approved.
Global revisable objects, such as an attribute or an entity storing customer data, generate an event as soon as the data changes because approval is not available or required.

Event triggering definitions define what changes (events) are important and should be monitored by the OIEP or EP. For an OIEP, changes to any element defined on this tab are then formatted based on the output template and ultimately queued for export. For an EP, changes to any element defined on this tab are then handled by the selected core processor. For details about event generation, refer to the Events section of the System Setup documentation here.

For event-based OIEPs or EPs, the Event Triggering Definitions tab allows you to add or edit the available triggers. At a minimum, you must set an Object Type trigger before the OIEP or the EP can be enabled to queue events. Additional triggers can be added to further limit the data monitored by the OIEP. For more information, refer to the section for each trigger below.

Important: For an OIEP, an output template must be created for each event trigger, otherwise the triggered data will not be exported. For more information, refer to OIEP - Event-Based - Output Templates Section here.

Triggering Object Types Section

Triggering object types are used to filter the data being monitored by the OIEP. For example, if you are only interested in exporting data when a change is made on a specific object type, there is no reason for the OIEP to listen to events happening on other object types. Setting a trigger on only the required object type reduces the load on the OIEP.

Consider the following during configuration:

If functionality should vary by object type, a unique endpoint should be created for each object type.
Common setup is to include at least one attribute or attribute group unless the integration endpoint handles System Setup data only or Create / Delete events only.
If standard object types (product, entity, classification) are selected as triggers and the output template includes a Modify event, at least one attribute or attribute group must be selected to trigger the Modify event.

Object Types

The Triggering Object Types section allows you to identify object type(s) that are important for this OIEP. The OIEP will listen for events on these object types to generate the desired output as defined by the output template configuration. When listening for events on changes to objects like attributes, the object type for these must be selected as well. All object types can be added in a single row unless business rules are used to filter and process events (functionality described below).

Keep in mind that events are triggered based on the revisability setting of the object type. Global revisable events are triggered on a change transaction. Workspace revisable events are triggered on approval. For more information, refer to the Events section of the System Setup documentation here.

Important: The OIEP cannot be enabled or queue events until at least one object type is set as a trigger.

To select the object types:

Click the Add Object Type link, then browse or search for the relevant object type.
While the most commonly used object types are displayed in the browsing area, use Search to find other object types.
Any System Setup data (references, attributes, units, etc.) can be selected.
At least one object type must be selected.

Event Filter

Event filters are business conditions that can be added for each row of the Object Type Triggering section and can be used to apply additional event filtering. Event filters are run after any required approval, if applicable, and can be used in place of a pre-processor. Despite being created on an OIEP, an event filter runs at the time of event generation. If the condition evaluates to true, the event is written and registered on the event queue. When the condition evaluates to false, the event is not written at all unless a corresponding derived event is generated.

For example, when a change happens on a parent object, but only the children of this parent need to be output, a business condition can be created to filter out the parent. Then, a business action (refer to the Generate Event section below) can trigger an export of the children.

Conditions used as event filters are typically written in JavaScript since the built-in condition options, in most cases, will not provide the required flexibility.

For JavaScript based event filter conditions, the following available binds are of special relevance:

Event Type binds in a derived event so you can check if the event currently being handed is of a specific derived event type.
Current Event Type tests if the event currently being handed is a BasicEventType or a DerivedEventType. Assuming that 'Current Event Type' is bound to the variable 'currentEventType':

if (currentEventType instanceof com.stibo.core.domain.eventqueue.BasicEventType) {
// It is a core event
}
if (currentEventType.equals(com.stibo.core.domain.eventqueue.BasicEventType.Modify)) {
// It is a core Modify event
}

You can also test derived events and if you have created an 'Event Type' binding, test if the current event is of a specific type. Assuming that 'Current Event Type' is bound to the variable 'currentEventType' and the derived event 'webModify' is bound to the variable 'webModify':

if (currentEventType instanceof com.stibo.core.domain.eventqueue.DerivedEventType) {
// It is a derived event
}
if (currentEventType.equals(webModify)) {
// It is a derived WebModify event
}

Approve Context lets you compare an object in Main and Approved before the actual synchronization is carried out. It is important to understand that event filter conditions are evaluated immediately when events are generated. If the event is generated based on an approval, in the event filter condition, you will have access to the Approved Context. Refer to the Approve Context Bind section of the Resource Materials online help (here) or the 'ApprovePlugin.ApproveContext' interface in the Public Java API JavaDoc.

For more information, refer to Event-Based OIEP Example Business Rules for Derived Events here.

Generate Event

Event generators are business actions that run after approval (when approval is required) and can be added for each row of the object type triggering section. The purpose of an event generator is to produce derived events based on other events (most often core events). New core events cannot be generated. For more information, refer to Derived Events of the System Setup documentation here.

Event generators have access to the current event regardless of the chosen event filter, and an event filter is not required. This means derived events can be generated from events discarded by the filter. As with event filters, the event generator logic is also executed immediately when an event is generated.

Generated actions must typically be formulated in JavaScript. In addition to the binds mentioned in the event filter section above, the following are of special relevance for event generators.

Current Event Queue lets you bind in the current event queue so that you can put new derived events on the queue (after filtering). Assuming that 'Current Event Queue' is bound to 'currentEventQueue', the derived event type 'webModify' is bound to the variable 'webModify', and 'Current Object' is bound to 'currentObject', an event can be generated as follows:
```
currentEventQueue.queueDerivedEvent(webModify, currentObject);
```
Event Queue lets you place an event on a queue different from current. Use this bind if you produce events from actions not hooked in as generators.

Important: Avoid creating an endless loop by considering that any derived event generated by an event generator for the current event queue will pass through the object type filter and any event filters and event generators again.

For more information, refer to Event-Based OIEP Example Business Rules for Derived Events here.

Triggering Attributes Section

Triggering Attributes are used to filter the data being monitored by the OIEP in conjunction with the Triggering Object Types section. When a Triggering Attribute is defined, and that attribute's value changes for objects of the object types selected in the Triggering Object Types section, events are registered. The 'Triggering Attributes' section is a positive list, so if no attributes are selected, events will not be registered when, for example, a value changes and the object holding the value is approved.

Be aware that you can select both revisable and externally maintained attributes, and events are generated as follows:

Changes to values for externally maintained attributes and global revisable entities cause an event to be generated immediately.
Changes to values for revisable attributes cause an event to be generated when the object holding the values is approved.

For more information, refer to the Events section of the System Setup documentation here.

Click Add Attribute, then browse or search for the relevant attribute(s) and/or attribute group(s).
At least one attribute or attribute group must be selected, unless the integration handles ONLY System Setup data OR Create / Delete events.
When an attribute or attribute group is selected as a trigger, an output template must be configured with a Modify event or the endpoint will skip the event since it cannot find a corresponding template. For more information, refer to the OIEP - Event-Based - Output Templates Section here.

Triggering Table Types Section

The Trigger Table Types section allows you to specify (filter) table types for which you want events registered when tables owned by objects of the type are listed in the Triggering Object Types section change. Common setup is to use tables, and this setting serves only for print output.

Click Add Table Type, then browse or search for the relevant table type. Modifications to the table configuration on the product. For example, adding, removing, or modifying the table rows or columns; or changing the data on a free text cell followed by an approval will trigger an event for the endpoint.

Reference Type Triggers Section

Use reference / link types to define (filter) which reference / link types to listen to for changes. This is a positive list so only the items listed are triggers. If functionality should vary by object type, a unique endpoint should be created for each object type.

Be aware that you can select both revisable and externally maintained reference / link types and events are generated as follows:

Changes to values for externally maintained reference / link types cause an event to be generated immediately if an object type on which the reference is valid is selected as a triggering object type.
Changes to values for revisable reference / link types cause an event to be generated when the object holding the values is approved if an object type on which the reference is valid is selected as a triggering object type.

For more information, refer to the Events section of the System Setup documentation here.

Click Add Reference Type, then browse or search for the relevant reference type.

Triggering Data Container Types

When monitoring changes on entity objects, specific data container types can be configured to trigger events upon creation / deletion of corresponding data containers. Any data container types omitted from the triggering definition will not trigger events.

Click Add Data Container Type, then browse or search for the relevant data container type. When a data container of this type is created / deleted, it will trigger an event for the endpoint.

Miscellaneous Triggers Section

Miscellaneous triggers complement the triggers set in the other sections. By default, the following miscellaneous triggers are set to additionally filter the data being monitored by the OIEP:

Names enabled: Triggers an event when a change is made to the object name of triggering object types for a global revisable object, or when a workspace revisable object is approved. An output template must be configured with a Modify event or the endpoint will skip the event since it cannot find a corresponding template.
Parent links enabled: Triggers an event when changes are made to the parentage of triggering object types for a global revisable object, or when a workspace revisable object is approved. For example, when a product or asset is moved into another parent folder. An output template must be configured with a Modify event or the endpoint will skip the event since it cannot find a corresponding template.
Attribute-links enabled: Triggers an event when attribute hierarchy link is changed on an object of the types for a global revisable object, or when a workspace revisable object is approved. For example, when an attribute is linked to a product or classification.
Index-word hierarchy enabled: Triggers an event when an index word changes, or an index hierarchy link is added on a triggering object type. Common setup is to use indexes, and this option for print output.

Triggering Workspace Section

This section is displayed in rare cases, specifically, only if either the 'Main' or the 'Main and Approved' option was previously selected in a release where this option was available. Changing the selection to the default 'Approved' radio button removes the section from the OIEP without the ability to reconfigure triggering events from either the 'Main' or the 'Main and Approved' since triggering events from Main is not advised when using OIEPs.

By default, events are triggered on the Approved workspace. Derived event functionality is available for triggering events prior to approval, as defined in the Derived Events topic in the System Setup documentation.

Important: Triggering from the 'Main' or 'Main and Approved' workspace can negatively impact performance and is not generally recommended for OIEPs. An alternate approach to triggering events from the main workspace is to use Derived Events to trigger objects after a group of changes are made by a user or integration / import.

For OIEPs created prior to release 11.0, once the 'Approved' radio button is selected, the section is no longer available since 'Approved' is the recommended setting.

The recommended option 'Approved' creates events when an action causes an update to the Approved workspace, generally as a result of approving an object.
The 'Main' option creates an event when a change is made in the Main (maintenance) workspace, prior to approval, and can have a negative performance impact.
The 'Main and Approved' option results in events both before and after approval and can have a negative performance impact.

Note: To activate a change to the Triggering Workspace parameter, you must invoke the event processor with at least one event on the queue.