Workflow REST API

Last Updated: Jan 28, 2021
documentation for the dotCMS Content Management System

The Workflow REST API allows you to create, modify, and execute Workflows and Workflow actions via standard REST API calls.

Common Operations

The most commonly used Workflow operations are to find which Workflow Actions are available to a specific content item or Content Type, and to execute a Workflow action for a specific piece of content. The following endpoints perform the common operations.

EndpointMethodUsageDescription
findActionsByStepGET/steps/{Step id}/actionsReturns all Workflow Actions associated with the specified Workflow Step.
  • If the Step does not have any Actions, returns an empty list with status 200.
findAvailableActionsGET/contentlet/{Content Id}/actionsReturns the available Workflow Actions for the specified content item.
  • By default, Actions available will be displayed for Editing render mode.
  • To return Actions for the Listing render mode, add ?renderMode=listing to the URL.
findInitialAvailable
ActionsByContentType
GET/initialactions/contenttype/{Content Type Id}Finds the available actions of the initial/first step(s) of the workflow scheme(s) associated with a content type Id.
fireActionPUT/actions/{actionId}/fireExecutes the specified Workflow Action.

In addition to the most common operations, you also may use the Workflow API to create, modify, and delete all parts of Workflows, including Workflow Schemes, Workflow Steps, and Workflow Actions. The following sections list all endpoints in the Workflow REST API.

Workflow Schemes

EndpointMethodUsageDescription
copySchemePOST/schemes/{Scheme Id}/copyCopies the specified Workflow Scheme to a new Scheme.
  • Performs a deep copy (including all Workflow Steps, Workflow Actions, and Permissions).
deleteSchemeDEL/schemes/{Scheme Id}Deletes an existing Workflow Scheme.
  • Note: The response is asynchronous.
exportSchemeGET/schemes/{Scheme Id}/exportExports the specified Workflow Scheme.
  • The Scheme is exported with all dependencies to rebuild it (including all Workflow Steps, Workflow Actions, and Permissions).
importSchemePOST/schemes/importImports a Workflow Scheme previously exported with exportScheme.
findAllSchemesAnd
SchemesByContentType
GET/schemes/schemescontenttypes/{Scheme Id}Returns all Workflow Schemes used by the specified Content Type.
  • Only non-Archived Workflow Schemes will be returned.
findSchemesGET/schemes/Returns all Workflow Schemes assigned to the specified Content Type.
  • Only non-Archived Workflow Schemes will be returned.
saveSchemePOST/schemesCreates a new Workflow Scheme.
Body: {"schemeName": "{Name}", "schemeDescription": "{Description}", "schemeArchived": "false"}
updateSchemePUT/schemes/{Scheme Id}Updates the specified existing Workflow Scheme.
Body: {"schemeName": "{Name}", "schemeDescription": "{Description}", "schemeArchived": "false"}

Workflow Steps

EndpointMethodUsageDescription
addStepPOST/stepCreates a new Step in the specified Workflow Scheme.

Please see below for the data to send in the body of the request.
deleteStepDEL/steps/{Step Id}Deletes the specified Workflow Step from its Workflow Scheme.
findStepByIdGET/steps/{Step Id}Returns the specified Workflow Step.
findStepsBySchemeGET/workflow/schemes/{Scheme Id}/stepsReturns all Workflow Steps associated with the specified Workflow Scheme.
  • If the Scheme does not exist, returns status 404.
reorderStepPUT/reorder/step/{Step Id}/order/{Order}Changes the order of the specified Workflow Step within the Workflow Scheme the Step is in.
updateStepPUT/steps/{Step Id}Updates the specified existing Workflow Step.

Please see below for the data to send in the body of the request.

Updating a Workflow Step

The addStep and updateStep methods expect data in the following format within the body of the request:

{
    "stepOrder":{order},
    "stepName":"{Step Name}",
    "enableEscalation":{true|false},
    "escalationAction":"{Action Id}",     // Optional
    "escalationTime":"0",                 // Optional
    "stepResolved":{true|false}
}

Workflow Actions

Executing Actions

The fire endpoint executes a Workflow Action. The fire endpoint may be called using either the Workflow Action identifier or the Workflow Action name:

EndpointMethodUsageDescription
fireActionPUT/actions/{actionId}/fireExecutes the specified Workflow Action.
fireActionPUT/actions/fireExecutes the Workflow Action specified in the request body.
fireDefaultActionPUT/actions/default/fire/{defaultAction}Executes ONLY SYSTEM default actions {NEW, EDIT, PUBLISH, UNPUBLISH ARCHIVE, UNARCHIVE, DELETE, DESTROY}.
For more information on Default Workflow Actions, please see the documentation on Default Workflow Actions.
Contents of the Request

