removeItemsFromList

A Workflow Engine function that removes a set of specified items from an existing list (array) and writes the resulting modified list back to the source field, or to a different destination field. The source and destination fields can be located in the workflowContext or an event, alert or Situation field. The “itemsToRemove” can include an explicit list, or a substituted value. If the substituted value contains a list already, this will be expanded (refer to the Examples, below, for more information).

This function is available as a feature of the Add-ons v2.2 download and later.

This function is available for event, alert, and Situation workflows.

The workflow sweep up filter applies to this function.

Back to Workflow Engine Functions Reference.Workflow Engine Functions Reference

Arguments

Workflow Engine function removeItemsFromList takes the following arguments:

Name

Required

Type

Description

sourceField

yes

string

The source field (CEvent or workflowContext) for the list.

itemsToRemove

yes

object

The list of items to remove from the source list. Substitution is allowed.

destinationField

no

string

The field to write the results back to. Can be either the CEvent field or the workflowContext.

Example

The following example demonstrates typical use of Workflow Engine function removeItemsFromList.

The following examples use this source list custom_info.services:

[ "apple" , "pear" , "skippy" , "boomerang" ]

Removing “in place” from a CEvent field:

  • sourceField : custom_info.services

  • itemsToRemove : [ “apple” ]

The UI translates your settings to the following JSON:

{"sourceField":"custom_info.services","itemsToRemove":["apple"]}

Removing from one list and writing to another:

  • sourceField : custom_info.services

  • itemsToRemove : [ “apple” ]

  • destinationField : custom_info.newServices

The UI translates these settings to the following JSON:

{"sourceField":"custom_info.services","itemsToRemove":["apple"],"destinationField":"custom_info.newServices"}

Using substitution in the “itemsToRemove”

Given a sourceField of workflowContext.source and a destination field of workflowContext.newService, we will remove a dynamic list also held in the workflowContext.

The workflowContext before the action:

WORKFLOW CONTEXT: ALERT: 634 :  : 
{
    "source": [
        "apple",
        "pear",
        "dog",
        "cat",
        "banana"
    ],
    "delete": [
        "banana"
    ]
}

In this example, to delete “banana” from the source.

The itemsToRemove argument uses a substitution, but this still has to be an object, such as [ ] (a list, or array). The workflow performs the substitution as needed and ensures that the list is correctly formed, using the standard substitution syntax.

For example:

{"sourceField":"workflowContext.source","itemsToRemove":["$(workflowContext.delete)"],"destinationField":"workflowContext.newServices"}