Modify list / Clear
See also: Modify list / Remove, Is empty (Compare type)
The ‘Empty’ operation for the Modify list event action removes all entries from an existing list.
►NOTE◄
A ‘cleared’ list still exists as a data object (JSON image: []). Only the entries are removed.
‘Clearing’ the list field of a data object is therefore not the same as assigning ‘No value’ ($null) to this field (see also Equals compare type).
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 option opens a context menu that allows a different operation to be selected.
The symbol for the 'Clear’ operation is the rubbish bin (see screenshot).
The value configuration for the list to be modified must provide an updatable list at runtime.
Without a value configuration for the list to be modified (left), the reference object is automatically used in the context of the Modify list event action.
Without reference to an updatable list, the event action has no effect.
Notes on the selective removal of entries
►IMPORTANT◄ If not all but only certain entries are to be removed from an existing list, the 'Clear' operation is generally unsuitable.
If the primary aim is to obtain a specific subset of given list entries as a list, this can be obtained using the Rule list resolver with the option ‘All values as list’ and a suitable check criterion (see Rule types).
The return value is then a copy of the original list in which all entries that do not match the check criterion (see Rule types) are missing (or appear ‘removed’). However, the original list remains unchanged.
However, a Rule list resolver can also be used to determine the subset of list entries to be removed and to process these cyclically in a For each loop event action using Modify list / Remove.
Exception:
Some value resolvers for accessing attributes (Attribute, Plural attributes (Resolver), Plural typed attribute resolver) provide lists of attributes that represent a defined subset of the entries in the attributes field of the attribute owner.
The attributes returned as a subset can be removed from the attributes field of the attribute owner's list using Modify list / Clear.
If the attribute owner (or the directly or indirectly superordinate entity) is subsequently saved, the relevant attributes are actually deleted.
In this way, the ‘Clear’ operation is used to selectively remove a subset of entries from the list of all attributes, which is delimited by the parameterisation of the value resolver used (Attribute, Plural attributes (Resolver), Plural typed attribute resolver).
Examples
Simple use case: Reset ‘Company types’ for copied company account
When copying an existing company account (see Company accounts), the multiple selection for the Company type in the ‘Company types’ (types) field in the original should be automatically reset so that this selection must be deliberately made ‘from zero’ for the copied instance.
Configuration:
|
Event handling is configured as shown on the right; As the only Triggering event, the ‘Copy’ event (see Common action event) is selected. The Validating rule ensures that the ‘copy’ concerns an entity of the ‘Company Account’ (CompanyAccount) type. The only Action on passed rule is the Modify list event action with the ‘Clear’ operation:
►NOTE◄ The change should not be saved, but only applied to the volatile data status of the copy that appears in the context of an input form for Users during copying. |
|
Special use case: Reset ‘Address contacts’ for copied company account
As an extension to the previous example, all ‘Address contacts’ with the Contact type ‘Employee’ (EMPLOYEE) should now also be removed from the company address (address) when copying a company.
Configuration:
|
In the existing event handling, the Modify list event action shown on the right is supplemented with the ‘Clear’ operation:
|
|
►NOTE◄ This configuration removes all address contacts for ‘Employees’ in the data of the copy. Address contacts with a different Contact type continue to appear in the address of the copied company.
The following configuration variant removes all ‘Address contacts’ in the copied data status:
|
The configuration shown on the right should replace the previous one.
|
|
►NOTE◄ The existing configuration can also be used for any other attribute type, including the ‘Communication infos’ plural attribute type.
For non-typed plural attributes (such as ‘Communication infos’), there is also the dedicated Plural attributes (Resolver), which can also be used as an alternative.
Even if attributes for ‘Communication infos’ always contain a ‘Type’ (communicationType) field, you cannot use Modify list / Clear to remove all attributes for a Communication type (e.g. EMAIL).