Set value
Event action – Abstract
Purpose: Sets a value in an object field or variable.
The Set value event action sets a value in an object field or variable.
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:
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:
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