Workflow Building Guide

This guide is the short path through building a workflow with the API, and the lessons from building many of them. Build a Workflow covers each part in more depth, and every endpoint name below links to its reference page.

The recommended path

1. Check where you are acting. Who Am I? answers the organization your requests act on and the permissions your key has there. Every workflow, connection and run you touch belongs to that organization.
2. Find the apps and actions. List Universal Apps finds an app by name (q=slack; includeBuiltins=true adds Loop, If/Else, Map and the other built-in steps). List Universal Actions finds its actions. Use the slugs they answer, such as list-users and send-user-message for Slack.
3. Pick a connection. List Connections with app=slack lists the app's connections, the organization's default first. Use one your key's creator can use: their own personal connections, and the organization's shared ones that the connection's role grants open to them. Another member's personal connection, and a shared one whose role grants leave the creator out, are refused. A connection's status is the result of its last sign-in, test or use, so Test Connection before you rely on one that has not been used lately. No connection yet? List Connection Fields says what the app asks for: an app that takes an API key is connected with Create Connection; an OAuth app (requiresBrowser true) needs your key's creator to sign in through Create Connect Link.
4. Create the workflow with Create Workflow, then read its first revision from Get Workflow Definition.
5. Build it in one call with Set Workflow Definition: every trigger and step, nested as they run, each with its configuration. Give each new step a ref and reference it by that ref anywhere in the same body. It is all or nothing, and a refusal lists every problem with its JSON Pointer into your body. Check a body first, without saving it, with Validate Workflow Definition.
6. Set any Map code that reads a step you just created, in one follow-up Update Workflow Step Configuration (see below).
7. Test the steps that read data with Test Workflow Step. Its output becomes the sample later steps read.
8. Validate, publish and turn it on: Validate Workflow, Publish Workflow, then "isActive": true with Update Workflow.
9. Run it by calling its trigger or with Run Workflow, and follow it with Get Run.
10. Check what it did with List Run Steps and Get a Run Step: the exact request each step sent and what the provider answered.

What to know

Revisions

Every change to the draft needs the revision you last read in the If-Match header, sent as "r_..."; Test Workflow Step is the one exception, where it is optional but recommended. A change answers the new one in meta.revision, and the ETag header of a draft read or change is the same value, so you can send it straight back. A 412 means someone changed the draft since you read it: read it again and retry.

Most draft changes don't touch what runs: the workflow's triggers run its published version. Three trigger settings are the exception and go live as soon as you save them, as in the editor: a schedule, a webhook's custom URL and a polling interval. Two things also act on the draft right away: Run Workflow with "version": "draft" runs it, and Test Workflow Step runs one of its steps for real.

Map steps and input keys

A Map step's code reads each input as input['<key>'], and the key ends in the last four characters of the input step's id, in capitals, such as input['slackListUsers7K2Q']. A step created in the same Set Workflow Definition call has no id until the call answers, so:

1. add the Map step with its inputs and no code (it is saved, and shows as not set up yet);
2. read the key from the answer's inputKeys;
3. set the code with Update Workflow Step Configuration.

Code that reads a key no input provides gets undefined at run time, so Validate Workflow and Publish warn UNKNOWN_INPUT_KEY. Read every warning before you publish.

Paging

An app step that lists records makes one request for the first page only, at the action's default page size, unless you set its pagination option. A list longer than one page is cut short without an error. Set "pagination": { "mode": "all" } to read every page. An action that pages by size only takes "mode": "single" instead, so raise its size. Get Workflow Step Schema gives the modes the action takes and its page sizes, and Workflow References describes each mode.

Choosing values from the app

When an argument takes a provider id, such as a Slack channel or user, find it by name instead of guessing: Run Workflow Step Lookup for a step in a workflow, or Resolve Universal Lookup for an action on its own. Both take the text to find as q (search is accepted too).

Conditions

If/Else conditions and step filters compare text case-sensitively. Use startsWith, endsWith, contain and their opposites for text, and set type to number or date to compare those as numbers or dates. Workflow References lists every operator. A single condition is stored, and read back, as a group of one: { "conjunction": "and", "where": [ ... ] }.

Real side effects

Test Workflow Step runs the step for real, with its connection: a step that sends a message sends it, and a step that creates a record creates it. Test the steps that read, and give the steps that write a sample with Update Workflow Step Output instead. Running the workflow, or calling its webhook, sends everything it sends, so check List Runs before you run it again.

Webhooks

A new Webhook trigger queues each call and answers at once (waitForCompletion is false). Its default answer includes runId, the run that call started, so you can follow it with Get Run. It is null when the trigger processes calls in order, since that run starts later, and a trigger set to send a custom response answers that instead, without runId. Its address is in Get Workflow Trigger Configuration.