Lists (Arrays)

How to create a list

Relay.app has various tools to perform operations on lists of data in your workflow. There are three common situations in which you might encounter lists.

1. A step output representing a list of app objects

2. A step output containing a (nested) field that's a list of items

3. A step output containing a (nested) list of app objects

1. A step output representing a list of app objects

Example: A list of Jira tickets obtained by configuring a Find step to return All matching issues in a list

The step output pill will contain a badge with three horizontal lines on top of the app icon to indicate it's a list of Issues, not just a single Issue

Example of a Step Output representing a list of objects (Jira issues)

2. A step output containing a (nested) field that's a list of items

Example: A step output representing an email object from Gmail contains a number of lists:

• Lists of recipients (for the To and CC lines)

• List of attachments

• List of labels

Note: While the structure of every email object contains these lists, this does not mean that they contain data for every email. For example, when an email doesn't have any attachments, the list of attachments is simply empty.

Example of a step output containing lists of items (an email with lists of attachments, recipients, labels)

3. A step output containing a (nested) list of app objects

Example: A deal object from HubSpot contains lists of associated companies, contacts, tasks, and many others.

Example of a step output containing lists of other app objects items (a HubSpot deal with a list of associated companies)

How to work with a list

Loops (Iterators): Perform actions for each item in a list

Once you have a list of items, the most common thing you'll want to do is to perform an action for each item in the list (e.g. upload each attachment to Google Drive). Iterators let you perform one or multiple actions for each item in a list. Read more about Looping (Iterators).

Use your list as input for an AI step

Another common use case is to analyze or synthesize a list of data using AI. For example, to create a digest of a list of newsletters or get combined insights from customer calls. In this case, you'll create a "prompt any model" AI step and use the list as input in data for previous steps.

This technique is demonstrated at 1:35 of this video:

An example workflow that uses an AI analysis of a list

Filtering, combining, and manipulating lists

You can use a Transform Data step to perform a variety of actions on your list, including:

• Filtering based on some criteria

• Combining it with another list

• Removing duplicates

• Appending values

The transform data menu for working with lists

Format a list in text with unrolling

If you want to create a text representation of a list (e.g. a bulleted list in an email body), you could use an AI step to do the formatting for you. But if you want more control and consistency over list formatting, you can use unrolling to render your list in a bulleted or numbered list format.

Inside a multi-line or rich text box, like an email or Slack message body, insert an unroll block for a selected list. Inside the unroll block, insert fields from the object to create the template for how each list item should be displayed in the list.

Multi-line text inputs let you "unroll" list data using custom template structures

Example of an unroll block to format a list of events with subbullets

Example of an unrolled list to create bullet points with key details for open Jira issues

For a detailed demonstration on how to unroll a list, you can check out this video:

Detailed demo of unrolling a list

Unrolling nested list data

Sometimes lists have nested items. For example, you may have a list of jobs, and each job contains a name, start date, and end date.

To unroll nested lists, you'll need to use a Create constant step. Create a multi-line text variable and unroll elements of the list there.

Combine list data into a comma-separated list

The 'Combine' feature is similar to the 'Unroll' feature, except for that it's hard-coded to concatenate all values in the list separated by commas. You can use this in single-line text inputs.

Single-line text inputs let you combine list data into a comma-separated string

Using the size of a list

All lists have a size property. You may use this in a workflow to determine the number of items in the List, and define behavior accordingly. For example, by creating paths for cases where the list contains 0, 1, or multiple items.

The 'Size' property of a list may be used to determine how many items are in a list during a run

Explicitly selecting the first item from a list

While in the majority of cases you'll want to wrap an loop (iterator) around a list, there may be cases when you want to explicitly pick the first item from a list to perform an action on. For example, your CRM might let you add multiple 'Associated Companies' to a deal, even though you're only ever adding one at most. In that case, you can probably just use the 'first result'.

This is why step outputs for lists will still show up in data pickers that only accept a single item. You'll see a 'First result' entry that lets you pick the very first result.

Uploading the first attachment in an email to Dropbox

Adding a comment to the first Jira Issue from a list of issues