Modify list / Remove
The ‘Remove’ operation of the Modify list event action can be used to remove a single element from an existing list.
CAUTION
The configuration of the Modify list event action for the ‘Remove’ operation seems rather straightforward.
However, it only achieves the desired result in a reliable way if it is configured so that the identification of the entry to be removed succeeds as desired, taking into account any specific ‘handling’ for the respective Data type in the intended Execution context (server/client).
Defining a ‘solid’ identification for the entry to be deleted is a challenge that requires attention and care. Detailed and meaningful Tests are recommended, even or especially if the configuration looks simple and seems to work straight away.
The following notes explain dependencies in abstract terms, which can determine the characteristics when performing a ‘removal’. Examples that illustrate these topics in specific terms follow below.
►IMPORTANT◄ How to identify the entry to be removed?
The Modify list event action compares the entries in a list specified by the left-hand value configuration in the specified order with the compare value specified by the right-hand value configuration.
If a list entry is recognised as matching the compare value, this list entry is removed and the search is ended. This means that only the ‘first match’ is removed from the list.
Whether a list entry is considered a ‘match’ depends on whether it is defined as corresponding to the compare value according to the logic applicable in the execution context (client/server) for the data type in question.
In contrast to other comparison scenarios (e.g. Entity property rule or Field restriction), there is no automatic type conversion. This applies regardless of the execution context (server/client).
Even removing a simple value is not necessarily straightforward. The following aspects must be taken into account:
The Data type must match exactly. For example, a Long value 2 is not considered to match an Integer value 2, although an Entity property rule with the Equals comparison judges otherwise.
In the Client context, Long values are treated as complex data objects, unlike other numerical data types, which means, for example, that even return values from different instances of the value resolver for Long with the same value (e.g. 2) are not considered to be the same.
Consequently, if a less critical ‘discrimination’ is required to identify the entry to be removed, it should be identified directly from the list using a Rule list resolver with a suitable criterion (e.g. Entity property rule).
Complex values (data objects with fields) that are not entities are handled differently depending on the execution context:
In the Server context, complex values are generally compared ‘in terms of content’. They are considered to match exactly when all field values match (see ‘Compare object contents’ with the Equals compare type).
In the Client context, complex values are generally only considered as matching if they are identical and do not only have matching field values (see also note for Long values in the client context, above).
If a list contains complex values with matching content, each individual instance can be clearly identified as an entry to be removed in the client context using the List item resolver. In the server context, on the other hand, the first entry that matches the content of the addressed List item would always be deleted.
If less critical ‘discrimination’ is required to identify the entry to be removed, it should therefore be identified directly from the list using a Rule list resolver with a suitable criterion (e.g. entity property rule).
Complex values that belong to the subcategory of entities are handled differently depending on the execution context:
In the Server context, the data of entities that have been included as input objects in the context of a transaction are managed via a cache that uses the ‘ID’ (id) of the entity as the key value.
When accessing an entity that has already been created, the cache is therefore generally searched first for a (possibly volatile) data status for its ‘ID’ (id). If this exists, it is used for the requested read or write operation.
►IMPORTANT◄ A volatile data status found in the cache also overrides the data status for the relevant entity actually retrieved from the server by the search in the return value of a Search.
There is no cache in the Client context. Therefore, retrieving an entity via a Search always creates an independent data object that is not identical to other data objects, even if they refer to the same entity and have no differences in field values.
If a less critical ‘discrimination’ is required to identify the entry to be removed, it should therefore be identified directly from the list using a Rule list resolver with a suitable criterion (e.g. ‘ID’ (id) in an Entity property rule).
Configuration
►NOTE◄ After adding a Modify list event action to a workflow, the ‘Add’ operation is selected by default. Clicking on the icon for the operation opens a context menu that allows you to select a different operation.
The value configuration for the list to be modified (left) must provide an updatable list at runtime.
If a value configuration for the list to be modified (left) is omitted, the reference object is automatically used in the context of the Modify list event action.
The value configuration (right) defines the entry to be removed.
If there is no value configuration for the entry to be removed (right), the default value is ‘No value’ ($null).
However, an explicit value configuration for the entry to be removed (right) can still access the reference object in the context of the Modify list event action.
Examples
Simple use cases: Remove simple values
The following series of examples demonstrates various simple use cases for removing entries from a given list of simple values using the Liste modifizieren 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 list to be modified (left) creates a list from static Text ["A","B",null,"B","A","C"]via the concatenated JSON to JSON to object resolver and assigns it to the list variable via the Store value as variable resolver. ►NOTE◄ The type hint for the return value here is just Objekt (and not Objekt[]), which corresponds to the general case for the return value of the JSON to object resolver. A value resolver for static Text with the text value B is used as the value configuration for the entry to be removed (right). As can be seen in the ‘Result’ column (right), the first matching entry is removed from the list at runtime, while the second B is retained. |
["A",null,"B","A","C"] |
|
|
This step is intended to demonstrate that a list available as a reference object can be used as an input value for the value configurations on both sides of the Liste modifizieren event action. In the header of an Execute with event action, the Object resolver accesses the Variable list , i.e. the list that is the result of the previous modification. In the Variable value resolver, we select the ‘Object’ Type in conjunction with the Is collection of option for clarification. This is why the type hint Objekt[] appears for the action block. The same type hint also appears in the placeholder for the value configuration for the list to be modified (left) in the Modify list event action in the action block. This signals that the list available as a reference object is modified if a value configuration is completely omitted. A List item resolver with the Mode ‘Value (from end)’ and an Offset of 0 is configured as the value configuration for the entry to be removed (right), which returns the text value C at runtime, as this is the last value of the list available as a reference object.
►IMPORTANT◄ As the results column shows, the
C
at the end of the list is actually removed. However, this only works because none of the previous entries match this text value. If the value configuration returns a simple value for the entry to be removed, the first ‘equivalent’ entry in the list (from the beginning) is removed. |
["A",null,"B","A"] |
|
|
Now the null value is removed from the remaining list. The Variable list is accessed as the value configuration for the list to be modified (left) in a Modify list event action. Without a value configuration for the entry to be removed, the first match for ‘No value’ ( $null ) is removed. |
["A","B","A"] |
|
|
Finally, all instances for the text value A should be removed from the remaining list. This task can only be achieved by repeatedly using the Modify list event action. For an indefinite number of matching entries, this can only be guaranteed with the help of a For each loop . However, it is not necessary to iterate over all entries of a possibly very extensive list, as the solution in the screenshot on the left shows:
|
["B"] |
More complex use case: Remove complex value (no entity)
In the following examples, the ‘Date with time’ (DateTime) object, which has two fields, serves as a simple example of a complex data type that is not an entity:
The ‘Date value’ (dateValue) field contains a Long value that dates the time as an offset to the time origin (01.01.1970 00:00:00.000 UTC) in integer milliseconds.
The ‘Time zone’ (timeZone) field refers to a Java time zone that is to be linked to the time as the ‘source time zone’.
This structure qualifies every date specification per DateTime as a complex value, even if the data object with two fields appears more manageable.
|
The screenshot on the right shows an overview of a configuration that is used as the basis for a series of experiments to demonstrate the comparison logic of the Modify list event when removing complex values in different contexts and to prevent possible misunderstandings:
|
|
|
►NOTE◄ As can be seen in the screenshot for the object resolver (top left), all instances of the Relative date with time resolver in the list refer to the type ‘End of today’ in combination with a specific time zone. While the same time zone (UTC) is referenced for the first and last list entry, the middle list entry differs (Africa/Cairo). The Show alert event action would display the generated list as follows if the Modify list event action did not exist (or was deactivated): [UTC,Africa/Cairo,UTC] |
|
The following table compares configuration variants for the Modify list event action with the result achieved for each execution context:
|
Configuration |
Result |
Description |
|
|
Server context: [Africa/Cairo,UTC] |
In the server context, the return value of the Relative date with time resolver for the value to be removed (right in the screenshot) is considered to match the first and last list entry, since the parameterisation matches and – on the condition that the creation and modification of the list takes place on the same UTC calendar day – generates a ‘date with time’ (DateTime) value with matching field values (dateValue, timeZone). The second and third entries remain in the result as only the first ’match‘ is removed from the list. |
|
Client context: [UTC,Africa/Cairo,UTC] |
No list entry is removed in the client context, as the DateTime value to be removed as a data object is definitely not identical to one of the list entries. Even if the data object matches two list entries in all field values, it was only created with the Relative date with time resolver after the entries for the list. |
|
|
|
Server context: [Africa/Cairo,UTC] |
In this variant, the first value of the list is referenced as the entry to be removed via the List item resolver with Mode ‘Get first’ and Offset 0. This configuration is suitable for reliably removing the first value in the list, regardless of the execution context. However, the reason for the hit is different in each case:
|
|
Client-Kontext: [Africa/Cairo,UTC] |
||
|
|
Server context: [Africa/Cairo,UTC] |
In this variant, the List item resolver accesses the last list entry with the Mode ‘Get last’ and Offset 0 to name the value to be removed. As its field values match the first list entry completely, the first list entry is deleted in the server context, while the last one is retained. |
|
Client context: [UTC,Africa/Cairo]
|
In the client context, the identity between a list entry and the value to be removed is decisive. This is only given for the last list entry, regardless of whether the field values match, so that it is reliably removed. |
|
|
|
Server context: [Africa/Cairo,UTC] |
The last variant shows a somewhat more complex configuration for the value to be removed, which ensures that the first match for a value determined via the Relative date with time resolver is reliably removed regardless of the execution context (server/client): The Rule list resolver is used here to search for the first entry in the list available as a temporary reference object using the Entity property rule that matches the compare value (right) from the Relative date with time resolver. With the given data, the Rule list resolver reliably identifies the first list entry as the value to be removed. ►NOTE◄ The principle of this variant should always be used if the Modify list event action is intended to reliably remove the first entry that fulfils a condition that can be configured in the Rule list resolver. Then the removal works independently of the execution context (server/client) and there is no risk of deviating results when transferring the configuration from an event handler to a Client workflow via copy and paste. ►NOTE◄ The effect of this method is that the comparison logic for identifying the value to be removed, which is actually only applicable in the server context, takes effect in the client context. However, there is no comparably simple concept that could enforce that the comparison logic applicable in the client context (identity of the data objects) could be applied in the server context. |
|
Client context: [Africa/Cairo,UTC]
|
Special use case: Remove entity
The ‘company account’ (CompanyAccount) is used as an arbitrary example of an entity in the following examples, as these are present in every Lobster Data Platform / Orchestration implementation.
|
The screenshot on the right shows an overview of a configuration that is used as the basis for a series of experiments to demonstrate the comparison logic of the Modify list event when removing complex values in different contexts and to prevent possible misunderstandings: To be able to create a list of entities (here: Company accounts), access to the entities to be used as entries must first be guaranteed. In principle, it is possible to include company accounts as an Input object (type safe) based on long values for the ‘ID’ (id) of the account. However, this only works in the server context. To ensure that the same configuration also works in the client context, three instances of the search are used on the right, each of which maps a Company accounts to a specific variable (ca1, ca2, ca3). Based on the examples for removing complex values (see above), a list with three entries is created as the basis for a series of Tests, of which the first and last entry refer to the same entity. The Search event actions for the ca1 and ca3 variables are therefore parameterised to match, so that this entity is the only match as the value of the variable.
|
|
|
For the documentation of the following examples, we assume that the name of the company referenced by Variable ca1 and ca3 is ‘A’ and that Variable ca2 references a company with the name ‘B’. The Show alert event action would therefore output the following string as a Message for the complete list: [A,B,A] |
|
The following table compares configuration variants for the Modify list event action with the result achieved for each execution context:
|
Configuration |
Result |
Description |
|
|
Server context: [B,A] |
To identify the entry to be removed, the Variable ca1 is used here, which already contributed the value for the first list entry when the list was created. The value of the Variable ca1 is logically identical to the first list entry and does not only match in terms of content, so that exactly this value is reliably removed in the server context as well as in the client context. Instead, the List item resolver with the Mode ‘Value (from start)’ and Offset 0 could have been used, which in the given scenario also refers exactly to the search result referenced in the ca1 variable. |
|
Client context: [B,A] |
||
|
|
Server context: [B,A] |
In this variant, the List item value resolver accesses the last list entry with the Mode ‘Value (from end)’ and Offset 0 to name the value to be removed. At first glance, it may seem unexpected that the first list entry is still deleted in the server context. However, this is only an indirect effect of accessing the cache for entities, which is only relevant in the server context: The value for the Variable ca3 is set (as described above) based on the result of a Search that returns the same company account that was already ‘found’ by the Search performed for the Variable ca1 and added to the cache. This cache value is therefore assigned to ca3 variable the second time it is accessed. As ca1 and ca3 reference the same data object for company account ‘A’, the first and last list values are identical. Therefore, the first entry is deleted, although the configuration refers to the last list entry. |
|
Client context: [A,B]
|
In the client context, the identity between a list entry and the value to be removed is also decisive. As the client context does not provide a cache for entities, the search results in the ca1 and ca3 variables technically reference different data objects here, even if their content is completely identical. Consequently, in this case the last list entry is removed ‘as ordered’. |
|
|
|
Server context: [B,A] |
The last variant shows a somewhat more complex configuration for the value to be removed, which can be used to ensure that the first list entry, which refers to the company account referenced here via Variable ca3, is reliably removed regardless of the execution context (server/client): The Rule list resolver is used here to search for the first entry in the list available as a reference object by checking an Entity property rule that matches the compare value (right) – here: the Variable ca3 – in the ‘ID’ (id) field. With the given data, the Rule list resolver reliably identifies the first list entry as the value to be removed, regardless of the execution context (server/client). ►IMPORTANT◄ In the example scenario, the list only contains entities of the same ‘Company account’ (‘CompanyAccount’) type. When accessing the Variable ca3, the same entity type is addressed via the Type parameter, so that the return value is ‘No value’ ($null) if ca3 does not refer to a ‘Company account’. Only under these conditions does the rule in the Rule list resolver work without an additional check for the match between the entity type of the list value (left) and the compare value (ca3). In order to reliably remove a company account from a list with entries of potentially different types based on its ‘ID’ (id), it must be explicitly ensured that not only the same ‘ID’ (id) but also the ‘searched’ entity type matches for the list entry. For this purpose, a second condition would have to be added to the Rule list resolver using an AND Junction, which ensures that not only the ‘ID’ searched for is present for the list entry, but also the entity type searched for (e.g. via Check type). |
|
Client context: [B,A]
|
