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"
    }
    ...
  ]
}