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.

images/download/attachments/201660713/image-2025-3-13_10-23-48-version-1-modificationdate-1741857828007-api-v2.png

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:

  1. The entry to be added corresponds to the expected data type for list entries.
    It is then added.

  2. 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.

  3. 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
(integer)

Returns the item of a given list from a position specified by an Offset relative to the first item.

  • An Offset of '0' returns the first item on the list.

  • Positive Offset values refer to the following items (if any).

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
(integer)

Returns the item of a given list from a position specified by an Offset relative to the last item.

  • An Offset of '0' returns the last item on the list.

  • Negative Offset values refer to the preceding items (if any).

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
(integer)

Adds an item to a given list at a position specified by an Offset relative to the first item.

  • With an Offset of '0', the new item is added as the first item on the list.

  • With positive Offset values, the new element appears as one of the following items.

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
(integer)

Adds an item to a given list at a position specified by an Offset relative to the last item.

  • With an Offset of '0', the new item is added as the last item on the list.

  • With negative Offset values, the new item appears as one of the preceding items.

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:

  • The Check type ensures that a ‘company account’ (CompanyAccount) exists as a reference object.

  • The AND-linked Entity property rule uses Equals as a check value (left) to compare the lowest ‘ID’ (id) from the ’Parent companies’ (parentCompanies) field of the company account with the compare value (right), namely the ‘ID’ (id) of the Company of session:

  • The decisive check value for the comparison is determined in several stages using a value resolver chain:

    • The Object property value resolver returns the Long[]list with all ‘ID’ (id) values for ‘parent companies’ (parentCompanies).

    • The Sort list value resolver sorts these values in ascending order.

    • The List item resolver then accesses the first value of the sorted list in order to obtain the minimum value for the ‘ID’ (id) within the list. The Mode ‘Get first’ in conjunction with the offset of 0 ensures that the first list entry is read.

images/download/attachments/201660713/image-2025-3-13_10-55-4-version-1-modificationdate-1741859704163-api-v2.png

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:

  • A Set value event action uses the Calculate value resolver to determine a random value from the value range for the index of the given list, which is saved in the Variable randomIndex:

    • For the calculation, two input values are mapped to variables for the calculation: A Random long value (Variable name random) and the length (length) of the list (Variable name entries).

    • The calculation first determines the absolute value of the random number, as only positive values are desired, and then uses the modulo operator (%) to obtain the residual value of an integer division by the number of options (entries). This value is always between 0 and length-1, which corresponds exactly to the value range for the index in the user list.

  • In the Dispatch action event event action, the List item value resolver is used, which uses the Mode ‘Get first’ and refers to the name of the variable (randomIndex) filled by the Set value resolver in the Offset.

    NOTE◄ The Offset cannot be calculated directly because the parameter does not provide a value configuration but only a static value that is interpreted either directly as an index value (number) or as a variable name (text).

images/download/attachments/201660713/image-2025-3-13_10-57-13-version-1-modificationdate-1741859833286-api-v2.png

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:

  • The target for the assignment (left) is determined via a concatenation of two value resolvers:

    • The Object property value resolver accesses the ‘Parent companies’ (parentCompanies) list field.

    • The concatenated List item value resolver uses the Mode ‘Add first’ and the Offset of 0 to define that the value provided as an assignment is added as a new entry.

  • The assigned value (right) is read via an Object property value resolver from the ‘owner’ (ownerId) field of the original company account provided via the source variable during the copy event.

images/download/attachments/201660713/image-2025-3-13_10-58-19-version-1-modificationdate-1741859899055-api-v2.png

NOTE◄ The data type for the list field 'Parent companies' (parentCompanies) is 'Set' (Set), which has two important effects on adding in the example:

  1. 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.

  2. 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:

  • The sample data is provided here as static Text (Statische Werte and split using the concatenated Split text resolver with the ‘comma’ (,) as a Delimiter. The result is a list of text values (String[]).

  • A Set value event action is used in the action block, which defines the second parameter (with index 1) as the target for the assignment for the static ‘replacement text’ defined on the right via the List item resolver with the Mode ‘Get first’ and Offset 1.

  • In the following Set value event action, a coherent string is formed again from the revised list of text values with the Join string list value resolver (right), which is assigned to the params Variable.


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.

images/download/attachments/201660713/image-2025-3-13_10-59-39-version-1-modificationdate-1741859979318-api-v2.png

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:

  • The data structure is provided in JSON format as static Text, from which a list of name/value tuples is generated using the concatenated object from JSON to object resolver.

  • A Set value event action is used in the action block to assign a new value to the penultimate parameter entry in this list:

    • The List item resolver refers to the penultimate list entry using the ‘Get last’ Mode and -1.

    • The concatenated Object property value resolver addresses its value field as the target for assigning the statically defined text value on the right (48).

images/download/attachments/201660713/image-2025-3-13_11-1-43-version-1-modificationdate-1741860102856-api-v2.png

Result:
starting from the following input value:

[{"name":"YEAR","value":"2024"},
{"name":"WEEK","value":"42"},
{"name":"AREA","value":"7"}
]


{
"class": "list",
"data": [
{
"name": "YEAR",
"value": "2024"
},
{
"name": "WEEK",
"value": "48"
},
{
"name": "AREA",
"value": "7"
}
]
}

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:

  • Instead of the Set value event action, a Set values event action is used in the given use case, as two fields of the completely newly added parameter must be set for the task at hand.

  • The List item resolver was transferred to the value configuration for the Target host with unchanged parameterisation (for Mode and Offset), as it again concerns the penultimate list position.

  • The two target hosts are each addressed via an instance of the Object property value resolver and are assigned static Text.


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.

images/download/attachments/201660713/image-2025-3-13_11-3-31-version-1-modificationdate-1741860211290-api-v2.png

The alternative shown in the screenshot on the right shows how the above configuration can be made executable for the server context:

  • When providing the list in the Object resolver, after parsing the list from the JSON text, an Input object (type safe) value resolver is concatenated, which declares the type of the list as an Is collection of (selected) ‘Client object’.

  • Based on this declaration, the List item resolver now also ‘knows’ the object type (here: ‘Client object’) in the server context that it should use if an 'add' Mode is selected and the new list value is not assigned ‘ready-made’ as an object.

With this variant, the result is the same for server context and client context:

{
"class": "list",
"data": [
{
"name": "YEAR",
"value": "2024"
},
{
"name": "WEEK",
"value": "42"
},
{
"name": "COUNTRY",
"value": "NL"
},
{
"name": "AREA",
"value": "7"
}
]
}

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" }

images/download/attachments/201660713/image-2025-3-13_11-4-57-version-1-modificationdate-1741860306892-api-v2.png

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 all the individual values provided in the Create list have the Long data type, the list is created with reference to this data type (see type hint Long[] for the action block).

  • The List item resolver on the left-hand side of the Set value event action expects a Long value.

  • By definition, only text (String) is expected from the User prompt resolver, as the entered character string is returned directly.

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.

images/download/attachments/201660713/image-2025-3-13_11-6-36-version-1-modificationdate-1741860396014-api-v2.png

►IMPORTANT◄ Specific rules or restrictions for the execution context (server/client) may be relevant for the type conversion:

  • The input of ‘090’, for example, is converted into the value 90 regardless of the execution context.

  • The input ‘90.0’ or ‘9e1’ only lead to the same result in the server context.

  • The input ‘90°’ cannot be converted to Long, regardless of the execution context.