Dict Helper

Replace, add or filter for dictionaries or lists a.k.a. JSON objects

Overview

Dict Helper is not only one of the most popular tools, but it is also a powerful tool for Flow. It is capable of storing values, filtering them, parsing Jinja expressions, and much more.

What is essential for you to understand

Dictionaries, essentially JSON objects adapted for efficient program communication, along with lists, constitute the most commonly employed methods for transferring data between programs and bridging the gap between browsers and servers.

1. Dictionaries (Dict)

A dictionary is a structure that is essentially a list of key: value pairs.

Example

{
  "name": "John Doe",
  "age": 23,
  "address": {
    "street": "123 Main Street, Boston",
  }
}

More info

2. Lists

A list, similar to an array, is a versatile data structure designed for storing collections of items. Lists can accommodate a wide range of data types, including:

• Numbers (both floating-point and integers)

• Strings

• Nested lists

• Dictionaries

This flexibility makes lists a fundamental tool for managing and organizing various types of data."

Example

[
  {"name": "John", "age": 23},
  {"name": "Bob", "age": 25},
  {"name": "Charlie", "age": 35}
]

More info

3. Jinja expressions

Jinja is a powerful templating engine designed for Python. It seamlessly integrates with Dict Helper, allowing you to effortlessly execute logic by passing Jinja expressions directly. You can learn more here

Actions

1. Define variables for later use

This action has only one input that accepts dictionaries, lists, and Jinja expressions. It allows you to reference data from Previous Steps, File Uploads, and Environment Variables within your workflow, enabling you to execute custom logic. In this example, the variable contacts comes from a previous step:

Example

{% if contacts | length < 100 %}
  "this is fine"
{% else %}
  "too much"
{% endif %}

2. Filter List V2

The enhanced version of the Filter makes it effortless to apply filtering in a no/low-code manner. Filtering is carried out using a variety of predefined filter operators tailored to different data types. Some of them:

• Exists

• Equal to

• Greater than

• Less than

• Contains

• Is empty

3. Remove list from lists (flatten list)

• Nested lists

• Dictionaries

For instance: if you have a list like

Example of list of lists

[
  [1,2,3],
  [4,5,6],
  [7,8,9]
] 

you get [1, 2, 3, 4, 5, 6, 7, 8, 9] back.

4. Store Value

Add any kind of value to a dictionary

5. Add string to the dictionary

This feature enables you to append a new field with a specified value to an existing dictionary. For instance, if you have a Zendesk user object containing first_name and last_name, you can easily include the age by specifying both the Field name and the desired Content:

6. Add string to list

It allows you to add a new string to an existing list.

7. Replacing fields in lists or dictionaries

With this action, you can replace a value in the specified place.

For example, you have a user (zend1.user):

{
   "user":{
      "first_name": "Max",
      "last_name": "Miller",
      "email": "[e-mail]"
   }
}

And you want to replace the value of the field first_name in the JSON / dictionary response of Zendesk with my_new_name:

Replacing fields in dictionaries

After replacing:

{ 
  "user": {
    "first_name": "my_new_name",
    "last_name": "Miller",
    "email": "[e-mail]"
    }
}

Replace a value in the list: Similarly to the previous example you need to specify the destination - index to access n element in the list. So to replace the user's email here you need to enter it's index [2]

[
  "Max",
  "Miller",
  "[e-mail]"
]

8. Update value

Update any kind of value in a dictionary

9. Append Value

This is very similar to #6.-add-string-to-listbut more powerful It allows you to add an entire row or object to a list.

10. Combine Lists

This helps you to unite two lists in one

Example:

list_1

[
  "Barcelona",
  "Berlin"
]

list_2

[
  "Porto",
  "Kyiv"
]

will be united into

list_combined

[
  "Barcelona",
  "Berlin"
  "Porto",
  "Kyiv"
]

11. Convert List Of Dicts To List Of Lists

Converts list of dicts (JSON objects):

list of dicts

[
   {
      "email": "[e-mail]",
      "last_name": "Miller",
      "first_name": "Max"
   },
   {
      "email": "[e-mail]",
      "last_name": "Zoal",
      "first_name": "Peter"
   }
]

to list of lists:

list of lists

[
  [
    "[e-mail]",
    "Miller",
    "Max"
  ],
  [
    "[e-mail]",
    "Zoal",
    "Petr"
  ]
]

12. Filtering

For a large list, larger than 50k entries or 5 MB, please use the Spreadsheet helper with action Query spreadsheet, as it can better handle large data.

You can also use the Jinja filter selectattr to filter without having to use an action.

More details can be found here.

Filtering a list

will most likely be used a lot for CSV files or e.g. GoogleSheet content that is a list of lists. Please see the section here on filtering CSVs here.

Filtering a JSON / dictionary (dict)

As an example, let's say you want to filter a list of Freshdesk or Zendesk tickets. The response JSON of an API would look like this:

{
   "tickets": [
      {ticket1 ... some more JSON},
      {ticket2 ... some more JSON},
      {ticket3 ... some more JSON}
   ...
   ]
}

The corresponding connector setup looks like this:

As a list reference in this case, you would provide zen1.tickets in order to only get the list of tickets, because as you can see, within the above JSON object is again a list, indicated by the squared brackets [ ]. So essentially, you could say the above is a JSON object that wraps a list of ticket objects, which are again JSON.

If you want to filter for a particular data record e.g. after pulling all your Zendesk tickets, you want to get all tickets where the requester_id is 12345, you could filter for:

item.requester_id == 12345

An alternative notation which would yield the same result would be HTML

12345 in item.tags

More examples:

"email" in item.profile and item.deleted == False and item.updated >= (unix_timestamp - 3* 24 * 60 * 60)

item.created_date > "{{ convert_datetime(date, '%Y-%m-%d', -30) }}" and item.status == "active" and item.email[-10:] != "locoia.com"

Note that you cannot use the item parameter in combination with Jinja, here need you to use Python instead.