List item
See also: Modify list, Create list
Value resolver – Abstract
Purpose: This enables write or read access to exactly one existing or newly created entry in a ‘list’ available as input value.
The List item resolver enables write or read access to exactly one existing or newly created entry of a ‘list’ available as an input value.
A specific data object that can be treated as a ‘list’ must be provided as the input value or reference object.
Accessing a list entry using a List item resolver does not imply the creation of the parent list under any conditions.
Four options are available for the Mode parameter, which can be grouped in pairs:
The Get first and Get last modes are primarily aimed at providing an existing list entry for a read or write access as a return value.
The Add first and Add last modes are used to add an entry to the list that is provided as a return value for a read or write access.
The Offset parameter defines the index position of the requested or inserted list entry relative to the reference point (First/Last of the list) for the selected Mode.
Typically, the Offset parameter is defined statically by direct entry of an integer in the configuration.
An Offset value of 0 always refers directly to the reference point.
Integer Offset values <0 refer to positions before the reference point.
Integer Offset values >0 refer to positions after the reference point.
In order to be able to assign the value for the Offset parameter dynamically – i.e. variable at runtime – the corresponding integer value must be provided via a Variable whose name is entered in the configuration as a text value instead.
►NOTE◄ If the configuration for the Offset refers to a variable that is not assigned at runtime or whose value cannot be converted into an integer, an Offset of 0 is assumed.
►Important◄ Which data types can be added to a list?
A ‘list’ that was created, for example, using a Create instance value resolver with the ‘list’ (java.util.List) type or using a Create list value resolver without entries can be assigned entries of any different data types.
In these cases, the parent data type ‘Object’ (Object) is used as the data type for list entries, which allows assignments of any kind.
On the other hand, a ‘list’ can be linked to a specific data type, e.g. in the following situations:
If the Create list event action is used to initialise a list with entries of the same type, then this type is linked to the ‘list’ and then also appears in the type reference for the return value of the value resolver (e.g. Long[]).
If a Create list event action is used to initialise a list with entries of different types, the ‘list’ is linked to a parent type that covers all the data types it contains (e.g. ‘Interface > User’ for Users and Guest users).
In this case, assignments of instances of the specific data types covered (e.g.: Users or Guest users) are always possible.
Creating an instance of the parent data type using one of the Add modes of the List item value resolver, on the other hand, is only supported in the client context if necessary and makes limited sense.
If a Search event action writes the ‘result list’ of a search for instances of a specific entity type (see Guest users) to a variable, the variable contains a list that defines the ‘Guest user’ type for list entries.
If the List item value resolver is to be used to add an entry to a ‘list’ that expects a specific data type for list entries, the following scenarios must be distinguished:
The entry to be added corresponds to the expected data type for list entries.
It is then added.The entry does not correspond to the expected data type, but an automatic type conversion to an expected data type is supported.
The entry is then converted and added (see case 3) as far as possible.
►IMPORTANT◄ Specific rules can apply for each execution context (server/client) for automatic type conversion.
In the server context, for example, the text value ‘2.5e3’ can be converted to the Long value 2500 and added to a Long[]list; in the client context, the type conversion fails (see case 3).
►NOTE◄ In this context, calling up an entity based on a long value that is interpreted as a reference to its ‘ID’ (id) in other contexts (e.g. Input object (type safe) or Variable) is not supported as a type conversion. However, the Long value is automatically extracted from the ‘ID’ (id) field when an attempt is made to add an entity as an entry to a Long[]list.The entry corresponds to a different data type for which no automatic type conversion to the expected data type is provided or a type conversion would be provided (see case 2), but fails for the specific value of the entry.
Then the entry is not added. No error message is triggered.
►NOTE◄ The same results cannot necessarily be achieved with the List item value resolver when adding list items as with the Modify list event action (see Modify list / Add).
Configuration
Mode |
Parameter |
Effect |
Get first (default) |
Offset |
Returns the item of a given list from a position specified by an Offset relative to the first item.
If the offset refers to a position before the first or after the last item on the list, one or more empty elements are added to the list to ensure the addressed position becomes valid, if the resolver is used on the left side of an assignment, e.g. by Set value. |
Get last |
Offset |
Returns the item of a given list from a position specified by an Offset relative to the last item.
If the offset refers to a position before the first or after the last item on the list, one or more empty elements are added to the list to ensure the addressed position becomes valid, if the resolver is used on the left side of an assignment, e.g. by Set value. |
Add first |
Offset |
Adds an item to a given list at a position specified by an Offset relative to the first item.
If the offset refers to a position before the first or after the last item on the list, one or more empty elements are added to the list to ensure the addressed position becomes valid, even if there is no assignment to the new value. |
Add last |
Offset |
Adds an item to a given list at a position specified by an Offset relative to the last item.
If the offset refers to a position before the first or after the last item on the list, one or more empty elements are added to the list to ensure the addressed position becomes valid, even if there is no assignment to the new value. |
Examples
Read access to the first entry in a sorted list
For a given company account (see Company accounts), a rule should apply if the Company of session is not only contained in the ‘Parent companies’ (parentCompanies) list field, but is also the company with the lowest ‘ID’ (id) of all the companies listed there.
Configuration:
In a context in which the company account to be checked is a reference object (possibly a With rule), a Junction is displayed as shown in the screenshot on the right:
|
|
Read access to a random entry in a list
A ‘candidate’ is randomly selected from a given preselection for Users, which is given as a list via the Variable candidates, for which a Custom action event (SEND_EMAIL) is triggered.
Configuration:
All necessary steps are configured in the action block of an Execute with event action, which defines the candidates list variable with the list of eligible Users as a temporary reference object via the Object resolver parameter:
|
|
Write access: Create an additional list entry
When copying a company account, it should be ensured automatically that the company specified as the ‘owner’ (ownerId) of the original is also contained in the ‘parent companies’ (parentCompanies) list.
Configuration:
The screenshot on the right shows the configuration for event handling that reacts to ‘Copy’ (see Common action event) as the Triggering event. A Check type is executed as a Validating rule to ensure that a ‘Company account’ is copied. As the only Action on passed rule, a Set value event action is used:
|
|
►NOTE◄ The data type for the list field 'Parent companies' (parentCompanies) is 'Set' (Set), which has two important effects on adding in the example:
If the Long value being added is already contained in the list, it is added (without an error message). Therefore, nothing needs to be done to prevent duplicates.
Mode and Offset settings only have a limited influence on the position of an added entry, as the ‘Set’ (Set) class handles the order of the entries independently.
►NOTE◄ Strictly speaking, it should also be ensured that the Action on passed rule is only executed if the ‘owner’ (ownerId) field in the original company account contains the value >0. If no owner is selected there at the time of copying, the ownerId value is -1. This value should not be added to the list of ‘Parent companies’ (parentCompanies).
Write access: Replace existing list entry
From a given comma-separated list of parameters (in the example Text: YEAR=2024,WEEK=42,AREA=7), the second parameter is to be replaced by a new string (in the example: MONTH=10).
Then, the string for the parameter list should be written into a params variable, URL-encoded (using '&' as the delimiter instead of a comma).
Configuration:
In the context of an Execute with event action, the Object resolver parameter is used to provide the input list of parameters:
Result: (Text value of params Variable) YEAR=2024&MONTH=10&AREA=7 ►NOTE◄ Of course, the same result could also be achieved in other ways (e.g. Replace text), but the method presented here solves the task very clearly and reliably. |
|
Read access for writing: Change existing list item
Following on from the previous example, the same ‘parameter list’ is now no longer given as a string but as a list of objects with the name and value fields.
In the context of event handling, the value property for the penultimate list entry (parameter ‘WEEK’) should be assigned the value 48.
►NOTE◄ In the following example, the List item resolver is primarily used to read the entry. However, this access indirectly enables write access to a field of the contained object.
Configuration:
In the context of an Execute with event action, the Object resolver parameter is used to provide the input list of parameters:
|
|
Result: [{"name":"YEAR","value":"2024"}, |
{ |
Write access: ‘Insert’ additional list entry
Based on the previous example, an additional ‘parameter’ with the name (name) 'COUNTRY' and the value (value) ‘NL’ should be inserted in the penultimate position.
Configuration:
In the configuration shown on the right, only the action block has been changed from the previous example:
►IMPORTANT◄ This configuration only works in this form in the client context, where the 'add' Mode supports the creation of a new object for the additional parameter without any further precautions. In the server context, on the other hand, it must be explicitly ensured that the object to be added is created as a ‘client object’, otherwise the value assignments via Set values will come to nothing. In general, this could be achieved via a Create instance with values resolver, whose return value is assigned as a list entry to be added. |
|
The alternative shown in the screenshot on the right shows how the above configuration can be made executable for the server context:
With this variant, the result is the same for server context and client context: { In contrast, in the server context with the original configuration, only an empty object entry without field values would be inserted at the penultimate position: { "class": "java.lang.Object" } |
|
Write access: Add list entry with type conversion
A list is defined as a list of Long values when it is created. Subsequently, a value is to be inserted that is provided as a text value (String) via a User prompt.
Configuration:
In the Object resolver of an Execute with event action, a list of static Long is generated with the Create list value resolver. In the action block, a 'missing' value is added in the second position, which is queried by the user via the User prompt.
As the list provides the Long type for entries, the added input must also correspond to this type. If the character string entered can be converted into an integer, a Long value is inserted. Otherwise, no input is added. |
|
►IMPORTANT◄ Specific rules or restrictions for the execution context (server/client) may be relevant for the type conversion:
|