Event action – Abstract

Purpose: Attempts to add the working state just added to a manifest as well as to the Shipments contained as manifest items.

images/download/attachments/177912357/image-2024-9-18_15-35-3-version-1-modificationdate-1726666503271-api-v2.png

The event action Propagate working state is used to add the working state just added to a business transaction object of the 'Manifest' type (see Manifests) as well as to the Shipments contained as manifest items.

►IMPORTANT◄ 'Propagation' works only within an event handling triggered by the corresponding working state event (see Working state (Events)). If the same event handling should propagate different Working state, the corresponding events must be explicitly configured as triggers. However, there is no possibility to propagate 'all' working states to the Shipments of a manifest via the event action Propagate working state.

CAUTION Within a working state event (see Working state (Events)), the working state just added is already set in the 'Current working state' (currentWorkingstate) field of the reference object. However, this entry is only saved if the transaction is completed successfully. The occurrence of an error or execution of an Abort, on the other hand, causes a rollback. If the 'propagation' of the working state fails because it cannot be added to at least one of the Shipments contained in the manifest due to contraints by any applicable Working state matrix, this means the working state change for the manifest also fails.

CAUTION As far as the event action Propagate working state has read or write access to Shipments or their working state entries in the course of propagation, this is done without any consideration of permissions or access restrictions.

Configuration

The event action can only be used meaningfully with a manifest (see Manifests) as the reference object. The propagation of the working state only works with a working state event (see Working state (Events)) as a trigger (see above).

By default, the Reason parameter provides for the direct entry (on the left of the screenshot) of a static text that will appear in the course of propagation to the reason field in the working state object when it is assigned to a shipment.

Alternatively, a value resolver can be defined by clicking on the gray arrow at the bottom left to dynamically assign a text value for the same field. The example on the right in the screenshot (above) shows how an Object property value resolver can be used to propagate the 'reason' from the manifest's 'Current working state' (currentWorkingstate.reason field) for all Shipments. The 'reason' is not automatically propagated if no text is specified or no value resolver is configured!

►NOTE◄ In addition to the Reason (reason), the working state object also contains the 'realization time' (realization) field, which should indicate the time when the working state became effective. In the course of propagation, the current system time is automatically assigned to this – similar to the interactive addition of a working state via the ribbon. The optional assignment of a time is not considered here.

Example

For selected working state changes for Manifests ('Released', 'Delivery', 'Canceled'), the added working state should be propagated to all contained Shipments, if there is at least one shipment among them whose current working state differs from the added one.

As an indication of the 'originator' of the status change, the name of the role from the context of the session should be entered in the Reason field for the working states created in the course of propagation (for Shipments).

Configuration:

The desired Working state (Events) are assigned as Triggering events.

The Validating rule uses a Check type to ensure that a manifest is present as the reference object.

The Action on passed rule is configured as shown to the right:

Within an If then else event action, a complex criterion is evaluated, which is described in more detail below. It applies if the 'Current working state' of at least one of the Shipments items included in the manifest (reference object) is different from the working state that has just been added to the manifest.
In the 'Then' branch, the event action Propagate working state is executed, which is accessed per the Reason parameter to the Role of session, whose Object property 'RoleName' (roleName) is propagated as the 'Reason' for the working state of the Shipments.

images/download/attachments/177912357/image2021-7-20_15-45-46-version-1-modificationdate-1726664640112-api-v2.png

The rule in the If then else event action is configured as shown on the right:

The outer Entity property rule checks if the return value from the contained Rule list resolver is not empty.
The Rule list resolver is at the end of a concatenation of value resolvers, in which the reference object is first stored in the variable mfst, so that there is access to the manifest within the condition in the Rule list resolver. Then the Object property value resolver reads the list of all manifest items from the lineItems field.
In the Rule list resolver, a comparison is made for each shipment (Object property in the manifest position) by Entity property rule, to see if its 'Current working state' (currentWorkingState.workingState) field differs from the value of the corresponding field in the manifest (Variable mfst). Since the Resolve all as list option is not set, this search terminates at the first match ('deviator') and returns the corresponding manifest item as a value. In this case, the outer Entity property rule is fulfilled ('not empty') and the event action Propagate working state in the 'Then' branch is executed.

►NOTE◄ An 'Else' branch is not needed, since there is nothing to do if the working state of all contained items already matches the working state just added to the manifest.

However, if the propagation is executed, the respective working state (incl. 'Reason') will also be reassigned to the shipments whose workingState already previously matched the manifest.

images/download/attachments/177912357/image2021-7-20_15-46-51-version-1-modificationdate-1726664640107-api-v2.png