Workflow¶
Endpoints
GET /workflows
GET /workflows/:id
POST /workflows
POST /workflows/partial
POST /workflows/:link_uid/link_uid
PUT /workflows/:id
PUT /workflows/:id/partial
POST /workflows/:id/run
DELETE /workflows/:id
DELETE /workflows
A workflow is a collection of digital workers linked together to perform tasks in an automated fashion. Workflows can incorporate portfolios, datastores, report templates, API, and email distributions, as well as standard and custom digital workers.
The workflow object¶
What a workflow object looks like?
{
"version": "v1",
"status": "OK",
"updated": 1624633670,
"description": "This is my first workflow.",
"tags": ["first", "new", "workflow"],
"trigger_enabled": true,
"gui": {
"offset_x": 0,
"zoom": 75,
"offset_y": 0
},
"created": 1624633670,
"starter_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
"ender_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
"link_uid": null,
"workspace": "main",
"trigger_type": "MANUAL",
"trigger_config": {},
"id": "wrkf_8fRueOt4JlXV9k5o9HZDMWfw7",
"name": "My First Workflow"
}
| Property | Description |
|---|---|
id string |
Unique identifier (UID) for the workflow. |
created timestamp |
Time at which the object was created. Measured in seconds since the Unix epoch. |
updated timestamp |
Time at which the object was updated. Measured in seconds since the Unix epoch. |
name string |
The workflow's name. |
description string |
An arbitrary string attached to the workflow. Default is "". |
tags array |
A list of strings. Up to 32 tags. Use them to find the workflow with a query. |
version string |
Indicates the workflow's current version. |
status string |
OK when every worker is complete. INCOMPLETE when a worker has missing inputs or errors. |
trigger_type string |
The type of the workflow's trigger. It can be MANUAL, API, SCHEDULER_EVENT, INTEGRATION_EVENT or WORKER_FINISHED_EVENT. |
trigger_config object |
Parameters used to activate the workflow's trigger. |
trigger_enabled boolean |
Whether the trigger can start the workflow. |
starter_worker_id string |
The id of the workflow's Starter worker. |
ender_worker_id string |
The id of the workflow's Ender worker. |
gui object |
The position and zoom of the workflow canvas in the editor. |
link_uid string |
An identifier you set to link the workflow to an external system. Default is null. |
workspace string |
The workspace where the workflow was generated. |
workers array |
The workers of the workflow. Only included when with_workers is True. |
List all workflows¶
To list all workflows, run the following:
The above call returns the following JSON object:
{
"workflows": [
{
"status": "OK",
"updated": 1624633670,
"description": "This is my first workflow.",
"tags": [
"first",
"new",
"workflow"
],
"trigger_enabled": true,
"gui": {
"offset_x": 0,
"zoom": 75,
"offset_y": 0
},
"created": 1624633670,
"starter_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
"workspace": "main",
"trigger_type": "MANUAL",
"trigger_config": {},
"id": "wrkf_8fRueOt4JlXV9k5o9HZDMWfw7",
"name": "My First Workflow"
},
...
],
"next_page_token": null
}
Returns a list of workflows you’ve previously created. The workflows are returned in sorted order, with the most recent workflow appearing first.
HTTP Request
GET /workflows
HTTP Parameters
| Parameter | Description |
|---|---|
query string |
optional, default is null Request a list of workflows filtering it by name or tag. When using a tag to perform a query, each term must include a hashtag prefix. (e.g: query="#april #sample") |
workspace string |
optional, default is main The workspace to list. |
page_size integer |
optional, default is 10 Set the number of objects that will be listed per page. |
page_token string |
optional, default is null The next_page_token from the previous response. See the pagination guide. |
with_workers boolean |
optional, default is False When True, each workflow in the list includes its workers. |
Retrieve a workflow¶
Retrieves the details of an existing workflow by supplying the workflow's id.
To retrieve a workflow, run the following:
The above call returns the following JSON object:
{
"workflow": {
"status": "OK",
"updated": 1624309266,
"description": "This is my first workflow.",
"tags": [
"first",
"new",
"workflow"
],
"trigger_enabled": true,
"workers": [
...
],
"created": 1624309074,
"starter_worker_id": "wrkr_jcQBp4Hj2MX3l9xsk8wgAByi7",
"workspace": "main",
"id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
"trigger_type": "MANUAL",
"trigger_config": {},
"gui": {
"offset_x": 0,
"zoom": 75,
"offset_y": 0
},
"name": "My First Workflow"
}
}
HTTP Request
GET /workflows/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a workflow. A workflow's id will always look like this: wrkf_uylMWijKauV4B4Te7UJg9cNIv. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
with_workers boolean |
optional, default is True When True, the response includes the workers of the workflow. |
Create a workflow¶
Creates a workflow and then returns it. A workflow needs a workers array with one Starter and one Ender. The easiest way to build this array is to copy it from an existing workflow: retrieve the workflow with with_workers=true and send its workers back. The API gives each new worker a new wrkr_ id.
To copy the workers of an existing workflow into a new workflow, run the following:
workers=$(curl -s "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?with_workers=true" \
-H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.workflow.workers')
curl https://api.everysk.com/v2/workflows \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d "$(jq -n --argjson workers "$workers" '{
name: "My Second Workflow",
description: "A copy of my first workflow.",
tags: ["second", "workflow"],
workspace: "main",
workers: $workers
}')" \
-X POST
This example relies on jq to read and build the JSON.
The above call returns the following JSON object:
{
"workflow": {
"version": "v1",
"status": "OK",
"updated": 1624309074,
"description": "A copy of my first workflow.",
"tags": [
"second",
"workflow"
],
"trigger_enabled": true,
"workers": [
...
],
"created": 1624309074,
"starter_worker_id": "wrkr_jcQBp4Hj2MX3l9xsk8wgAByi7",
"ender_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
"link_uid": null,
"workspace": "main",
"id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
"trigger_type": "MANUAL",
"trigger_config": {},
"gui": {
"zoom": 100,
"offset_x": 0,
"offset_y": 0
},
"name": "My Second Workflow"
}
}
HTTP Request
POST /workflows
HTTP Parameters
| Parameter | Description |
|---|---|
name string |
REQUIRED The workflow's name. 1 to 200 characters. |
workers array |
REQUIRED The workers of the workflow. It must contain one worker with type STARTER and one with type ENDER. Each worker must have the keys id, type, name, description, gui (with form_sections), script_inputs, script_outputs, script_source, script_entry_point, trigger_type, trigger_config, trigger_enabled and template_id. Copy them from a workflow that you retrieve with with_workers=true. |
description string |
optional, default is "" An arbitrary string attached to the workflow. Up to 2000 characters. |
tags array |
optional, default is [] A list of strings. Up to 32 tags. |
trigger_type string |
optional, default is MANUAL The type of the workflow's trigger: MANUAL, API, SCHEDULER_EVENT or INTEGRATION_EVENT. |
trigger_config object |
optional, default is {} The trigger parameters. For SCHEDULER_EVENT, it must contain a valid cron expression in cron_expression. For INTEGRATION_EVENT, it must contain the integration id in integration_id.select.value. |
trigger_enabled boolean |
optional, default is True Whether the trigger can start the workflow. |
gui object |
optional, default is {"zoom": 100, "offset_x": 0, "offset_y": 0} The position and zoom of the workflow canvas in the editor. |
link_uid string |
optional, default is null An identifier you set to link the workflow to an external system. |
with_workers boolean |
optional, default is True When True, the response includes the workers of the workflow. |
workspace string |
optional, default is main The workspace where the API creates the workflow. Send it in the JSON body. |
Update a workflow¶
Replaces a workflow and then returns it. The update is not partial: send every field again. A field that you leave out goes back to its default value, the same as on create. This also applies to workspace: if you leave it out, the API moves the workflow to main. The easiest way to update a workflow is to retrieve it with with_workers=true, change the fields, and send the object back.
To rename a workflow and keep the rest of it, run the following:
workflow=$(curl -s "https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv?with_workers=true" \
-H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.workflow')
curl https://api.everysk.com/v2/workflows/wrkf_uylMWijKauV4B4Te7UJg9cNIv \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d "$(echo "$workflow" | jq '{
name: "My Renamed Workflow",
description, tags, gui, link_uid, workspace,
trigger_type, trigger_config, trigger_enabled,
starter_worker_id, workers
}')" \
-X PUT
The call returns the updated workflow, in the same format as create.
HTTP Request
PUT /workflows/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED The workflow's unique identifier. |
name string |
REQUIRED The workflow's name. 1 to 200 characters. |
starter_worker_id string |
REQUIRED The id of the workflow's Starter worker. |
workers array |
REQUIRED The workers of the workflow, in the same format as on create. A worker that keeps its id keeps its worker id. |
workspace string |
optional, default is main Moves the workflow to this workspace. If you leave it out, the API moves the workflow to main. To keep the workflow where it is, send its current workspace. |
| Others | description, tags, trigger_type, trigger_config, trigger_enabled, gui, link_uid and with_workers, with the same rules and defaults as on create. |
Create or update a workflow by link_uid¶
Creates or replaces the workflow that has a given link_uid. Use it to deploy the same workflow again and again from an external system. The API looks for the most recently updated workflow with this link_uid in workspace:
- If it finds none, it creates a workflow and responds with HTTP
201. - If it finds one, it replaces that workflow, the same as update, and responds with HTTP
200. The workflow keeps its id and its Starter worker id.
The body is the same as on create. If the body has a link_uid that is different from the one in the URL, the API returns 400.
HTTP Request
POST /workflows/:link_uid/link_uid
Create or update a workflow with partial workers¶
POST /workflows/partial and PUT /workflows/:id/partial take the same body as create and update. The difference is where each worker's script_source comes from:
- On
PUT /workflows/:id/partial, a worker that keeps itsidkeeps its stored script source. The API ignores thescript_sourcein the body, except for the Starter and for a worker namedWorkflow Outputs. - On
POST /workflows/partial, the API takes the script source from the worker template that has the same name as the worker, or else from the template in the worker'stemplate_id.
HTTP Request
POST /workflows/partial
PUT /workflows/:id/partial
Run a workflow¶
Runs a specific workflow through the api. On this example we are running a workflow that contains a File Generator worker.
By default, running a workflow is asynchronous. This endpoint responds with HTTP 202 Accepted: the request has been accepted and the workflow execution has been started/queued, but the workflow has not necessarily finished running yet. The response contains a workflow_execution object; keep its id. To wait for the result in the same request, send "synchronous": true (see Run a workflow and wait for the result).
Getting the result of an asynchronous run takes four steps:
- Run. Send this request. Keep
workflow_execution.id. - Wait. Poll Retrieve a workflow execution every
poll_intervalseconds (default2) untilrun_statusisSUCCEEDED,FAILEDorCANCELED. Stop with an error aftertimeoutseconds (default300). A workflow that stops before it finishes, or a failure in a worker that is not the Ender, leavesrun_statusatRUNNINGforever, so the timeout is mandatory. - Judge. Treat
run_status == SUCCEEDEDas the only success.FAILEDis a failure.CANCELEDis reserved and is also a failure. - Read. Fetch the Ender's worker execution with
with_result=true. The business output isworker_execution.result.
See Polling for a workflow execution's completion for the full loop.
To run a workflow, run the following:
curl https://api.everysk.com/v2/workflows/wrkf_P95OLO61oGM5NwFn3W4iMl7rs/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"parameters": {
"file": {
"name": "SimpleTextFile.txt",
"content_type": "text/plain",
"data": "SGVsbG8gV29ybGQ="
}
},
"workspace": "main"
}' \
-X POST
The above call returns the following JSON object:
{
"workflow_execution": {
"id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
"run_status": "RUNNING",
"workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
"workflow_name": "File Generator Workflow",
"trigger": "API",
"workspace": "main",
"started_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
"ender_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
"ender_worker_execution_id": null,
"created": 1632835285,
"updated": 1632835285,
"started": 1632835285,
"duration": null,
"real_execution_time": null,
"total_execution_time": null,
"resume": null
},
"result": null
}
HTTP Request
POST /workflows/:id/run
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED The workflow's unique identifier. |
parameters object |
optional, default is null Object sent to be used inside the workflow that will be started through the API. Usually this object contains information and data required by the workers inside the workflow in order to execute properly. If the workers inside the target workflow do not require external inputs, leave it out. In Python it must be used as kwargs. |
synchronous boolean |
optional, default is False When True, the API waits for the run to finish and responds with the result. See Run a workflow and wait for the result. |
workspace string |
optional The workspace of the workflow. Send it in the JSON body. If you send it and the workflow is in another workspace, the API returns 403. |
Run a workflow and wait for the result¶
Send "synchronous": true to keep the request open until the run finishes. The API starts the workflow, waits for the Ender, and responds with HTTP 200. You do not poll.
To run a workflow and wait for the result, run the following:
The above call returns the following JSON object:
{
"workflow_execution": {
"id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
"run_status": "SUCCEEDED",
"workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
"workflow_name": "File Generator Workflow",
"trigger": "API",
"workspace": "main",
"ender_worker_execution_id": "wkex_3bNhXpQrLo7TmK2sJfGvWe1cA",
...
},
"result": {
...
},
"run_status": "SUCCEEDED"
}
The response has three keys:
workflow_execution: the finished execution, withoutresume.result: theresultof the Ender's worker execution. A run that fails still returns what the Ender produced.run_status:SUCCEEDEDorFAILED. Treat onlySUCCEEDEDas success.
The API waits up to the platform execution timeout (60 minutes). If the run does not finish in that time, the API still responds with HTTP 200, but result is null and the response has no run_status. Then poll the execution with the workflow_execution.id.
Delete a workflow¶
Permanently deletes a workflow. It cannot be undone. Returns an object with the workflow's id, its name and an attribute specifying whether the workflow was successfully deleted or not.
To delete a workflow, run the following:
The above call returns the following JSON object:
{
"workflow": {
"deleted": true,
"id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
"name": "My First Workflow"
}
}
HTTP Request
DELETE /workflows/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED The workflow's unique identifier. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
Delete several workflows¶
To delete several workflows in one call, leave the id out of the path and send the ids in ids, separated by commas.
To delete several workflows, run the following:
The above call returns the following JSON object:
{
"workflows": [
{
"deleted": true,
"id": "wrkf_uylMWijKauV4B4Te7UJg9cNIv",
"name": "My First Workflow"
},
{
"deleted": true,
"id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
"name": "File Generator Workflow"
}
]
}
HTTP Request
DELETE /workflows
HTTP Parameters
| Parameter | Description |
|---|---|
ids string |
REQUIRED The ids of the workflows, separated by commas. An id that the API does not find gives null in the list. |
workspace string |
optional The workspace of the workflows. If you send it and a workflow is in another workspace, the API stops at that workflow and returns 403. The workflows before it in ids are already deleted. |