Opencast

Workflow Service REST Documentation

/workflow
This service lists available workflows and starts, stops, suspends and resumes workflow instances.

General Notes

Table of Contents

Read methods

Method / Path: GET /configurationPanel
Description: Get the configuration panel for a specific workflow
Path params: NONE
Optional (query) params: definitionId: The workflow definition identifier
Response formats: text/html
Status codes: 200: OK, The workflow configuration panel.
Notes:
  • Return value description: The HTML workflow configuration panel
Testing:
Sample: /configurationPanel?definitionId={definitionId}
Testing form (click to reveal)
Method / Path: GET /count
Description: Returns the number of workflow instances in a specific state
Path params: NONE
Optional (query) params: state: The workflow state
Response formats: text/plain
Status codes: 200: OK, The number of workflow instances.
Notes:
  • Return value description: Returns the number of workflow instances in a specific state
Testing:
Sample: /count?state={state}
Testing form (click to reveal)
Method / Path: GET /mediaPackage/{id}/currentInstance.json
Description: Returns the current workflow for a media package
Path params: id: The media package identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, Returns the workflows for a media package.
404: Not Found, Current workflow not found.
Notes:
  • Return value description: Returns the currentworkflow that are associated with the media package as JSON.
Testing:
Sample: /mediaPackage/{id}/currentInstance.json
Testing form (click to reveal)
Method / Path: GET /definition/{id}.json
Description: Returns a single workflow definition
Path params: id: The workflow definition identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, The workflow definition.
404: Not Found, Workflow definition not found.
Notes:
  • Return value description: Returns a JSON representation of the workflow definition with the specified identifier
Testing:
Sample: /definition/{id}.json
Testing form (click to reveal)
Method / Path: GET /definition/{id}.xml
Description: Returns a single workflow definition
Path params: id: The workflow definition identifier
Optional (query) params: NONE
Response formats: text/xml
Status codes: 200: OK, The workflow definition.
404: Not Found, Workflow definition not found.
Notes:
  • Return value description: Returns an XML representation of the workflow definition with the specified identifier
Testing:
Sample: /definition/{id}.xml
Testing form (click to reveal)
Method / Path: GET /definitions.json
Description: List all available workflow definitions as JSON
Path params: NONE
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, The workflow definitions.
Returned Entity Schema:
Click to view
Notes:
  • Return value description: Returns the workflow definitions as JSON
Testing:
Sample: /definitions.json
/workflow/definitions.json
Method / Path: GET /definitions.xml
Description: List all available workflow definitions as XML
Path params: NONE
Optional (query) params: NONE
Response formats: application/xml
Status codes: 200: OK, The workflow definitions.
Returned Entity Schema:
Click to view
Notes:
  • Return value description: Returns the workflow definitions as XML
Testing:
Sample: /definitions.xml
/workflow/definitions.xml
Method / Path: GET /handlers.json
Description: List all registered workflow operation handlers (implementations).
Path params: NONE
Optional (query) params: NONE
Status codes: 200: OK, A JSON representation of the registered workflow operation handlers
Notes:
  • Return value description: A JSON representation of the registered workflow operation handlers.
Testing:
Sample: /handlers.json
/workflow/handlers.json
Method / Path: GET /mediaPackage/{id}/hasActiveWorkflows
Description: Returns if a media package has active workflows
Path params: id: The media package identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, Whether the media package has active workflows.
Notes:
  • Return value description: Returns wether the media package has active workflows as a boolean.
Testing:
Sample: /mediaPackage/{id}/hasActiveWorkflows
Testing form (click to reveal)
Method / Path: GET /statemappings.json
Description: Get all workflow state mappings
Path params: NONE
Optional (query) params: NONE
Status codes: 200: OK, A JSON representation of the workflow state mappings
Notes:
  • Return value description: A JSON representation of the workflow state mappings.
Testing:
Sample: /statemappings.json
/workflow/statemappings.json
Method / Path: GET /user/{id}/hasActiveWorkflows
Description: Returns if there are currently workflow(s) running thatwere started by the given user
Path params: id: The user identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, Whether there are active workflow for the user.
Notes:
  • Return value description: Returns if there are currently workflow(s) running that were started by the given user as a boolean.
Testing:
Sample: /user/{id}/hasActiveWorkflows
Testing form (click to reveal)
Method / Path: GET /instance/{id}.json
Description: Get a specific workflow instance.
Path params: id: The workflow instance identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, A JSON representation of the workflow instance.
404: Not Found, No workflow instance with that identifier exists.
Returned Entity Schema:
Click to view
Notes:
  • Return value description: A JSON representation of a workflow instance
