Set value

Purpose: Sets a value in an object field or variable.
Tooltip
Usage: The value returned by the right value resolver is assigned to the target (object field or variable) defined by the left value resolver.
Parameter: Value resolver (left/target), value resolver (right/source).
Output: Value change for a field of the reference object or variable.

The Set value event action sets a value in an object field or variable.

images/download/attachments/62864945/image2021-3-19_19-37-12-version-1-modificationdate-1616179034920-api-v2.png

On both sides of the 'Value assignment', one resolver each can be configured for the destination and the source.

The arrow direction of the symbol between the two values illustrates the relationship between the source (right) and the destination (left).

►IMPORTANT◄

A value assignment only takes place if the configured target can process it at all, and if the data type between source and target matches or is convertible. If, for example, a static value (see Static values) or 'no value' is defined as the target, the event action has no effect with respect to the target. In the context of Tests, an error message may be read in the 'Log' (e.g. an UnsupportedOperationException), however, in the case of the Set value event action, such inconsistencies do not usually lead to any event handling cancellation (with rollback). If a value assignment fails, the target simply keeps its value unchanged.
If a Variable value resolver in a Set value event action defines the source, the 'Type' parameter (in the Variable value resolver) can be used to read the data 'type safe' from the variable. In addition to simple conversions for simple values (e.g. between the types String and Long), specific mechanisms (see Input object (type safe)) for 'resolving' complex objects based on simple values (dynamic enumeration value via name as String value, entity of a concrete type via id as Long value) are also effective.
If a Variable value resolver in a Set value event action defines the target, the 'Type' parameter (in the Variable value resolver) can be used to write the data read from the source to the target in a 'type-safe' manner. Only simple conversions for simple values (e.g. between the types String and Long) are effective, but not the specific mechanisms mentioned under (2).
When writing or reading variables, note that they always represent a reference to an object unless they are assigned a simple value (e.g. a string or a numeric value). Set value transfers if source and target are two different variables, i.e. only the reference, provided that the value of the source is an object and not a simple value.

The following examples are intended to illustrate the practical significance of these important aspects.

Example

As an example, the use of a series of Set value event actions is explained here, which should result in an event handling with the following objective:

Task formulation:

images/download/attachments/62864945/image2021-3-19_19-38-17-version-1-modificationdate-1616179100101-api-v2.png

There are two companies (with the IDs 2101 and 4101), that have been assigned so far to the Company types shown above (see Company type).
The Company types of 'Vortex Inc.' (2101) are to be transferred to the company 'fast-or-furious Ltd.' by event handling, which was previously classified only as a 'Freight forwarder', in addition to the current company type ('Freight forwarder').

Configuration:

►NOTE◄ The following configuration is not intended to be a best practice solution for the task. Rather, it serves to illustrate important considerations when using Set value.

