Workflow Definitions

The /workflows/definitions endpoints allows you to manage your Workflow Defintions. Workflow definitions are used to define the steps that will be executed by a workflow. They are written in a DSL that is based on JSON.

Workflow DSL

The workflow DSL is a JSON-based language that is used to define workflows. It is a simple language that is easy to learn and use. The DSL is composed of a list of steps. Each step can be either an activity or a child workflow.

Activities

Activities are the building blocks of workflows. They are the individual tasks that are executed by the workflow worker. The following activities are available:

create_object: Creates a new content object.
update_object: Updates an existing content object.
delete_object: Deletes an existing content object.
generate_renditions: Generates renditions for a content object.
extract_text: Extracts text from a content object.
generate_embeddings: Generates embeddings for a content object.
execute_interaction: Executes an interaction.
wait: Waits for a specified amount of time.
http_request: Makes an HTTP request.
send_email: Sends an email.

Details about the Workflow Activity DSL are in the Workflow Activities section.

Example Workflow Definition

The following is an example of a workflow definition that generates renditions for a content object:

{
  "name": "Generate Renditions",
  "description": "Generates renditions for a content object",
  "tags": ["renditions", "images"],
  "steps": [
    {
      "type": "activity",
      "name": "generate_renditions",
      "params": {
        "objectId": "$.objectId",
        "formats": ["jpg", "png"]
      },
      "output": "renditions"
    },
    {
      "type": "activity",
      "name": "wait",
      "params": {
        "duration": "10s"
      }
    },
    {
      "type": "activity",
      "name": "update_object",
      "params": {
        "objectId": "$.objectId",
        "properties": {
          "renditions": "$.renditions"
        }
      }
    }
  ],
  "vars": {
    "objectId": "<OBJECT_ID>"
  }
}

Child Workflows

Child workflows are workflows that are executed as part of another workflow. They are useful for breaking down complex workflows into smaller, more manageable units.

Example Child Workflow

The following is an example of a child workflow defined using the DSLChildWorkflowStep interface which are steps[] in the DSL.

{
  "type": "workflow",
  "name": "dslWorkflow",
  "spec": {
    "name": "My Child Workflow",
    "description": "This is a child workflow.",
    "steps": [
      {
        "type": "activity",
        "name": "log",
        "params": {
          "message": "Hello from the child workflow!"
        }
      }
    ],
    "vars": {}
  },
  "output": "childWorkflowResult"
}

List Workflow Definitions

Endpoint: /workflows/definitions

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Example Request

There is no JSON body with this request.

Example Response

[
    {
        "id": "<WORKFLOW_DEFINITION_ID>",
        "name": "Generate Renditions",
        "description": "Generates renditions for a content object",
        "tags": [
            "renditions",
            "images"
        ],
        "created_at": "2023-04-20T12:00:00.000Z",
        "updated_at": "2023-04-20T12:00:00.000Z"
    }
]

Code Examples

List Workflow Definitions

curl --location --request GET 'https://studio-server-production.api.becomposable.com/api/v1/workflows/definitions' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create a Workflow Definition

Endpoint: /workflows/definitions

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
name	string	The name of the workflow definition.
description	string	The description of the workflow definition.
tags	string[]	The tags of the workflow definition.
steps	DSLWorkflowStep[]	The steps of the workflow definition.
vars	Record`<string, any>`	The variables of the workflow definition.
options	DSLActivityOptions	The options of the workflow definition.
result	string	The result of the workflow definition.
debug_mode	boolean	The debug mode of the workflow definition.

Example Request

{
  "name": "Generate Renditions",
  "description": "Generates renditions for a content object",
  "tags": ["renditions", "images"],
  "steps": [
    {
      "type": "activity",
      "name": "generate_renditions",
      "params": {
        "objectId": "$.objectId",
        "formats": ["jpg", "png"]
      },
      "output": "renditions"
    },
    {
      "type": "activity",
      "name": "wait",
      "params": {
        "duration": "10s"
      }
    },
    {
      "type": "activity",
      "name": "update_object",
      "params": {
        "objectId": "$.objectId",
        "properties": {
          "renditions": "$.renditions"
        }
      }
    }
  ],
  "vars": {
    "objectId": "<OBJECT_ID>"
  }
}

Example Response

{
    "id": "<WORKFLOW_DEFINITION_ID>",
    "name": "Generate Renditions",
    "description": "Generates renditions for a content object",
    "tags": [
        "renditions",
        "images"
    ],
    "created_at": "2023-04-20T12:00:00.000Z",
    "updated_at": "2023-04-20T12:00:00.000Z"
}

Code Examples

Create a Workflow Definition

