Skip to main content

Iterate Over an Array (JSON)

When integrating with certain applications, you may find that some actions in your module workflow return an array of JSON objects. For example, your action might query a database for a subset of data and you want to send a notification for each result. To set up that notification, you must iterate over the array and handle each object one at a time.

There are various ways to handle an array, but the best practice is to leverage the Create Sub Items action to create an inner-item for each object in the JSON array. For the walkthrough below, we're working with a Mattermost data action that queries Mattermost for all the users in our instance and returns an array of six sample user objects from Mattermost:

json_array_object_example.png

To iterate over a JSON array using the Create Sub Items action, follow the steps below:

  1. In the module builder, select the add block button, add_block.png, after the action that returns a JSON array. The Action Block panel displays.

  2. Select the Create Sub Items action block. The Create Sub Items panel displays.

    add_create_sub_items_action.png

  3. Select + Add to add a Dynamic field. A new Dynamic field displays.

    create_sub_items_add_dynamic.png

  4. Select the configuration button,three_dots.png , beside the newly-created Dynamic field. The Configuration window displays.

    create_sub_items_config_select.png

  5. The Input Type required depends on the size of the array you want to iterate through and whether you're processing the whole thing or only a subset of values from it:

    • Text - Select this option if the input for the action is plain text, such as a formula. If your array contains large objects and you want to process the entire array, you may need to leverage a formula field to map and index the objects one-by-one.

      create_sub_items_config_text_select.png

      For our example, we must create the formula field below to parse the array and create an index of the objects, after which we can use the index to access each object. We add the following formula, "Map Index", into the Dynamic field:

      RegexReplace(Map({Get Users - Response Whole}, "$singleItemIndex"), "\[|\]", "")
      map_index_formula_builder.png

      The Map formula maps each item in a JSON array using a specified formula or function, generating an array of new values.

      Notice the formula added to the Dynamic field:

      create_sub_items_dynamic_formula_field.png

    • JSON - Select this option if the input for the action contains the raw JSON object. This option is helpful if you're processing a smaller array or the action you're working with returns only a subset of data for each object.

      create_sub_items_config_json_select.png

  6. After configuring the Create Sub Items action, select the add block button, add_block.png, after it. The Monitor Items trigger block is added.

    add_monitor_items_block.png

  7. In the Monitor Items panel, set the trigger to continue the flow. There are two options for ensuring the trigger continues the flow:

    • Change the trigger to an Item is Added trigger:

      Select the blue pencil icon, blue_edit_pencil.png, beside the trigger type, then select Item is Added. The trigger type changes to Item is Added.

      monitor_items_change_trigger_type.png

    • Remove the condition group from the Match Conditions trigger:

      1. Select the condition dropdown. The condition group displays.

        monitor_items_select_condition.png

      2. Select the settings button, three_dots_horiz.png, and select Delete Condition. The condition resets.

        monitor_items_delete_condition.png

  8. Next, for each object in the array (in our example, indexed as a number from 0 to 6), we want to take an action—this can be any action that's relevant to your use case. In our example, we leverage a formula to locate the email address for each user object and update the manual field User with the email address value using the Update Field action.

    Select the add action block, add_block.png, after the Item is Added trigger. The Action Block panel displays.

    add_block_after_monitor_items_trigger.png

  9. Select the Update Field action block. The Update Field panel displays.

    update_field_block_select.png

  10. Select the Field Name dropdown and select the field you want to update. In our example, we want to update the User field with the email address of each user object we created an inner-item for.

    update_field_select_field_name.png

  11. In the Value field, select the insert field button, insert_field.png, then select the Formula Fields button, formula_calculator.png. The Formula fields display.

    update_field_value_insert.png

  12. Either scroll or use the search field to locate and select Json Path. The Create formula window displays.

    update_field_add_json_path_form.png

  13. Construct the formula to find the relevant value in your array. For our sample array, we configure the formula below, which leverages a Concatenate formula to combine the index value (that is, 0, 1, 2, and so on) with the JSON path to locate the email address for each object:

    JsonPath({Get Users - Response Whole}, Concat("$[", {Title}, "].email"), false)
    create_formula_editor_view.png

    Note that you can select the configuration button, three_dots.png, to the toggle between the Advanced View and Builder View. In the Advanced View, you can copy and paste formulas as plain text.

    formula_builder_settings_view.png

    When complete, the Value field should contain the relevant formula, such as in the image below:

    update_field_complete.png

    To access the JSON array received from a custom action, you may need to store the array in a field when handling the response of that custom action. In the image above, the Get Users - Response Whole field is an automatically-generated matched entity from a field storing the JSON array in a custom action.

  14. Next, test the module to confirm the workflow is behaving as expected:

    1. Select Test at the top of the module builder. The Test {Module Name} window displays.

      test_select.png

    2. Create a new test item, then select Test Now. The test runs, then the Module Events History screen displays, with the most recent test run selected.

      test_module_window.png

    3. In the left panel, notice each inner-item created by the module.

      module_history_left_panel.png

      Select an inner-item, then select the Success status for the Update Field action in the Flow Run panel. The action detail window displays.

      module_history_select_inner_item.png

    4. Confirm the action worked as expected. In our example, we can see the Update Field action was successful: the email address was added to the User field.

      module_history_action_detail.png

      Return to the Module Events History screen to confirm the workflow for each inner-item worked as expected and that the Create Sub Items action successfully iterated through the entire array.

      Notice on the business report, as well, that each object displays as an inner-item, including the emails for each user:

      business_report_inner_items.png

With your module successfully tested and each inner-item moving through the workflow as expected, you have successfully itereated through the entire JSON array and taken action on each object.

From this point, you can continue the workflow as desired for each inner-item (created from each JSON object). In our example, we might use a Send Notification action to contact each user we extracted from the array—but that's just one option. You can manipulate and act on inner-items in almost any way you can act on parent items.

In this section: