# 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**](#id-1.-a-step-output-representing-a-list-of-app-objects)
2. [A Step Output **containing** a (nested) **field that's a list of items**](#id-2.-a-step-output-containing-a-nested-field-thats-a-list-of-items)
3. [A Step Output **containing** a (nested) **list of app objects**](#id-3.-a-step-output-containing-a-nested-list-of-app-objects)

### **1. A Step Output representing a list of app objects**

For example, a List of Jira tickets obtained through a [Find Step](find-steps) by configuring it 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<img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FzWriJJkjiktlj4Wp9y7Y%2FCleanShot%202024-11-19%20at%2012.08.15.png?alt=media&#x26;token=f2caa7b7-a26f-46cb-9d6a-6489f9bbe30b" alt="Step output pill showing list badge with three horizontal lines on Jira issue icon" data-size="line">

<figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2F5OgYJZd5RCbufPdn4ycX%2FCleanShot%202024-11-19%20at%2012.05.51.png?alt=media&#x26;token=f0d9ab96-d83a-4fcf-9595-78391f115593" alt="Relay.app workflow step showing Jira Find Issues action configured to return all matching issues in a list format"><figcaption><p>Example of a Step Output representing a list of objects (Jira issues)</p></figcaption></figure>

### 2. A Step Output containing a (nested) field that's a list of items

For example, a Step Output representing an Email object from Gmail contains a number of Lists:

* Lists of recipients (one for the To-line and CC-lines)
* A List of File Attachments
* A List of Labels

Note: while \[the structure of] every Email object contains these Lists, this doesn't mean that they contain data for every email. e.g. when an Email doesn't have any attachments, the List of Attachments is simply empty.

<figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2F70vXQ2gMeXhSco1I4CY0%2FCleanShot%202024-11-19%20at%2012.11.35.png?alt=media&#x26;token=7e9fb528-b1a5-44da-8733-db1173a58540" alt="Gmail email step output showing nested lists including attachments, recipients, and labels fields"><figcaption><p>Example of a Step Output containing lists of items (an Email containing Attachments, recipients and Labels)</p></figcaption></figure>

### 3. A Step Output containing a (nested) list of app objects

For example, a Deal object from HubSpot contains Lists of associated Compenies, Contacts, Tasks, and many others.

<figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FgeuldaENsyyS3COkDFWr%2FCleanShot%202024-11-19%20at%2012.18.17.png?alt=media&#x26;token=9cd9fa10-b6fe-4478-9423-492edede1e35" alt="HubSpot Deal step output displaying associated objects including lists of companies, contacts, and tasks"><figcaption><p>Example of a Step Output containing lists of other app objects items (a HubSpot Deal containing associated Companies)</p></figcaption></figure>

## How to Work with a List

### 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 [iterators](../flow-control/iterators "mention")here.

### Use your List as input for an AI step

Another very 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](https://www.relay.app/templates/newsletter-summarizer) or get [combined insights from customer calls](https://www.relay.app/templates/customer-call-insight-generator). 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:

{% embed url="https://youtu.be/GFCKSkrHiZ4?si=0a0eJzs3s-YeeCPm" %}
An example workflow that uses an AI analysis of a list
{% endembed %}

### Unroll or Combine list data as Text \[Advanced]

If you want to create a text representation of a list in e.g. a a bulleted list in an Email body, and you don't want to simply use an AI step to do the formatting for you, you can used the more advanced 'Unroll' feature to create custom formatted text from a list.

The 'Unroll' feature lets you do this in multiline text inputs, and the 'Combine' feature for single-line text inputs.

<div><figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2F3Q0Jp98jzoAsq6GV8rrG%2FCleanShot%202024-11-19%20at%2012.44.50.png?alt=media&#x26;token=77d3a644-d9b1-4443-b826-eaeed253c47f" alt="Multi-line text input showing unroll data option with template structure for formatting list items"><figcaption><p>Multi-line Text inputs let you "unroll" List data using custom template structures</p></figcaption></figure> <figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FEXj2y7BhM9SinKbndrdl%2FCleanShot%202024-11-19%20at%2012.24.51.png?alt=media&#x26;token=6acc328b-f59c-4285-bf8c-5f9694a0849a" alt="Single-line text input showing combine data option to merge list items into comma-separated format"><figcaption><p>Single-line Text inputs let you combine List data into a comma-separated string</p></figcaption></figure></div>

#### Unroll List data using a custom template structure

Unrolling a List lets you **specify a templated structure that will be repeated for each item in the list**. For example, you can use this to create a bulleted list with key information about all currently open Jira issues.

<figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FytZk4ZDfY5zmfW955yPa%2FCleanShot%202024-11-19%20at%2013.04.57.png?alt=media&#x26;token=c668f122-b041-4cb6-a1fb-2c8e21f50bad" alt="List unroll template showing bullet point structure with Jira issue key, summary, and assignee for each item in the list"><figcaption><p>Example of a Lis 'Unroll', creating a bullet structure that lists out key details for all currently open Jira issues</p></figcaption></figure>

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

{% embed url="https://youtu.be/VqayM6sg8Bc?si=IP2GtXza7fv_8xeM" %}
Detailed demo of unrolling a list
{% endembed %}

#### 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 signle-line text inputs.

<div><figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FO34t9feUkRolO0EDoxfa%2FCleanShot%202024-11-19%20at%2013.11.56.png?alt=media&#x26;token=63d6dae4-574d-471a-a459-fb5c2d2785b8" alt="Text input field showing combine data option to create comma-separated list from multiple values"><figcaption></figcaption></figure> <figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FkXSNYyHiiFNJrQaf9NSL%2FCleanShot%202024-11-19%20at%2013.12.44.png?alt=media&#x26;token=df7b48e4-975f-44e7-b6ba-8a8a6e1d7e57" alt="Preview showing the result of combining list data into a comma-separated string format"><figcaption></figcaption></figure></div>

### 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](../flow-control/paths) for cases where the List contains 0, 1 or multiple items.

<figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2Fm1biUZqW2clU8AEex6bG%2FCleanShot%202024-11-19%20at%2012.51.17.png?alt=media&#x26;token=3f52e77b-1043-434a-8637-e44a9ecd5d78" alt="Step output data picker showing Size property of a list that indicates the number of items in the list"><figcaption><p>The 'Size' property of a List may be used to determine how many items are in a list during a Run</p></figcaption></figure>

### Explicitly selecting the first item from a List

While in the majority of cases you'll want to wrap an [Iterator](#iterators) 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.

<div align="left"><figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2Fufvui9bzroepWaT9rV6W%2FCleanShot%202024-11-19%20at%2012.22.04.png?alt=media&#x26;token=8ac12af2-7527-4b43-994a-54d712a969d0" alt="Dropbox upload step configuration showing first result option to select the first attachment from an email list"><figcaption><p>Uploading the first attachment in an email to Dropbox</p></figcaption></figure> <figure><img src="https://647519108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXkKoEy3xMIYaIwd4mRAB%2Fuploads%2FfFlvmM0X9e8VgMFzqYwJ%2FCleanShot%202024-11-19%20at%2012.29.57.png?alt=media&#x26;token=cc954249-c224-4a0f-8545-9a2484be5474" alt="Jira add comment step showing first result option to select the first issue from a list of issues"><figcaption><p>Adding a comment to the first Jira Issue from a list of Issues</p></figcaption></figure></div>
