Modify list / Add
The ‘Add’ operation can be used to add a single entry to a given list, which generally appears at the end of the list.
Configuration
The ‘Add’ operation is already selected after adding a Modify list event action to a workflow.
The value configuration for the modified list (left) must provide an updatable list at runtime.
If a value configuration for the modified list (left) is omitted, the reference object is automatically used in the context of the Modify list event action.
The value configuration (right) defines the added entry.
If a value configuration for the added entry (right) is omitted, the default value is ‘No value’ ($null).
However, an explicit value configuration for the added entry (right) can still access the reference object in the context of the Modify list event action.
Examples
Simple use cases: List with simple values
The following series of examples demonstrates different simple use cases for adding entries to a list of simple values (of the String type) with the Modify list event action.
The ‘Result’ column shows the JSON image of the resulting value for the list stored in the list variable after the sequential execution of all configurations up to the respective table row.
|
Configuration |
Description |
Result |
|
|
The value configuration for the modified list (left) creates an empty list via the Create instance value resolver and assigns this data object to the list variable via the concatenated Store value as variable resolver. ►IMPORTANT◄ The initialisation of the list is absolutely necessary here. A Variable value resolver with the ‘List’ type cannot replace the value resolver chain as it does not automatically generate a List object. A value resolver for the Text with the text value A is used as the value configuration for the added entry (right). |
["A"] |
|
|
The next step is to first use an Execute with event action to define the list created in the previous step as a temporary reference object for the action block. This is done by the Variable value resolver in the Object resolver parameter by addressing the list variable name. ►NOTE◄ The settings for the Type and the Is collection of option were made manually here to reflect the arbitrary convention that ‘our’ list should only contain text values. Therefore, the String[] data type – i.e. ‘String list’ – is notified for the action block below. Within the Modify list event action, this type note also appears for the left-hand value configuration. We can therefore dispense with an explicit value configuration for the modified list, as this is available as a reference object at runtime. A value resolver for static Text with the text value B is used as the value configuration for the entry to be added (right), as in the previous example. ►NOTE◄ The Modify list event action always adds new entries to the end of a list. |
["A","B"] |
|
|
The next step demonstrates that a list available as a reference object can be used as an input value for the value configurations on both sides of the Modify list event action. Similar to the previous step, an Execute with event action refers to the list variable as a temporary reference object. Of course, alternatively, the action block from the previous step could have been extended. As in the previous step, there is no explicit value configuration for the list to be modified (left) within the Modify list event action, as this is available as a temporary reference object. The value configuration for the added entry (right) uses a List item value resolver that returns the first entry from the list available as an input value or reference object with default settings (‘Value (from start)’ mode and offset 0). Therefore, in the given scenario, the List item returns the text value A that was added to the list list in the first step. This value is now added again at the end of the list. |
["A","B","A"] |
|
|
The final step demonstrates the special interpretation if a value configuration is omitted for the entry to be added (right): As in the previous step, the existing list (via Variable list) is available as a temporary reference object in the action block of an Execute with event action. As above, a value configuration for the list to be modified (left) has been omitted, so this list is modified. In contrast to the previous step, the value configuration for the added entry (right) has now also been omitted. In contrast to the value configuration on the left, ‘No value’ ($null) is the entry added on the right and not the string image of the list built up to that point. |
["A","B","A",null] |
Special use case: Unique list
In general, ‘lists’ in Lobster Data Platform / Orchestration are data objects of the ‘list’ (List) type, in which entries of any type can be ‘strung together’. The same entry can also occur multiple times.
However, a ‘unique list’ (Set) is used in special cases. A ‘unique list’ generally also allows entries of different types, but cannot contain the same entry more than once.
The data structure for Users, for example, provides the ‘Companies’ (companies) field for a ‘Unique list’ of Long values that are references to the ‘ID’ (id) of Company accounts, which the user can use as the Company of session when logging in.
In the following example, the Modify list event action is used to ensure that the list of ‘companies’ (companies) for a given user account contains references to the Company of session and any other company with the Company type ‘Bill-to party’ from its parent hierarchy.
Configuration:
|
Within an action block that provides the relevant user account as a reference object (e.g. an Execute with or For each loop event action), two instances of the Modify list event action are configured as shown on the right:
|
|
The following scenarios are possible for the runtime behaviour of this configuration:
If the user account has not been saved yet, so there is no companies list at the beginning, the field is automatically initialised with an empty ‘Unique list’. In contrast to the previous example, there is no need to use the Create instance value resolver.
If the ‘ID’ (id) of the Company of session is not yet included in the list of companies, it will be added.
If the account of the Company of session refers to the Company type ‘Bill-to party’ via the ‘Company types’ (types) list field, the second instance of the Modify list event action has no effect, as the ‘ID’ (id) of the Company of session may already have been added to the companies list.
Otherwise, the parent company hierarchy is searched for a company that qualifies as a ‘Bill-to party’.
If a corresponding company is found and its ‘ID’ (id) is not yet included in the user's list of companies, it will be added.
In all other cases (no ‘Bill-to party’ can be found or the ‘Bill-to party’ determined is already contained in the companies list), the second instance of the Modify list event action has no effect,
More complex use case: Adding a typed plural attribute
When a new user account (see Users) is created, the address of the Company of session should be added to its address contacts with the Contact type ‘Location’ (LOCATION).
Configuration:
In an event handling that reacts to the ‘Create’ event (see Common action event and uses Check type to ensure that an entity of the type ‘User’ (User) is to be created, a Modify list event action is configured as follows:
The value configuration for the list to be modified (left) uses a value resolver chain:
The Object property value resolver first accesses the address field of the user account available as a reference object.
The concatenated Plural typed attribute resolver refers by selection for Typed attribute to the type ‘Address contact’ and its Subtype ‘Location’ (LOCATION), which was previously created as a custom value in the dynamic enumeration Contact type.
The value configuration for the added entry (right) uses the Create instance with values resolver to create an attribute value for the Type ‘AddressContact’ (AddressContact).
The only Property that needs to be set explicitly for this new attribute value is the contactAddress field, which is assigned the address of the Company of session as the value.
As the modified list (left) uniquely qualifies the Subtype ‘Location’ (LOCATION) via the configuration for the Plural typed attribute resolver, this does not need to be explicitly assigned in the address contact value on the right.
►NOTE◄ If several address contacts with different Contact type are assigned when the user account is created, the All attributes of one type resolver with the type ‘Address contact’ could be used to initially define the modified list without reference to a Subtype. This list can then be modified by a series of different Modify list instances, which must, however, contain an explicit assignment for the ‘Contact type’ (contactType) field for each entry added.
►NOTE◄ In this example, the address data of the Company of session is transferred to the new address contact of the created user. As addresses are Referenced objects, the address field of the company and the contactAddress field of the address contact currently refer to the same ‘address’ entity. However, the address data in both contexts can be changed at any time, which would result in the reference to a different ‘address’ entity being changed in each case. There is no permanent link between the company address and the address contact.