Dispatch action event
Rule types – Abstract
Purpose: Triggers a Custom action event with a defined data object as data context, which is processed completely before the surrounding event handling continues.
Trigger Event (action)
The Dispatch action event triggers a Custom action event and passes either the current reference object or an alternating reference object determined as the return value of a value solver as the 'input value'.
The impact of triggering an event depends on whether Event handling exist that consider triggering it. Often the 'Validating rule' of an event handler define specific requirements, e.g. a Check type, so that it only becomes active if a suitable 'input value' is passed.
Via the options (see 'Configuration' below for details), it is possible to control when the custom action event should be triggered at runtime (immediately or after the commit) and how event handlings are then executed (synchronous/serial or asynchronous/parallel).
In the data context of the triggered event, all variables present in the calling context are available in addition to the reference object defined when the event was triggered. However, these are not passed directly but 'cloned' beforehand. Therefore, the values of variables that are changed or created when processing the triggered event are not available afterwards in the context of the calling event handler. Therefore, they cannot be used to provide 'feedback' for the calling event handler. Where this is required, the 'feedback' must be via the reference object provided by the calling event handler. If necessary, an entity generated by Create instance ('Client object') or Create list can also be used as a reference object, to which suitable 'return values' can be assigned.
Configuration
|
The Event parameter supports the static selection for exactly one Custom action event based on the associated dynamic enumeration via a Combobox with a search function (see screenshot on the right). ►NOTE◄ The selection options are limited via Dynamic enum filters if these are applicable in the context of the configuration. An existing selection does not have to be included in the selection list. It can be kept, changed or removed, but is not selectable again after removal. |
|
|
The Entity parameter determines the 'input value' that will be passed to the event identified by Event:
|
|
The Dispatch action event event action provides two options that control when and how a Custom action event is triggered:
The option Dispatch after commit with a new Transaction can be set if the event should not be executed within the current transaction and immediately, but only (and only) when it is successfully completed ('Commit').
When a Dispatch after commit with a new Transaction event is triggered, the exact sequence depends on the Dispatch async option:
If the Dispatch async option is not checked (default), the event will be triggered after the commit, but it will still be executed synchronously. Then the triggered event handlers are assigned to the same thread on the server CPU that handles the dispatched event handler. The dispatched event handling is considered effectively finished only when the handling of all events synchronously triggered after the commit is completed. If this concerns several events, they are processed by the thread 'serially', i.e. strictly one after the other according to the order in which they were dispatched.
If the option Dispatch async is checked, then the respective event handling can be executed asynchronously and assigned to the next available thread from the thread pool of the server CPU. If the event can be assigned to another thread, the dispatching event handler immediately addresses the next event, if any, in the 'queue' for triggering after the commit. This is then immediately started in parallel with the asynchronously dispatched predecessor and processed either synchronously or asynchronously again.
►NOTE◄ The Dispatch async option affects the event processing flow in a similar way as the 'Synchronous' option affects the profile call during Export (only with a different polarity of the off/on selection).
Since the Dispatch async option is only selectable in conjunction with the Dispatch after commit with a new Transaction option, three use cases can be configured:
|
When to trigger? ► How to trigger? ▼ |
Trigger immediately |
Trigger after commit with a new transaction |
|
Trigger |
The event is dispatched immediately and synchronously and 'handled' before any subsequent event actions. |
The event is dispatched after the commit and synchronization. Event handlers use the same thread as the triggering event handler. Multiple synchronously dispatched events are processed serially. |
|
Trigger |
(Dispatch async is not applicable 'before the commit') |
The event is dispatched after the commit and asynchronization. It is assigned to the next available thread. Any subsequent events can therefore be processed in parallel.
|
►NOTE◄ With the Dispatch async option, all variables are passed on as a copy in order to prevent parallel accesses to any objects contained therein.
Example
Simple example
In the course of an interactive action for an existing shipment (e.g. assigning the working state 'permissions'), the responsible user should be informed in a compact form about the 'participants' specified in company and address attributes for the shipment in question. Here, the Company type should appear as the title and a concatenation of selected address attributes in a standalone notification for each relevant attribute.
Example:
Configuration:
So that the display of address attributes in the desired format can also be used in other contexts, a Custom action event with the name 'Info: Address' is defined. This event can be triggered whenever a user is to be notified about the content of a certain 'Company and address attribute'.
For our example, we will create an event handler that is triggered when a shipment is assigned the 'Permissions' working state.
|
The Actions on passed rule are configured as shown on the right:
|
|
For the output of the notification in response to the 'Info: Address' event, the following event handling is configured:
|
|
►NOTE◄ The Event recorder makes it possible to trace which Input value was used to call a Custom action event and when:
Similarly to the example shown at the beginning, three address attributes were found in a shipment and passed on to the custom action event 'Info: Address' for the purpose of 'Notification'.
The Input value tab in the detail area shows the entity of the last call with the Company type 'Loading party' (DPA).