General

The Workflow API is available since API version 1.1.0.

Workflow instances

POST /api/workflows

Creates a workflow instance.

Form Parameters	Required	Type	Description
event_identifier	yes	string	The event identifier this workflow should run against
workflow_definition_identifier	yes	string	The identifier of the workflow definition to use
configuration	no	property	The optional configuration for this workflow

This request additionally supports the following query string parameters to include additional information directly in the response:

Query String Parameter	Type	Description
withoperations	boolean	Whether the workflow operations should be included in the response
withconfiguration	boolean	Whether the workflow configuration should be included in the response

Example

event_identifier:

f41e4417-b841-4d20-a466-f98ddfbe4c2a

workflow_definition_identifier:

fast

configuration:

{
  "publishLive": "false",
  "uploadedSearchPreview": "false",
  "publishToOaiPmh": "true",
  "comment": "false",
  "publishToMediaModule": "true"
}

Response

201 (CREATED): A new workflow is created and its identifier is returned in the Location header.

Location: http://api.opencast.org/api/workflows/3170

The workflow instance is returned as JSON object with the following fields:

Field	Type	Description
identifier	string	The unique identifier of this workflow instance
title	string	The title of this workflow instance
description	string	The description of this workflow instance
tags	array[string]	The (potentially empty) list of workflow tags of this workflow instance
configuration_panel	string	The configuration panel of this workflow instance
operations	array[operation_instance]	The list of operations of this workflow instance

400 (BAD REQUEST): The request is invalid or inconsistent.
404 (NOT FOUND): The specified workflow instance does not exist.

GET /api/workflows/{workflow_instance_id}

Returns a single workflow instance.

This request supports the following query string parameters to include additional information directly in the response:

Query String Parameter	Type	Description
withoperations	boolean	Whether the workflow operations should be included in the response
withconfiguration	boolean	Whether the workflow configuration should be included in the response

Response

200 (OK): The workflow instance is returned as JSON object with the following fields:

Field	Type	Description
identifier	string	The unique identifier of this workflow instance
title	string	The title of this workflow instance
description	string	The description of this workflow instance
tags	array[string]	The (potentially empty) list of workflow tags of this workflow instance
configuration_panel	string	The configuration panel of this workflow instance
operations	array[operation_instance]	The list of operations of this workflow instance

403 (FORBIDDEN): The user doesn't have the rights to make this request.
404 (NOT FOUND): The event or workflow definition could not be found.

Example

{
  "workflow_definition_identifier": "fast",
  "identifier": 1603,
  "creator": "Opencast Project Administrator",
  "operations": [
    {
      "identifier": 1604,
      "completion": "2018-08-08T08:46:57.3Z",
      "configuration": {
        "publishLive": "false",
        "uploadedSearchPreview": "false",
        "publishToOaiPmh": "true",
        "comment": "false",
        "publishToMediaModule": "true"
      },
      "time_in_queue": 0,
      "failed_attempts": 0,
      "start": "2018-08-08T08:46:57.201Z",
      "description": "Applying default configuration values",
      "fail_workflow_on_error": true,
      "unless": "",
      "max_attempts": 1,
      "host": "http:\/\/localhost:8080",
      "state": "succeeded",
      "operation": "defaults",
      "if": "",
      "retry_strategy": "none",
      "error_handler_workflow": ""
    },
    {
      "identifier": 1605,
      "completion": "",
      "configuration": {
        "apply-acl": "true"
      },
      "time_in_queue": 0,
      "failed_attempts": 0,
      "start": "2018-08-08T08:47:02.209Z",
      "description": "Applying access control entries from series",
      "fail_workflow_on_error": true,
      "unless": "",
      "max_attempts": 1,
      "host": "http:\/\/localhost:8080",
      "state": "skipped",
      "operation": "series",
      "if": "",
      "retry_strategy": "none",
      "error_handler_workflow": "partial-error"
    }
    ...
  ],
  "configuration": {
    "publishLive": "false",
    "workflowDefinitionId": "fast",
    "uploadedSearchPreview": "false",
    "publishToOaiPmh": "true",
    "comment": "false",
    "publishToMediaModule": "true"
  },
  "description": "\n    A minimal workflow that transcodes the media into distribution formats, then\n    sends the resulting distribution files, along with their associated metadata,\n    to the distribution channels.\n  ",
  "state": "running",
  "title": "Fast Testing Workflow",
  "event_identifier": "f41e4417-b841-4d20-a466-f98ddfbe4c2a"
}

PUT /api/workflows/{workflow_instance_id}

Updates a workflow instance.

Form Parameters	Required	Type	Description
state	no	workflow_state	The optional state transition for this workflow
configuration	no	property	The optional configuration for this workflow

This request additionally supports the following query string parameters to include additional information directly in the response:

