Read a list in a workflow

Two list steps read a list: Find rows, which brings back every row that matches, and Find one row, which brings back one. Use them to check whether something has been handled already, to look up a value, or to go through a set of rows one by one.

Who can do this

Workspace Admins and Editors build workflows. Reading a list in a workflow works on every plan, and keeps working when the company's lists are full.

Before you start

The list must exist in this workspace. See Create a list.

Steps

1. Open the workflow in the designer.

2. Select + where the step should go (Add a step). In Search steps, type Find, and choose:

   • Find rows — Reads. Every matching row goes on as its own item, or
   • Find one row — Reads. One item out, whatever happens.

3. The step's settings open. In List, choose the list.

4. Under Show rows where, select + Add condition and set it:

   • choose the column;
   • choose the comparison — is, is not, contains, greater than, before and so on, depending on the column's type;
   • type the value, or type {{ to use a value from an earlier step, such as the invoice number the trigger brought in.

   Add more conditions to narrow it further; a row must match all of them (AND). With no conditions, every row matches.

5. Choose the order:

   • for Find rows, under Sort by;
   • for Find one row, under If more than one matches, take the first by.

   Choose a column, then A to Z or Z to A (text), smallest first or largest first (numbers), oldest first or newest first (dates) — or leave it on the order rows were added.

6. For Find rows, set Most rows to bring back. It starts at 100; 500 is the most. The step stops there.

7. For Find one row, choose under If nothing is found:

   • Carry on with nothing — The next steps get an empty item. Check it with a condition., or
   • Stop the run — The run fails here and says which row it looked for.

8. Select Run this step at the foot of the settings, or Test run at the top of the designer, and open the step's Output tab to see what it found.

What happens next

• The step gives each row's values under its column names. A later step reads them as {{ steps.find_customer.email }} — the email column of the row the Find customer step found.
• Find rows: each row found goes on as its own item, so the steps after it run once per row. If nothing matches, nothing goes on, and the steps after it do not run.
• Find one row: one item goes on, always. It has found set to true with the row's values, or found set to false and nothing else — check it with a condition. With Stop the run, the run fails with Nothing in Customers matched email is rohan@consulace.com.
• In the run, the step shows how many rows it found, what it looked for and the first four rows. See See what a list step did in a run.

Good to know

• A list step picks a list by its id and columns by their own id, so renaming the list or a column does not break it. An expression that spells a column out, like {{ steps.find_customer.email }}, does need editing after a column rename.
• is on a Text column is exact, capitals included. contains ignores capitals.
• is not includes rows with nothing in that column.
• Dates in a step's conditions are read in UTC unless they carry their own offset; {{ $now }} and ISO dates do.
• Reading never counts against the row limit, and keeps working when writes have stopped.
• A list belongs to its workspace. A workflow can only use lists in its own workspace.

If something goes wrong

Related

• Write to a list from a workflow
• See what a list step did in a run
• Using what earlier steps found
• Create a list