The fire endpoint expects data in the body of the request with the JSON name "contentlet", which includes a list of the fields of the content and a “name” field which specifies the name of the application accessing the endpoint (for logging purposes).

If you wish to specify the Workflow Action via the action name, you must include an actionname field as well. This field is not required when specifying the Workflow Action identifier in the URL.

{
    "actionname" : "save",
    "contentlet" : {
        "stInode" : "{Action Inode}",
        "languageId" : {Language Id},
        "name": "{Application Name}"
    }
}

For information on how to send different Content Type Fields, please see the Save Content Using the REST API documentation.

Example

The following curl command demonstrates how to submit a full fire endpoint request (for the fileAsset Content Type), including specification of a Binary field using a multipart upload:

curl -v -u admin@dotcms.com:admin -X PUT \ http://localhost:8082/api/v1/workflow/actions/b9d89c803d/fire?identifier=b105eddc-e4b0-4a7f-85ad-b09d29a1c31b -F "json={ 'contentlet': { "contentType":"fileAsset", "languageId":1, "hostFolder":"demo.dotcms.com", "fileName":"liz2.jpg", "title":"liz!" } }; type=application/json" -F "file=@//Users/fabrizzio/Downloads/liz.jpg; type=application/jpg"

Finding Actions

EndpointMethodUsageDescription
findActionGET/actions/{Action Id}Returns the specified Workflow Action.
  • If the Action does not exist, returns 404.
  • If the user does not have permission, returns 401.
findActionByStepGET/steps/{Step id}/actions/{Action id}Returns the specified Workflow Action associated with the specified Workflow Step.
  • If the Action does not exist, returns status 404.
findActionsBySchemeGET/schemes/{Scheme Id}/actionsReturns all Workflow Actions associated with the specified Workflow Scheme.
findActionsByStepGET/steps/{Step id}/actionsReturns all Workflow Actions associated with the specified Workflow Step.
  • If the Step does not have any Actions, returns an empty list with status 200.
findAvailableActionsGET/contentlet/{Content Id}/actionsReturns the available Workflow Actions for the specified content item.
  • By default, Actions available will be displayed for Editing render mode.
  • To return Actions for the Listing render mode, add ?renderMode=listing to the URL.
findAvailableDefault
ActionsByContentType
GET/defaultactions/contenttype/{Content Type Id}Returns the default Workflow Actions associated with all Workflow Schemes assigned to the specified Content Type.
  • Returns all possible Default Workflow Actions (does not consider the state of the content or the user permissions to those Actions).
findAvailableDefault
ActionsBySchemes
GET/defaultactions/schemesReturns the Default Workflow Actions associated with all Workflow Schemes.
  • Returns all possible Default Actions (does not consider the state of the content or the user permissions to those Actions).
findInitialAvailable
ActionsByContentType
GET/initialactions/contenttype/{Content Type Id}Finds the available actions of the initial/first step(s) of the workflow scheme(s) associated with the specified Content Type.

Adding and Updating Actions

EndpointMethodUsageDescription
deleteActionDEL/actions/{Action Id}Deletes all references to a Workflow Action.
  • Deletes the specified Action from all Steps in the Workflow Scheme.
  • All deletions are permanent and can not be undone.
deleteActionFromStepDEL/steps/{Step Id}/actions/{Action Id}Deletes the specified Workflow Action from the specified Workflow Step.
  • Only removes the Action from the specified Workflow Step, not from the Workflow Scheme.
reorderActionPUT/reorder/steps/{Step Id}/actions/{Action Id}Changes the order of the specified Workflow Action within the specified Workflow Step.
Body: {"order" : 3}
saveActionPOST/actionsSaves an action.
  • If no stepId value is supplied, the Action is associated with the specified Workflow Scheme but not with any specific Step in the Scheme.
Please see below for the data to pass in the body of the request.
saveActionToStepPOST/steps/{Step Id}/actionsSaves the specified Workflow Action into the specified Workflow Step.
Body: { "actionId": "{Action Id}" }
updateActionPUT/actions/{Action Id}Updates the specified existing Workflow Action.

Please see below for the data to pass in the body of the request.
Saving or Updating an Action

The saveAction and updateAction methods expect data in the following format within the body of the request:

{
   "stepId": "{Step Id}",
      "actionName": "{Name of the new Action}",
      "schemeId": "{Scheme Id}",
      "actionCondition": "",
      "actionNextStep": "{Step Id or 'currentStep'}",
      "actionNextAssign": "{User Id or Role Id}",
      "actionRoleHierarchyForAssign": false,
      "actionAssignable": false,
      "actionCommentable": true,
      "whoCanUse":[],
      "showOn": [
        "UNPUBLISHED",
        "NEW",
        "LOCKED",
        "PUBLISHED"
      ]
}

On this page

×

We Dig Feedback

Selected excerpt:

×