Value changed
The Value changed matcher type typically aims to check in the context of an Entity property rule whether the volatile data state of an entity present as a reference object differs from the associated Original entity with respect to a certain check value configuration.
The check value configuration here refers to the value configuration in the Entity property rule that uses the Value changed matcher type. In the screenshot (above), the check value configuration is an Object property resolver that accesses a (fictitious) 'Check value' field of an unspecific type 'Entity'.
CAUTION
In the client context (Client workflow), the Value changed resolver is effectively useless, because there the Original entity is always the volatile state of the entity in the execution context (see Original entity), so the return value is always false .
In the simplest case, the check value configuration determines a 'simple value' (e.g. a String from a text field) whose state in context may or may not match the value determined from the Original entity (hereafter referred to as the original value).
If the check value configuration refers to a 'complex value', i.e. a data object with multiple values in fields, then the return values for the reference object and the Original entity are compared according to the logic of the Equals comparison, taking into account the selection for the Deep compare option.
For the evaluation of 'complex values' (data objects with fields) the following cases have to be distinguished:
If the class of the check value provides specific comparison logic, this determines the criteria according to which the check value and original value are considered to match or change.
In the context of entities, this particularly concerns the values of attributes of different types that may be assigned to an entity at the header or line item level.
Attribute values of certain attribute types are compared directly 'by content' even without selecting the Deep compare option. All 'useful data' of the attribute value are included, except for the index field, which affects only Plural attributes.
For attribute entities, i.e. the entries in the attributes list field of the respective attribute owner (with one attribute value each in the value field), on the other hand, no specific comparison function takes effect (see next point).
If the check value class does not provide specific comparison logic (e.g. for a complete line item), the Deep compare option must be activated so that the Value changed comparison provides meaningful results.
Without a content check, two data objects, which at best are clones with identical content, would always be considered different, i.e. 'changed'.
The 'deep comparison' requested by the Deep compare option may be applied recursively to all levels of a nested data object and may be correspondingly CPU-intensive depending on its complexity. Therefore, the Deep compare object contents option should be used 'sparingly' with regard to runtime behaviour.
Configuration
The Value changed matcher type requires an entity to be the reference object in the context of the parent Entity property rule.
►IMPORTANT◄ If there is no entity as the reference object, the Entity property rule is considered 'failed' (false). The check value configuration is not then evaluated.
|
If the Value changed compare type is selected for an Entity property rule, only one value configuration is displayed, referred to here as the check value configuration. The Deep compare option in the compare type configuration is switched off (OFF) by default. |
|
|
In the example on the right, an Object property value resolver has been added via the context menu of the check value configuration, which accesses the 'owner' field (ownerId). This field is present for each entity. It identifies a company account as the 'owner' of the entity via its ID and therefore contains a Long value. The Deep compare option therefore remains switched off (OFF) for the comparison. |
|
|
The following configuration for an Entity property rule is functionally completely equivalent: |
|
|
|
|
|
The Value changed matcher type simplifies the configuration, because on the one hand the Original entity value resolver (top right) does not have to be used explicitly and on the other hand the redundant value configuration in the compare value (bottom right) is omitted. IIn this very simple example, the benefit is still clear, but if a more complex Chained resolver is required in the check value configuration, the Value changed matcher type not only saves effort but also allows for a more compact representation and avoids the risk of unintended deviations when creating and adjusting redundant value resolver chains. |
|
The Deep compare object contents option should be used only if the comparison of complex data objects requires it:
|
|
By default, the Deep compare option is switched off (OFF). Then the Value changed comparison for complex data objects is passed only if their class (e.g. an attribute value class) defines a specific comparison logic (see above). Otherwise, a complex data object (e.g. a specific position of an entity) always appears as 'changed' because accessing the Original entity always returns a clone as the original value, which – even if all contained values match – is not identical to the check value. |
|
|
If the Deep compare option is switched on, then all characteristics (such as fields, attributes, etc.) of the data objects resolved via the check value configuration are compared (recursively if necessary) to determine whether the same object is described in terms of content and form. However, the check does not take into account whether the object is technically the same. This 'deep comparison' is generally more time-consuming than the simple comparison of the identity of two objects performed by default (see above). The |
Examples
Simple use case: Sending an e-mail when a user is deactivated
Event handling for the 'Update' event (see Common action event) is used to check in the context of a user account (see Users) whether the 'Active' status is withdrawn from the user account in question when the transaction is completed. In this case, a notification is to be sent by e-mail.
Configuration:
|
'Update' is selected as the only Triggering event for the event handling shown on the right. The Validating rule consists of three conditions in a common AND Junction:
►NOTE◄ Which value for 'Active' was present in the Original entity is not explicitly checked here. For a Booelan field, only true and null can technically be considered as original values other than false. Since the default value for the 'Active' field in the user account is defined as false, null can only be the original value if the user account has not yet been saved, so that no Original entity exists. This case is excluded in our event handling, because here only the 'Update' event and not also 'Create' is provided as a Triggering event. The only Action on passed rule here is a E-Mail to notify the concerned user. |
|
More complex use case: Registering changes to e-mail communication information
When saving an existing user account (→ Common action event: 'Change'), it should be determined whether changes have been made to the communication information for the 'E-Mail' (EMAIL) Communication type.
Runtime example:
The Type, Context and Value properties represent the ‘payload’ of communication info.
Each ‘line’ in the screenshot represents an instance for this plural attribute type of the address object (see Addresses), which is non-typed although it contains a Type field.
Configuration:
The following rule configuration is aimed at detecting changes to communication info in a user's address that affect the 'E-Mail' (EMAIL) type.
|
The AND Junction shown in the screenshot on the right for the Validating rule of an event handling that reacts to the ‘Change’ event (Common action event) contains two rules:
|
|
►IMPORTANT◄ The Deep compare option must be checked (ON), otherwise the rule will always pass regardless of changes to e-mail communication information. The reason for this is that the Plural attributes (Resolver) always generates a new list of attribute values each time it is called. The Value changed matcher type implies two calls to the check value configuration. This means that two lists are compared which, without the Deep compare option, are not considered to be the same even if they list the same attributes and these do not contain any value changes. Only the more complex comparison of the object contents – here: the ‘content comparison’ of the lists – recognises the lists as ‘equivalent’, as long as none of the attributes have been changed.
However, the above check logic (with the Deep compare option) is also not yet perfect in its capacity for making changes. The weak point here is the orderIndex field, which assigns an order position to each piece of ‘Communication info’ (or each instance of the plural attribute). The Plural attributes (Resolver) resolver returns the attribute instances in the order of ascending orderIndex values, which is helpful for the comparison with the implicitly used Original entity. However, only as long as the orderIndex of the relevant instances has not changed:
If one of the entries for ‘mobile’ numbers in a list position before the e-mail entry (here: at the end of the list) is removed in the above runtime example, this should not actually be considered a change in relation to the ‘E-Mail’ address in the sense of the task.
However, the orderIndex value of the ‘E-Mail’ entry changes (from 2 to 1) as it is still at the end of the list, but now only has one predecessor.
Adding a 'Phone' entry above the ‘E-Mail’ entry would also be mistakenly interpreted as an e-mail change, unless another one was removed, so that the ‘E-Mail’ entry retains its absolute order position.
Alternative configuration:
|
The screenshot on the right shows how the value resolver chain for the check value can be extended so that the Value changed matcher type only takes into account the relevant properties of communication info for ‘E-Mail’ entries:
►NOTE◄ The method of selective ‘transcription’ of complete entries may seem radical. However, for a simple object such as communication info, it is ‘feasible’ and also quite efficient. In this specific case, since String fields are involved, a Concat strings in the Collect values resolver could also be used. However, a separator character must then be ‘reserved’ (possibly also a separator string), which by convention may not be used in both fields. Of course, there are countless other solutions for recognising differences between the original and the potentially modified list. This example is therefore also intended to familiarise users with potential 'difficulties' that may be relevant for deviating solutions. |
|
