Tracking-state-referenced-object

Value resolver – Abstract

Purpose: Returns the entity to which a tracking state entry present as input value refers to the tracking state owner.

images/download/attachments/177910665/image-2024-9-11_11-27-35-version-1-modificationdate-1726046854660-api-v2.png

The Tracking-state-referenced-object value resolver returns the entity to which a tracking-state entry present as an input value refers as the tracking state owner.

  • If the input value is not a tracking state entry, 'No value' ($null) is returned.

For the Type of referenced object parameter, a class must be selected that matches or is at least compatible with the type of the tracking state owner.

  • With no or with an inappropriate selection, 'No value' ($null) is returned.

NOTE◄ This value resolver is not supported on the client side (e.g. in a Client workflow), since the 'referenced object' must be retrieved from the server.

Configuration

The input value is expected to be an entity of the 'Tracking state entry' type (TrackingStatusEntry).

The Type of referenced object must be selected 'appropriately' for the Tracking state owner, since the selection options for further configuration (e.g. access to attributes, etc.) may depend on this selection, among other things.

Often, in the value resolver's operational environment, it is clear which type the tracking state owner is. Then the selection declares this type for subsequent configurations, for example, in the context of an Execute with event action.

If the value resolver is used in a context where the tracking state owner type can be variable, a suitable overarching class (e.g. 'entity' or 'business transaction object') must be selected as the Type of referenced object.

NOTE◄ The selection of an overarching class as the Type of referenced object may impose restrictions on the configuration in terms of specific content for the contained classes. However, at runtime the tracking state owner is always returned in full. Its specific type can be determined via Check type or by evaluating the variable entityClass.

Example

Simple use case

Changing an existing tracking state entry (e.g. to enter a comment or upload a signature) should be prevented for Orders if it is not the current tracking state entry (for the default Tracking state type 'Current' (CURRENT)) of the related object.

Configuration:

The event handling shown on the right is aimed at preventing the saving of changes for existing tracking state entries by means of an Abort action, provided that these affect Orders:

  • The only Triggering event selected is 'Update' from the Common (Events) category.

  • The Validating rule includes three AND-linked criteria that are deliberately arranged precisely in the following sequence with performance in mind:

    • The initial check type determines whether the 'Update' event has been triggered for a tracking state entry. Only then will further checks take place.

    • The first Entity property rule ensures that the tracking state entry in the input value per the statusOwner property refers to the 'Order' class. Only in this case is the referenced object for the last check criterion requested from the server.

    • The second Entity property rule requests the order referenced in the tracking state entry from the server via the Tracking-state-referenced-object value resolver to verify that its tracking state attribute for the tracking state type 'Current' (CURRENT) refers to the ID (id) of the changed tracking state entry via the trackingStatusEntryId properties. If this is not the case, the Validating rule as a whole is considered 'passed'.

  • The only Action on passed rule is an Abort action, which aborts the transaction to change the tracking state entry and informs the user about it with a message of the 'Semantic Exception' type.

images/download/attachments/177910665/image2022-7-18_9-52-22-version-1-modificationdate-1726046760665-api-v2.png

More complex use case

A user should receive notifications of 'current" tracking state changes in their area of responsibility at the push of a button.

  • Tracking state entries that have been created (i.e. successfully added to an entity) since the beginning of the current day should be considered 'current'.

  • The separation for the 'scope of responsibility' should be provided by read access for the tracking state entries in the context of the current session.

Runtime example:

After clicking on a ribbon button, a notification of the 'Info' type should be displayed on the right side of the screen for each 'current' tracking state change, containing the following information:

In the title:

  • Time of tracking state change
    (Date is 'Today' by definition)

  • Added tracking state code

  • Entity type (tracking state owner)

In the message:

  • More information about the 'referenced object'
    (here: ID ~ Owner ID/Current working state)

images/download/attachments/177910665/image2022-7-18_8-47-22-version-1-modificationdate-1726046760685-api-v2.png

Configuration:

The following event handling is triggered by a Custom action event 'What's new?' (WHATS_NEW), which users can trigger via ribbon buttons in selected views.

The tracking state entries relevant for display are provided by a Search action. This returns a chronologically sorted list of all tracking state entries readable in the context of the session that have been created since the beginning of today's tag (see Relative date with time) in a variable whatsNew.

The following For each loop action iterates over the tracking state entries in the whatsNew variable:

For each entry a Show alert (Popup) event action is executed in which the desired information is prepared:

  • The information for the Title can all be obtained directly from the tracking state entry, which is the reference object within the loop. This processing is done here by a Concat strings value resolver, the configuration of which will not be discussed in detail.

  • Of the data specified for the Message, only the tracking state owner ID is available in the tracking state entry (statusOwnerId property). For all other data, access to the 'referenced object' (aka tracking state owner) is necessary. The Tracking-state-referenced-object value resolver returns the entity in question starting from the reference object (tracking state entry). The Type of referenced object here must be the overarching 'Entity' class, so that all types of tracking state owners can be covered.

  • The concatenated Template value resolver defines the formatting of selected content from the data object of the entity determined to be the 'referenced object' for the tracking state entry.

NOTE◄ The id and onwerId properties are 'entity attributes' that each entity type uses. A working state, on the other hand, is not supported by every entity type that can 'own' a tracking state. A position of a business transaction object, according to its class, is considered as an 'Entity' but not as a 'Business transaction object'. It has no working state, but tracking states can be added to it. If specific detail data should appear for different entity types, case distinctions are required.

images/download/attachments/177910665/image2022-7-18_8-44-31-version-1-modificationdate-1726046760687-api-v2.png