Create an Automation

This document explains how to create and verify a DocStudio Automation.

Before you begin

To create an automation, you need:

• an account ID

• a bearer token for API authorization

• at least two automation types for the workflow

• credentials for automation types that access external services

You can retrieve the currently available automation types and their configuration schemas using:

GET /api/v1/automation/account/{accountId}/brick-types

Use the returned configSchema for the selected type to determine which configuration fields it supports.

Workflow structure

An automation contains the following properties:

{
  "name": "Automation name",
  "active": true,
  "workflow": []
}

Field	Description
name	Automation name
active	Whether the automation is active
workflow	Workflow items performed by the automation

The workflow array contains the operations performed by the automation. A workflow must contain at least two items.

Each workflow item uses the following structure:

{
  "id": "uuid",
  "type": "automation-type",
  "description": "Description",
  "config": {},
  "credentialsId": "uuid",
  "next": []
}

Field	Description
id	UUID generated for the workflow item
type	Automation type, such as envelope-trigger
description	Optional description of the operation
config	Configuration for the selected automation type, defined by its configSchema
credentialsId	ID of stored credentials, included only when the selected type requires credentials
next	IDs of workflow items that receive this item's output

Use x and y to set an item's position on the workflow canvas. They do not affect execution.

Passing data between automation types

Automation types can expose named output parameters. Downstream workflow items receive them automatically when parameter names match.

For example, envelope-trigger provides:

envelope
mailbox

The envelope-label-assignee type requires envelope, mailbox, and label. When it follows envelope-trigger, the envelope and mailbox values are supplied automatically, so only label needs to be specified in its config.

Create an automation

The following example creates an automation that detects envelopes with the WAITING status and assigns the AutoProcessed label to them.

Get the available automation types

Send:

GET /api/v1/automation/account/{accountId}/brick-types

Find envelope-trigger and envelope-label-assignee in the response and use their configSchema definitions when configuring the workflow.

Build the workflow

Use the following payload:

{
  "name": "Catch envelopes in 'Waiting for you' status and assign a label to them",
  "active": true,
  "workflow": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "envelope-trigger",
      "description": "Catch envelopes in 'Waiting for you' status",
      "config": {
        "status": [
          "WAITING"
        ]
      },
      "next": [
        "22222222-2222-2222-2222-222222222222"
      ]
    },
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "type": "envelope-label-assignee",
      "description": "Assign label",
      "config": {
        "label": "AutoProcessed"
      },
      "next": []
    }
  ]
}

The next value in envelope-trigger contains the ID of envelope-label-assignee. This makes label assignment the next operation. The final operation uses an empty next array.

Create the automation

Send the workflow using:

POST /api/v1/automation/account/{accountId}

A successful request returns 201 Created with the automation ID:

{
  "id": "<automation-uuid>"
}

Trigger the automation

Perform the action that matches the configured trigger. For this example, an envelope must enter a status matched by the envelope-trigger configuration.

The example uses:

{
  "status": [
    "WAITING"
  ]
}

Supported envelope status values:

• DRAFT

• SENT

• WAITING

• COMPLETED

• CANCELLED

• EXPIRED

• ON_APPROVAL

When the trigger finds a matching envelope, the workflow continues to envelope-label-assignee. The first run creates the AutoProcessed label if it does not exist.

Verify the execution

Creating an automation successfully does not confirm that its workflow has executed successfully. After triggering it, retrieve the automation executions:

GET /api/v1/automation/account/{accountId}/executions

Find the corresponding execution and check its execution state.

A completed execution has state SUCCEED.

If the execution state is FAILED, retrieve its execution log:

GET /api/v1/automation/account/{accountId}/execution/{traceId}/log

The log identifies the failed workflow item and describes the error.

Related topics

• Automation types

• Automation Overview