curl --location --request POST 'https://studio-server-production.api.becomposable.com/api/v1/workflows/definitions' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Generate Renditions",
  "description": "Generates renditions for a content object",
  "tags": ["renditions", "images"],
  "steps": [
    {
      "type": "activity",
      "name": "generate_renditions",
      "params": {
        "objectId": "$.objectId",
        "formats": ["jpg", "png"]
      },
      "output": "renditions"
    },
    {
      "type": "activity",
      "name": "wait",
      "params": {
        "duration": "10s"
      }
    },
    {
      "type": "activity",
      "name": "update_object",
      "params": {
        "objectId": "$.objectId",
        "properties": {
          "renditions": "$.renditions"
        }
      }
    }
  ],
  "vars": {
    "objectId": "<OBJECT_ID>"
  }
}'

Retrieve a Workflow Definition

Endpoint: /workflows/definitions/<WORKFLOW_DEFINITION_ID>

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<WORKFLOW_DEFINITION_ID>`	The ID of the workflow definition to retrieve.

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<WORKFLOW_DEFINITION_ID>",
    "name": "Generate Renditions",
    "description": "Generates renditions for a content object",
    "tags": [
        "renditions",
        "images"
    ],
    "created_at": "2023-04-20T12:00:00.000Z",
    "updated_at": "2023-04-20T12:00:00.000Z"
}

Code Examples

Retrieve a Workflow Definition

curl --location --request GET 'https://studio-server-production.api.becomposable.com/api/v1/workflows/definitions/<WORKFLOW_DEFINITION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update a Workflow Definition

Endpoint: /workflows/definitions/<WORKFLOW_DEFINITION_ID>

Method: PUT

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<WORKFLOW_DEFINITION_ID>`	The ID of the workflow definition to update.

Input Parameters

Parameter	Data Type	Description
name	string	The name of the workflow definition.
description	string	The description of the workflow definition.
tags	string[]	The tags of the workflow definition.
steps	DSLWorkflowStep[]	The steps of the workflow definition.
vars	Record`<string, any>`	The variables of the workflow definition.
options	DSLActivityOptions	The options of the workflow definition.
result	string	The result of the workflow definition.
debug_mode	boolean	The debug mode of the workflow definition.

Example Request

{
  "name": "Generate Renditions (updated)",
  "description": "Generates renditions for a content object",
  "tags": ["renditions", "images"],
  "steps": [
    {
      "type": "activity",
      "name": "generate_renditions",
      "params": {
        "objectId": "$.objectId",
        "formats": ["jpg", "png", "webp"]
      },
      "output": "renditions"
    },
    {
      "type": "activity",
      "name": "wait",
      "params": {
        "duration": "10s"
      }
    },
    {
      "type": "activity",
      "name": "update_object",
      "params": {
        "objectId": "$.objectId",
        "properties": {
          "renditions": "$.renditions"
        }
      }
    }
  ],
  "vars": {
    "objectId": "<OBJECT_ID>"
  }
}

Example Response

{
    "id": "<WORKFLOW_DEFINITION_ID>",
    "name": "Generate Renditions (updated)",
    "description": "Generates renditions for a content object",
    "tags": [
        "renditions",
        "images"
    ],
    "created_at": "2023-04-20T12:00:00.000Z",
    "updated_at": "2023-04-20T12:00:01.000Z"
}

Code Examples

Update a Workflow Definition

curl --location --request PUT 'https://studio-server-production.api.becomposable.com/api/v1/workflows/definitions/<WORKFLOW_DEFINITION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Generate Renditions (updated)",
  "description": "Generates renditions for a content object",
  "tags": ["renditions", "images"],
  "steps": [
    {
      "type": "activity",
      "name": "generate_renditions",
      "params": {
        "objectId": "$.objectId",
        "formats": ["jpg", "png", "webp"]
      },
      "output": "renditions"
    },
    {
      "type": "activity",
      "name": "wait",
      "params": {
        "duration": "10s"
      }
    },
    {
      "type": "activity",
      "name": "update_object",
      "params": {
        "objectId": "$.objectId",
        "properties": {
          "renditions": "$.renditions"
        }
      }
    }
  ],
  "vars": {
    "objectId": "<OBJECT_ID>"
  }
}'

Delete a Workflow Definition

Endpoint: /workflows/definitions/<WORKFLOW_DEFINITION_ID>

Method: DELETE

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<WORKFLOW_DEFINITION_ID>`	The ID of the workflow definition to delete.

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<WORKFLOW_DEFINITION_ID>"
}

Code Examples

Delete a Workflow Definition

curl --location --request DELETE 'https://studio-server-production.api.becomposable.com/api/v1/workflows/definitions/<WORKFLOW_DEFINITION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'