Mark single run job executed
Event action – Abstract
Purpose: Sets a flag for the running transaction to prevent the same 'job' from running multiple times.
The Mark single run job executed event action sets a flag that can be evaluated in the further course of the current transaction with the help of the corresponding rule of the Single run job executed? type.
Each flag is identified by the combination of values for the Job name and Job owner parameters, each of which can be optionally filled via Resolvers in the configuration for the event action.
The Single run job executed? rule uses the same parameters to check whether the respective flag is considered to be set within the current transaction. The 'Configuration' section below describes important details about matching the parameters.
A flag can only be set by executing the event action Mark single run job executed. It then remains until the end of the transaction.
Repeated execution of the Mark single run job executed event action with matching values for the parameters has no effect at all.
The 'delete' or 'reset' of an already set flag in the course of the transaction is not included.
As the name of the event action suggests, the use of such flags is usually intended to prevent the repeated execution of a particular 'job'. This can be used to avoid redundancies or to optimize performance, but it can also be necessary to eliminate infinite loops in event processing when there are mutual dependencies between events and event handlings. Setting a flag can be useful, but also useful because of the signaling effect within the transaction.
►IMPORTANT◄ If a chain of events is processed (see also Dispatch action event), then a flag set by a Mark single run job executed event action applies to all event handlings along the chain. Unlike variables (see Variable), which pass values within an event chain only 'forward' – from the calling to the called event handler – flags can therefore be used to provide feedback for calling event handlers. These can use the Single run job executed? rule to check whether certain flags were set during the processing of a possibly multi-level event chain when the processing is continued in the calling level.
Configuration
The optional Job name parameter is determined by Resolvers whose return value is interpreted as a string unless it is 'No value' (null).
The optional Job owner parameter is determined by Resolvers whose return value is interpreted as a data object.
The Single run job executed? rule uses the same parameters and compares the Job name as a string and the Job owner as a data object to determine whether or not a certain flag has been set in the previous course of the transaction.
►NOTE◄
Since both parameters are optional, the event action can also be executed without parameter values (or with null/null values). The Single run job executed? rule is passed with 'matching parameters' (null/null) even if the following conditions are met.
The decisive factor for the Job name match is an exact match of the return value of the value resolver converted into a string. For example, an integer (e.g. a Long value from an id field of an entity) can be compared with a string of digits provided as text. If 'comma numbers', dates/time, etc. are to be compared with, for example texts provided as 'literal', the formatting must be chosen exactly to match the output format of the respective value within a Show alert (Popup) event action.
How data objects in the Job owner parameter are compared depends on the object type in question:
If an entity or an attribute of an entity with a system-managed ID (id) is specified as a Job owner, then the matching refers exclusively to the ID (id) of the object, so that it is 'recognized' by a Single run job executed? rule even if changes have been made to the entity's data since the flag was set.
If a freely defined data object (e.g. a 'Client object') is assigned as a Job owner, then the matching process evaluates all the data contained in the object (its hash value), which must match between an assignment when the flag is set and the object supplied in the Single run job executed? rule. Whether it is actually the same object instance (see also Create instance) is irrelevant, as long as all characteristics match.
Examples
Typical examples of use
Requirements:
When saving a purchase order (business object), an event handler checks whether the reference attribute 'Order number' has been filled in for the first time. If so, the tracking state 'Commissioned' is to be set for the order.
Another event handler is triggered by setting the tracking status 'Commissioned'. It automatically assigns the reference attribute 'Order number' with a value from a number range (see Number range), if an 'Order' does not yet have a concrete specification.
The 'commissioning' of an order should therefore be able to be triggered – interactively or via integration – in two different ways: Either by entering an order number in the order or by setting the tracking state 'Commissioned'.
When assigning the 'Commissioned' tracking state to a business object without the 'Order number' or further arrangements, the tracking status would be added twice, because when the 'Order number' is automatically filled by the second event handler, the first event handler is triggered, which then detects that the 'Order number' has been filled and therefore assigns the 'Commissioned' tracking state again. Even if no infinite loop is created here, because the second event handler is only active as long as the 'Order number' is still missing, the double assignment of the tracking state should be prevented.
Configuration:
As shown schematically above, the Mark single run job executed event action is used in conjunction with the Single run job executed? rule in the two event handlings involved.
In this specific case, the Job name 'TS_ORDER' is assigned as static text and the unique ID of the purchase order is assigned as the Job owner, as executed in the following configuration for the Mark single run job executed event action:
►NOTE◄ The Single run job executed? rule must use the same parameter values.
Alternative usage (return value from an event chain)
An event handler that reacts to an Custom action event shall validate the company and address attribute of a business object passed as 'input value' and 'inform' the calling event handler if a rule violation occurs. It should be possible to differentiate between 'warnings' and 'errors'. Details about the concrete logic of the validation are not relevant for the example.
The decisive factor is that the check is to be triggered for all existing company and address attributes at certain working state changes in order to be able to consider the check results for certain company types (see Company type) in specific rules and case distinctions in the further course of the calling event handling. For this purpose, flags should be set with the help of the event action Mark single run job executed, whose Job name specifies the severity of a violation, while as a parameter Job owner specifies the Company type of the company and address attribute.
Configuration:
►NOTE◄ The calling of Mark single run job executed for the declaration of an 'error' or a 'warning' could be done within a more complex event handler in different places, and in such a way that for the same Company type both a 'warning' and an 'error' are reported. The configuration on the right eliminates this against the background of a special test logic, which should not play a role here. |
|
A calling event handling for this check might look something like this:
|
In the example, the calling event handler per Check type refers to the business object type 'Purchase order' (not shown in the image). The following event actions are executed as Actions on passed rule:
|
|