Assigning a simple value to a variable (with simple conversion)
The source of the first assignment is a value resolver that defines the unique internal ID (`2101`) of the company 'Vortex Inc.' as a simple, static string of the `String` type (see Static values). The target of the assignment is a value resolver for a Variable in which the Key `sourceId` is defined, specifying the Class `Long`. The value of the variable `sourceId` is `2101` (`Long`) after this assignment, but only because an automatic conversion from `String` to `Long` is provided and because the string '`2101`' can be directly converted to an integer number. Even adding a space character ('`2101` ') would prevent this conversion. Then the variable `sourceId` would not be set at all. It would then also not appear in Tests or – if it was already set elsewhere within the transaction – show the previous value.
►NOTE◄ To assign the `Long` value statically, the specific value resolver 'Long' would actually be appropriate here, which the system will suggest automatically in the course of configuration if the target specifies this Class. However, instead of the static text, after initial tests, another value resolver could be used later, which by definition basically provides text (e.g. User prompt). However, further checks are recommended to deal with any cases where a user enters text that cannot be converted to `Long`.
Assign a reference to an entity addressed by Long ID as the value of a variable
The source of this assignment is the previously set variable `sourceId`, which contains the `Long` value `2101` at runtime. The selected Class 'Company account' takes effect on read access, so the subject of the assignment is the complete company account 'Vortex Inc.' identified by ID `2101`. The target of the assignment is a new variable named `sourceCompany`, which stores a reference to the company account for 'Vortex Inc.' and not just a static snapshot of the current state of the data. ►NOTE◄ In Tests, the current status of the company account with all details valid at the time of execution still appears as the value of the variable.
In the Execute with event action shown on the right, the company account of the company 'fast-or-furious Ltd.' is first set as the reference object, which is the target of the following assignments in the action block. Its internal ID (`4101`) is specified as a static long value (see Static values), which is passed on to an Input object (type safe) value resolver via concatenation. This returns the identified company account as a reference object at runtime. Functionally, the concatenation thus corresponds to the assignment shown above for the `sourceCompany`. However, specifying a static text ('`4101`') would not have worked here, because the value resolver Input object (type safe) resolves entities strictly only if a `Long` value is present as the input value. The following event actions are then performed with the company account defined as the reference object: The Save changes later event action sets a flag to save for the company account, since the subsequent adjustments to the company account should be saved after the event handling is complete. The following Set value event action transfers the list of all company types in the `types` field of 'Vortex Inc.' to the 'fast-or-furious Ltd.' company account. This first overwrites their existing classification as 'Freight forwarder'. In the last step, the 'Freight forwarder' company type is added back to the transferred list. Further details on this are described in the following sections, which show the expanded configuration of the two Set value event actions.
The source of the first assignment is the variable `sourceCompany` previously set, which contains reference to the company account of 'Vortex Inc.' at runtime. The selection here of 'Company account' as Class only causes the fields of a company account to be selectable in the concatenated Object property. Without this support, it would be necessary to know the field name `types` and define them by direct input. The object of the assignment is a reference to a list of company types ('Company type[]'), to which the entries 'Consignee' and 'Principal' belong at runtime. The target of the assignment defines an Object property value resolver, which provides access to the field 'Company types' of the reference object – the 'fast-or-furious Ltd.'. This field previously referenced a list with exactly one entry, namely the company type 'Freight forwarder'. This reference replaces the assignment with a reference to the list of 'Vortex Inc.' with the company types 'Consignee' and 'Principal'.
►IMPORTANT◄ For the understanding of Set value, it is important to understand that at this moment the two input objects for the involved company accounts per field types actually refer to the same list and not to two different ones, which contain the same elements due to the assignment.
The last assignment is now to restore the entry of the company type 'Freight forwarder' for the company account of 'fast-or-furious Ltd.', so that this is not lost when the company account is saved with the list recently referenced. The source for the entry uses a concatenation of the static string `FWD`, which corresponds to the internal name of the value from the dynamic enumeration Company type localized in the selection as 'Freight forwarder'. The concatenated Input object (type safe) value resolver therefore 'transforms' this string into the corresponding enumeration value. The target here is a List item resolver, which with the Mode 'Add last' allows an element to be added to the list defined above by value resolver. The list referred to by the 'Company types' (`types`) field in the 'fast-or-furious Ltd.' company account will therefore have 'Freight forwarder' added as a third company type.
CAUTION As explained in the previous paragraph, at this point the two input objects for the involved company accounts per `types` field refer to the same list to which the 'Freight forwarder' entry has just been added. If the company types of 'Vortex Inc.' were subsequently accessed within the current transaction, the entry 'Freight forwarder' would also appear as the company type for this company. The described procedure therefore only leads to the desired goal (see the following figure), because here only the reference object of Execute with, i.e. the company account of 'fast-or-furious Ltd.', is flagged for saving by the Save changes later event action. The unintended company type changes for 'Vortex Inc.' referenced as `sourceCompany` at the end of the transaction are fortunately 'lost' here due to the lack of any preselection.