Query String Parameter	Type	Description
withoperations	boolean	Whether the workflow operations should be included in the response
withconfiguration	boolean	Whether the workflow configuration should be included in the response

Example

state:

paused

configuration:

{
  "publishLive": "false",
  "uploadedSearchPreview": "false",
  "publishToOaiPmh": "true",
  "comment": "false",
  "publishToMediaModule": "true"
}

Allowed workflow state transitions

The following workflow state transitions are allowed:

Current state	Allowed new state
instantiated	paused, stopped, running
running	paused, stopped
failing	paused, stopped
paused	paused, stopped, running
succeeded	paused, stopped
stopped	paused, stopped
failed	paused, stopped

Response

200 (OK): The workflow instance is updated and returned as JSON object with the following fields:

Field	Type	Description
identifier	string	The unique identifier of this workflow instance
title	string	The title of this workflow instance
description	string	The description of this workflow instance
tags	array[string]	The (potentially empty) list of workflow tags of this workflow instance
configuration_panel	string	The configuration panel of this workflow instance
operations	array[operation_instance]	The list of operations of this workflow instance

400 (BAD REQUEST): The request is invalid or inconsistent.
403 (FORBIDDEN): The user doesn't have the rights to make this request.
404 (NOT FOUND): The workflow instance could not be found.
409 (CONFLICT): The workflow instance cannot transition to this state.

DELETE /api/workflows/{workflow_instance_id}

Deletes a workflow instance.

Response

204 (NO CONTENT): The workflow instance has been deleted.
403 (FORBIDDEN): The user doesn't have the rights to make this request.
404 (NOT FOUND): The specified workflow instance does not exist.
409 (CONFLICT): The workflow instance cannot be deleted in this state.

Workflow definitions

GET /api/workflow-definitions

Returns a list of workflow definitions.

The following query string parameters are supported to filter, sort and pagingate the returned list:

Query String Parameter	Type	Description
filter	string	A comma-separated list of filters to limit the results with (see Filtering). See the below table for the list of available filters
sort	string	A comma-separated list of sort criteria (see Sorting). See the below table for the list of available sort criteria
limit	integer	The maximum number of results to return (see Pagination)
offset	integer	The index of the first result to return (see Pagination)

The following filters are available:

Filter Name	Description
tag	Workflow definitions where the tag is included

The list can be sorted by the following criteria:

Sort Criteria	Description
identifier	By the identifier of the workflow definition
title	By the title of the workflow definition
displayorder	By the display order of the workflow definition

This request additionally supports the following query string parameters to include additional information directly in the response:

Query String Parameter	Type	Description
withoperations	boolean	Whether the workflow operations should be included in the response
withconfigurationpanel	boolean	Whether the workflow configuration panel should be included in the response

Sample request

https://opencast.example.org/api/workflow-definitions?sort=title:DESC&limit=5&offset=1&filter=tag:archive

Response

200 (OK): A (potentially empty) list of workflow definitions is returned. The list is represented as JSON array where each element is a JSON object with the following fields:

Field	Type	Description
identifier	string	The unique identifier of this workflow definition
title	string	The title of this workflow definition
description	string	The description of this workflow definition
tags	array[string]	The (potentially empty) list of workflow tags of this workflow definition
configuration_panel	string	The configuration panel of this workflow definition
operations	array[operation_definition]	The list of operations of this workflow definition

400 (BAD REQUEST): The request is invalid or inconsistent.

Example

[
  {
    "id": "fast",
    "title": "Fast Testing Workflow",
    "description": "\n    A minimal workflow that transcodes the media into distribution formats, then\n    sends the resulting distribution files, along with their associated metadata,\n    to the distribution channels.\n  ",
    "tags": [
      "schedule",
      "upload"
    ],
    "configuration_panel": "\n    \n      <div id=\"workflow-configuration\">\n        <fieldset>\n          <legend>Add a comment that the recording needs:</legend>\n          <ul>\n            <li>\n              <input id=\"comment\" name=\"comment\" type=\"checkbox\" class=\"configField\" value=\"true\" />\n              <label for=\"comment\">Review / Cutting</label>\n            </li>\n          </ul>\n        </fieldset>\n        <fieldset>\n          <legend>Immediately distribute the recording to:</legend>\n          <ul>\n            <li>\n              <input id=\"publishToMediaModule\" name=\"publishToMediaModule\" type=\"checkbox\" class=\"configField\" value=\"true\" checked=checked />\n              <label for=\"publishToMediaModule\">Opencast Media Module</label>\n            </li>\n            <li>\n              <input id=\"publishToOaiPmh\" name=\"publishToOaiPmh\" type=\"checkbox\" class=\"configField\" value=\"true\" checked=checked />\n              <label for=\"publishToOaiPmh\">Default OAI-PMH Repository</label>\n            </li>\n          </ul>\n        </fieldset>\n        <fieldset>\n          <legend>Publish live stream:</legend>\n          <ul>\n            <li>\n              <input id=\"publishLive\" name=\"publishLive\" type=\"checkbox\" class=\"configField\" value=\"false\" />\n              <label for=\"publishLive\">Add live event to Opencast Media Module</label>\n            </li>\n          </ul>\n        </fieldset>\n      </div>\n    \n  ",
    "operations": [
      {
        "id": "defaults",
        "description": "Applying default configuration values",
        "configuration": {
          "publishLive": "false",
          "publishToOaiPmh": "true",
          "comment": "false",
          "publishToMediaModule": "true",
          "uploadedSearchPreview": "false"
        },
        "unless": "",
        "if": "",
        "fail_workflow_on_error": "true",
        "error_handler_workflow": "",
        "retry_strategy": "none",
        "max_attempts": "1"
      },
      {
        "id": "series",
        "description": "Applying access control entries from series",
        "configuration": {
          "apply-acl": "true"
        },
        "unless": "",
        "if": "",
        "fail_workflow_on_error": "true",
        "error_handler_workflow": "partial_error",
        "retry_strategy": "none",
        "max_attempts": "1"
      }
      ...
    ]
  }
]

