Sign inGet started
Docs
Get started

Set Workflow Definition

Set the workflow's whole draft in one call: the fastest way to build a workflow, and the one to use from an agent. Send triggers and steps as Get Workflow Definition answers them. Name a step or trigger the draft has by its id; give a new one a ref of your own and its app (and action), and reference it anywhere in the same body by that ref: {{ steps.<ref>.output[0].id }}, or in a Map's or Group results' inputs. Nest steps in body, then and else where they go. Each step's configuration takes { arguments, options, connection } as Update Workflow Step Configuration does, except that each part you send replaces that part whole; leave configuration out to keep it. A step or trigger you leave out is removed, with the steps it holds. Keys Get Workflow Definition answers that cannot be set (number, slot, depth, appSlug, actionId, isConfigured, and the workflow's own name, tags and so on) are accepted and ignored, so you can send back what you read. Everything is applied as the equivalent single-step changes, in one transaction: all or nothing, with every problem answered at once. Map code is never rewritten: a Map step's code reads each input by a key that ends in the last four characters of that step's id, in capitals (input['<key>']), so a Map step that reads a step created in the same call is added with its inputs and no code (it is saved, and shows as not set up yet), and its code is set in a follow-up Update Workflow Step Configuration with the key the answer's inputKeys gives. The answer is the definition as written, refs (the id each ref got), inputKeys and issues (Validate Workflow's check). Send the revision you last read in If-Match; the response's meta.revision is the new one. Paging an app step that reads a list: Unset or null, paging is off: the step makes one request for the first page only, at the action's default page size (Get Workflow Step Schema's size.default: the app's default, 25 when it sets none), so a list longer than one page is cut short. To read more, set pagination: mode all reads every page of an action that can ask for later pages; an action that pages by size only takes mode single (Get Workflow Step Schema lists the modes an action takes), so raise its size, up to size.max.

PUT

Path

Path parameters
stringrequired

The workflow's id.

Headers

Optional headers
stringrequired

Required. The revision you last read: the revision from its read (Get Workflow Definition for a workflow, Get Analytics Page Definition for an Analytics page, Get Analytics Data Source Table for a fixed source's table), or meta.revision from your last change to it. The ETag header of either answer is the same value, ready to send back. The change applies only if nobody changed it since: otherwise it answers 412 with the current revision in error.details.revision. Send it as a strong entity tag ("r_..."): a weak one (W/"...") never matches and answers 412. Without it the request answers 428.

string

Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. A key can also act in its child organizations, and, with "Use this key across all of your organizations" on, in every organization its creator can open in the app. List them with GET /v2/companies. Every response's X-Company-Id header names the organization it acted in. See Organizations.

Body

Arguments
array of objectrequired

Every trigger, as you want it.

Every trigger the draft should have: { id } for one it has, { ref, app, action? } for a new one, each with name, isDisabled and configuration as you want them. A trigger left out is removed.

array of objectrequired

Every step, as a tree.

Every step the draft should have, as a tree in execution order: { id } for one it has, { ref, app, action? } for a new one, each with name, isDisabled and configuration, holding its steps in body (a loop, folder or batch step) or then and else (an If/Else). A step left out is removed with the steps it holds.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored unless it names another workflow. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

boolean

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

array of string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

number

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

string

Read-only: Get Workflow Definition answers it, and it is accepted so a read can be sent back, then ignored. Change the workflow itself with Update Workflow.

Read-only: change the workflow itself with Update Workflow.

Response fields

idstring

The workflow's id.

namestring

The workflow's name.

typestring

workflow, or function for a workflow other workflows call.

isActiveboolean

Whether the published version runs on its triggers.

environmentIdstring

The environment the workflow runs in. Null for the default environment.

tagsarray of string

Ids of the tags on the workflow.

versionstring

The version this answer describes: draft, or the saved version label.

publishedVersionstring

The version that runs. Null when the workflow was never published.

changesSincePublishnumber

How many draft edits are not published yet.

revisionstring

The draft's revision: send it in If-Match on your next change to the draft. The response's ETag header is the same value. Null when reading a saved version, which never changes.

triggersarray of objects

What starts the workflow. A workflow can have several.

  • idstring

    The trigger's id.

  • namestring

    The trigger's display name.

  • appSlugstring

    What starts the workflow: schedule, webhook, runWorkflow (when another workflow calls it), or the app whose event does.

  • appVersionstring

    The app version the trigger is pinned to. For a built-in trigger (Schedule, Webhook, When called), the version of the built-in app it was added with, "0" or "0.0.1" (some older ones hold "draft" or null); it does not change what the trigger does.

  • actionIdstring

    The app event the trigger listens for. Null for a built-in trigger.

  • isDisabledboolean

    True when the trigger is turned off.

  • isConfiguredboolean

    Whether the trigger passed the editor's validation. Null when it was never validated.

stepsarray of objects

The steps, top level first, in execution order. A step that holds others carries them in body (a loop, folder or batch step) or then and else (an If/Else).

  • idstring

    The step's id. Stable across edits; never positional.

  • numbernumber

    The number the editor shows for this step, in execution order. Null for a folder, which the editor does not number.

  • namestring

    The step's display name.

  • appSlugstring

    The app the step runs, or the built-in step type (iterate, ifElse, map, ...).

  • appVersionstring

    The app version the step is pinned to. For a built-in step (If, Loop, Map, ...), the version of the built-in app it was added with, "0" or "0.0.1" (some older ones hold "draft" or null); it does not change what the step does.

  • actionIdstring

    The app action the step runs. Null for a built-in step type.

  • functionIdstring

    The function this step calls, for a function call step.

  • parentStepIdstring

    The step this one sits inside (a loop, group, folder or if/else). Null at the top level.

  • slotstring

    Where the step sits in its parent: steps (the top level), body (a loop, group or folder), then or else (an if/else lane).

    • steps
    • body
    • then
    • else
  • depthnumber

    How deeply the step is nested. 0 at the top level.

  • isDisabledboolean

    True when the step is turned off and runs skip it.

  • isConfiguredboolean

    Whether the step passed the editor's validation (required values set, connection chosen). Null when it was never validated.

  • bodyarray

    Steps nested inside this one, in order. Present when it has any; each has the same keys.

  • thenarray

    Steps nested inside this one, in order. Present when it has any; each has the same keys.

  • elsearray

    Steps nested inside this one, in order. Present when it has any; each has the same keys.

refsobject

The id each new step and trigger got, by its ref.

inputKeysarray of objects

For each step this call created that a Map step reads: the name its code reads it by, input['<key>']. It ends in the last four characters of the new step's id, in capitals, so Map code that reads a step created in the same call is set in a follow-up Update Workflow Step Configuration with this key.

  • mapStepIdstring

    The Map step.

  • stepIdstring

    The new step it reads.

  • refstring

    The new step's ref in the body.

  • keystring

    The name the Map step's code reads it by: input['<key>'].

issuesarray of objects

Validate Workflow's check of the draft as written: what still stops publishing, and what is not set up yet. path points into this answer.

  • severitystring

    error blocks publishing; warning does not.

    • error
    • warning
  • codestring

    What is wrong, UPPER_SNAKE (SCHEDULE_INCOMPLETE, STEP_NOT_CONFIGURED, MISSING_GRAPH_REFERENCE, ...).

  • messagestring

    What is wrong, for a person.

  • stepIdstring

    The step or trigger it is about. Null for the workflow as a whole.

  • pathstring

    Where that step sits in Get Workflow Definition, as a JSON Pointer (/steps/1/body/0). Null for the workflow as a whole.