Testing:
Sample: /instance/{id}.json
Testing form (click to reveal)
Method / Path: GET /instance/{id}.xml
Description: Get a specific workflow instance.
Path params: id: The workflow instance identifier
Optional (query) params: NONE
Response formats: text/xml
Status codes: 200: OK, An XML representation of the workflow instance.
404: Not Found, No workflow instance with that identifier exists.
Returned Entity Schema:
Click to view
Notes:
  • Return value description: An XML representation of a workflow instance
Testing:
Sample: /instance/{id}.xml
Testing form (click to reveal)
Method / Path: GET /mediaPackage/{id}/instances.json
Description: Returns the workflows for a media package
Path params: id: The media package identifier
Optional (query) params: NONE
Response formats: application/json
Status codes: 200: OK, Returns the workflows for a media package.
Notes:
  • Return value description: Returns the workflows that are associated with the media package as JSON.
Testing:
Sample: /mediaPackage/{id}/instances.json
Testing form (click to reveal)

Write methods

Method / Path: DELETE /remove/{id}
Description: Danger! Permenantly removes a workflow instance including all its child jobs. In most circumstances, /stop is what you should use.
Path params: id: The workflow instance identifier
Optional (query) params: force(Default value=false): If the workflow status should be ignored and the workflow removed anyway
Response formats: text/plain
Status codes: 204: No Content, If workflow instance could be removed successfully, no content is returned
404: Not Found, No workflow instance with that identifier exists.
403: Forbidden, It's not allowed to remove other workflow instance statues than STOPPED, SUCCEEDED and FAILED (use force parameter to override AT YOUR OWN RISK).
Notes:
  • Return value description: HTTP 204 No Content
Testing:
Sample: /remove/{id}
Testing form (click to reveal)
Method / Path: POST /replaceAndresume
Description: Replaces a suspended workflow instance with an updated version, and resumes the workflow.
Path params: NONE
Required (form) params: id: The workflow instance identifier
Optional (form) params: mediapackage: The new Mediapackage
properties: Properties
Response formats: text/xml
Status codes: 200: OK, An XML representation of the updated and resumed workflow instance.
409: Conflict, Can not resume workflow not in paused state
404: Not Found, No suspended workflow instance with that identifier exists.
401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate.
Notes:
  • Return value description: An XML representation of the updated and resumed workflow instance
Testing:
Sample: /replaceAndresume
Testing form (click to reveal)
Method / Path: POST /resume
Description: Resumes a suspended workflow instance.
Path params: NONE
Required (form) params: id: The workflow instance identifier
Optional (form) params: NONE
Response formats: text/xml
Status codes: 200: OK, An XML representation of the resumed workflow instance.
409: Conflict, Can not resume workflow not in paused state
404: Not Found, No suspended workflow instance with that identifier exists.
401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate.
Notes:
  • Return value description: An XML representation of the resumed workflow instance
Testing:
Sample: /resume
Testing form (click to reveal)
Method / Path: POST /start
Description: Start a new workflow instance.
Path params: NONE
Required (form) params: definition: The workflow definition ID or an XML representation of a workflow definition
XML Schema

mediapackage: The XML representation of a mediapackage
XML Schema
Optional (form) params: parent: An optional parent workflow instance identifier
properties: An optional set of key=value\n properties
Response formats: text/xml
Status codes: 200: OK, An XML representation of the new workflow instance.
401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate.
404: Not Found, If the parent workflow does not exist
Returned Entity Schema:
Click to view
Notes:
  • Return value description: An XML representation of the new workflow instance
Testing:
Sample: /start
Testing form (click to reveal)
Method / Path: POST /stop
Description: Stops a workflow instance.
Path params: NONE
Required (form) params: id: The workflow instance identifier
Optional (form) params: NONE
Response formats: text/xml
Status codes: 200: OK, An XML representation of the stopped workflow instance.
404: Not Found, No running workflow instance with that identifier exists.
Returned Entity Schema:
Click to view
Notes:
  • Return value description: An XML representation of the stopped workflow instance
Testing:
Sample: /stop
Testing form (click to reveal)
Method / Path: POST /suspend
Description: Suspends a workflow instance.
Path params: NONE
Required (form) params: id: The workflow instance identifier
Optional (form) params: NONE
Response formats: text/xml
Status codes: 200: OK, An XML representation of the suspended workflow instance.
404: Not Found, No running workflow instance with that identifier exists.
Notes:
  • Return value description: An XML representation of the suspended workflow instance
Testing:
Sample: /suspend
Testing form (click to reveal)
Method / Path: POST /update
Description: Updates a workflow instance.
Path params: NONE
Required (form) params: workflow: The XML representation of the workflow instance.
Optional (form) params: NONE
Status codes: 204: No Content, Workflow instance updated.
Notes:
  • Return value description: No content.
Testing:
Sample: /update
Testing form (click to reveal)