GET /api/workflow-definitions/{workflow_definition_id}

Returns a single workflow definition.

This request supports the following query string parameters to include additional information directly in the response:

Query String Parameter	Type	Description
withoperations	boolean	Whether the workflow operations should be included in the response
withconfigurationpanel	boolean	Whether the workflow configuration panel should be included in the response

Response

200 (OK): The workflow definition is returned as JSON object with the following fields:

Field	Type	Description
identifier	string	The unique identifier of this workflow definition
title	string	The title of this workflow definition
description	string	The description of this workflow definition
tags	array[string]	The (potentially empty) list of workflow tags of this workflow definition
configuration_panel	string	The configuration panel of this workflow definition
operations	array[operation_definition]	The list of operations of this workflow definition

404 (NOT FOUND): The specified workflow definition does not exist.

Example

{
  "id": "fast",
  "title": "Fast Testing Workflow",
  "description": "\n    A minimal workflow that transcodes the media into distribution formats, then\n    sends the resulting distribution files, along with their associated metadata,\n    to the distribution channels.\n  ",
  "tags": [
    "schedule",
    "upload"
  ],
  "configuration_panel": "\n    \n      <div id=\"workflow-configuration\">\n        <fieldset>\n          <legend>Add a comment that the recording needs:</legend>\n          <ul>\n            <li>\n              <input id=\"comment\" name=\"comment\" type=\"checkbox\" class=\"configField\" value=\"true\" />\n              <label for=\"comment\">Review / Cutting</label>\n            </li>\n          </ul>\n        </fieldset>\n        <fieldset>\n          <legend>Immediately distribute the recording to:</legend>\n          <ul>\n            <li>\n              <input id=\"publishToMediaModule\" name=\"publishToMediaModule\" type=\"checkbox\" class=\"configField\" value=\"true\" checked=checked />\n              <label for=\"publishToMediaModule\">Opencast Media Module</label>\n            </li>\n            <li>\n              <input id=\"publishToOaiPmh\" name=\"publishToOaiPmh\" type=\"checkbox\" class=\"configField\" value=\"true\" checked=checked />\n              <label for=\"publishToOaiPmh\">Default OAI-PMH Repository</label>\n            </li>\n          </ul>\n        </fieldset>\n        <fieldset>\n          <legend>Publish live stream:</legend>\n          <ul>\n            <li>\n              <input id=\"publishLive\" name=\"publishLive\" type=\"checkbox\" class=\"configField\" value=\"false\" />\n              <label for=\"publishLive\">Add live event to Opencast Media Module</label>\n            </li>\n          </ul>\n        </fieldset>\n      </div>\n    \n  ",
  "operations": [
    {
      "id": "defaults",
      "description": "Applying default configuration values",
      "configuration": {
        "publishLive": "false",
        "publishToOaiPmh": "true",
        "comment": "false",
        "publishToMediaModule": "true",
        "uploadedSearchPreview": "false"
      },
      "unless": "",
      "if": "",
      "fail_workflow_on_error": "true",
      "error_handler_workflow": "",
      "retry_strategy": "none",
      "max_attempts": "1"
    },
    {
      "id": "series",
      "description": "Applying access control entries from series",
      "configuration": {
        "apply-acl": "true"
      },
      "unless": "",
      "if": "",
      "fail_workflow_on_error": "true",
      "error_handler_workflow": "partial_error",
      "retry_strategy": "none",
      "max_attempts": "1"
    }
    ...
  ]
}