Work with Data and Lists

Iterate over a List by Using a Loop Block

A Loop Block iterates over the items in a list, enabling the Actions within it to repeat for each item. In the Loop List parameter, you put a JSON node containing a list. The Loop Block processes one item in the list at a time. For example, suppose the list looks like this:

      {
        "Products": {
          "Ids": [
            {
              "Id": 1
            },
            {
              "Id": 2
            }
          ]
        }
      }
    

Each iteration of the Loop Block receives a single element, nested in the structure of the list:

{
  "Products": {
    "Ids": {
      "Id": 1
    }
  }
}    

Actions within the Loop Block have access to one element at a time.

Note

For a Loop Block that calls an Omnistudio Data Mapper Transform, a list with more than 1000 items degrades performance. You can use a paging strategy to break up long lists.

Note When the Omnistudio standard runtime is disabled and RollbackIPChanges is set to true, Loop Blocks in an Integration Procedure can result in loops executing within other loops. To resolve this, ensure that you have an Integration Procedure containing a loop that invokes a second Integration Procedure with an inner loop, RollbackIPChanges is set to false, or Omnistudio standard runtime is enabled.

Note When you enable the Include All Actions in Response setting for an Integration Procedure, a Loop Block in the Integration Procedure can’t process an array of records. This occurs because the stepResultFinal array exceeds a size of 1 and results in an error:

Cannot Write Array to Root

You can use a Loop Block to search for multiple records in a Salesforce object. Let’s say you wanted to search for Contacts with the name “Miller” or Torres. You can put a Data Mapper Extract Action in a Loop Block, then pass in a list of names in the Input Parameters.

Consider the following JSON:

{
    "names": [
        {
            "Name": "Miller"
        },
        {
            "Name": "Torres"
        }
    ]
}

To search for these names in a Loop Block:

1. Create a Data Mapper Extract that selects records with the Filter Contact.LastName LIKE Name.
2. Create a Data Mapper Extract Action in the Loop Block with the Data Source names:Name and the Filter Value Name. Set the Data Mapper Name to the name of the Data Mapper Extract.

As the Loop Block executes, the Data Mapper Extract Action uses each Name from the names list in the input JSON to search Contact.LastName.

Merge Lists by Using a List Action

The List Action merges multiple lists by matching values of specified list item JSON nodes. A basic merge matches node names exactly. An advanced merge matches nodes that have different names or reside at different levels in the incoming lists.

The inputs to a List Action must each be in list format even if the list contains only one item. Omnistudio Data Mapper Extracts that return a list with one item often convert it to a single object. To convert a single object back into a list, you can use the first example in Omnistudio Data Mapper Transform Examples.

For more list processing options, see List Input for Omnistudio Data Mappers and the AVG, FILTER, IF, LIST, LISTMERGE, LISTMERGEPRIMARY, LISTSIZE, MAX, MIN, SORTBY, and SUM functions in the Function Reference.

To match nodes that have different names or reside at different levels in the incoming lists, click Advanced Merge and specify settings for the nodes to be matched, as follows:

• List Key: Enter the name of the JSON list node where the node to be matched resides.
• Matching Path: Enter the path within the list to the node to be matched.
• Matching Group: Specify the same number for all nodes you want to match.

For example, this figure shows how to match first and last names from two incoming lists in which the nodes have different names.