# 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..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['']), 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 https://connect.mindcloud.co/v2/workflows/:workflowId/definition` Permissions: `workflow:edit`. ## Parameters ### Path - `workflowId` (string, required): The workflow's id. ### Headers - `If-Match` (string, required): 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. - `X-Company-Id` (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](https://mindcloud.co/docs/api/rest/introduction/organizations). ### Body - `triggers` (array, required): 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. - `steps` (array, required): 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. - `id` (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. - `name` (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. - `type` (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. - `isActive` (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. - `environmentId` (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. - `tags` (array): 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. - `version` (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. - `publishedVersion` (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. - `changesSincePublish` (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. - `revision` (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. ## Example request ```bash curl --request PUT \ --url 'https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/definition' \ --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "triggers": [ { "ref": "hook", "app": "webhook" } ], "steps": [ { "ref": "users", "app": "slack", "action": "list-users" }, { "ref": "each", "app": "iterate", "configuration": { "arguments": { "source": "{{ steps.users.output }}" } }, "body": [ { "ref": "dm", "app": "slack", "action": "send-user-message" } ] } ], "id": "Wq3kZ8pLx2Nb", "name": "Sync new orders", "type": "workflow", "isActive": true, "environmentId": "null", "tags": [], "version": "draft", "publishedVersion": "0.0.3", "changesSincePublish": 2, "revision": "r_8a01ddd954aa23f1cc6776b32a2acccd" }' ``` ## Response fields - `id` (string): The workflow's id. - `name` (string): The workflow's name. - `type` (string): workflow, or function for a workflow other workflows call. - `isActive` (boolean): Whether the published version runs on its triggers. - `environmentId` (string): The environment the workflow runs in. Null for the default environment. - `tags` (array of string): Ids of the tags on the workflow. - `version` (string): The version this answer describes: draft, or the saved version label. - `publishedVersion` (string): The version that runs. Null when the workflow was never published. - `changesSincePublish` (number): How many draft edits are not published yet. - `revision` (string): 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. - `triggers` (array of objects): What starts the workflow. A workflow can have several. - `id` (string): The trigger's id. - `name` (string): The trigger's display name. - `appSlug` (string): What starts the workflow: schedule, webhook, runWorkflow (when another workflow calls it), or the app whose event does. - `appVersion` (string): 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. - `actionId` (string): The app event the trigger listens for. Null for a built-in trigger. - `isDisabled` (boolean): True when the trigger is turned off. - `isConfigured` (boolean): Whether the trigger passed the editor's validation. Null when it was never validated. - `steps` (array 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). - `id` (string): The step's id. Stable across edits; never positional. - `number` (number): The number the editor shows for this step, in execution order. Null for a folder, which the editor does not number. - `name` (string): The step's display name. - `appSlug` (string): The app the step runs, or the built-in step type (iterate, ifElse, map, ...). - `appVersion` (string): 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. - `actionId` (string): The app action the step runs. Null for a built-in step type. - `functionId` (string): The function this step calls, for a function call step. - `parentStepId` (string): The step this one sits inside (a loop, group, folder or if/else). Null at the top level. - `slot` (string): Where the step sits in its parent: steps (the top level), body (a loop, group or folder), then or else (an if/else lane). Allowed values: - `steps` - `body` - `then` - `else` - `depth` (number): How deeply the step is nested. 0 at the top level. - `isDisabled` (boolean): True when the step is turned off and runs skip it. - `isConfigured` (boolean): Whether the step passed the editor's validation (required values set, connection chosen). Null when it was never validated. - `body` (array): Steps nested inside this one, in order. Present when it has any; each has the same keys. - `then` (array): Steps nested inside this one, in order. Present when it has any; each has the same keys. - `else` (array): Steps nested inside this one, in order. Present when it has any; each has the same keys. - `refs` (object): The id each new step and trigger got, by its ref. - `inputKeys` (array of objects): For each step this call created that a Map step reads: the name its code reads it by, input['']. 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. - `mapStepId` (string): The Map step. - `stepId` (string): The new step it reads. - `ref` (string): The new step's ref in the body. - `key` (string): The name the Map step's code reads it by: input['']. - `issues` (array 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. - `severity` (string): error blocks publishing; warning does not. Allowed values: - `error` - `warning` - `code` (string): What is wrong, UPPER_SNAKE (SCHEDULE_INCOMPLETE, STEP_NOT_CONFIGURED, MISSING_GRAPH_REFERENCE, ...). - `message` (string): What is wrong, for a person. - `stepId` (string): The step or trigger it is about. Null for the workflow as a whole. - `path` (string): Where that step sits in Get Workflow Definition, as a JSON Pointer (/steps/1/body/0). Null for the workflow as a whole.