This page describes the REST API for workflows.

The following actions are supported with the REST API:

  • start or stop a workflow service
  • create, update or delete workflow models
  • start, suspend, resume or terminate workflow instances
  • complete or delegate work items

Note

The CQ Workflow console makes heavy use of the REST API. By using Firebug, a Firefox extension for web development, it is possible to follow the HTTP traffic when the console is operated. For example you can check the parameters and the values sent to the CQ server with a POST request.

In this page it is assumed that CQ runs on localhost at port 4502 and that the installation context is "/" (root). If it is not the case of your installation, the URIs, to which the HTTP requests apply, need to be adapted accordingly.

The rendering supported for GET requests is the JSON rendering. The URLs for GET should have the .json extension, for example:

http://localhost:4502/etc/workflow.json

Managing Workflow Instances

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/instances

   
 HTTP request method
 Actions
 GET Lists the available workflow instances.
 POST

Creates a new workflow instance. The parameters are:

- "model": the ID (URI) of the respective workflow model

- "payloadType": containing the type of the payload (for example JCR_PATH or URL).

The payload is sent as parameter "payload". A 201 (CREATED) response is sent back with a location header containing the URL of the new workflow instance resource.

Managing a Workflow Instance by its State

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/instances.{state}

   
 HTTP request method
 Actions
 GET Lists the available workflow instances and their states (RUNNING, SUSPENDED, ABORTED or COMPLETED)

Managing a Workflow Instance by its ID

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/instances/{id}

   
 HTTP request method
 Actions
 GET Gets the instances data (definition and metadata) including the link to the respective workflow model.
 POST Changes the state of the instance. The new state is sent as the parameter "state" and must have one of the following values:RUNNING, SUSPENDED, or ABORTED.

If the new state is not reachable (for example when suspending a terminated instance) a 409 (CONFLICT) response is sent back to the client. 

Managing Workflow Models

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/models

   
 HTTP request method
 Actions
 GET Lists the available workflow models.
 POST Creates a new workflow model. If the parameter "title" is sent, a new model is created with the specified title. Attaching a JSON model definition as parameter "model" creates a new workflow model according to the provided definition.

A 201 response (CREATED) is sent back with a location header containing the URL of the new workflow model resource.

The same happens when a model definition is attached as a file parameter called "modelfile".

In both the cases of the "model" and "modelfile" parameters, an additional parameter called "type" is required to define the serialization format. New serialization formats can be integrated using the OSGI API. A standard JSON serializer is delivered with the workflow engine. Its type is JSON. See below for an example of the format.

Example: in the browser, a request to http://localhost:4502/etc/workflow/models.json gets a similar json file to the following one:


[

{"uri":"/etc/workflow/models/collab/comment_moderation"}

,{"uri":"/etc/workflow/models/dam/dam_asset_syncer_and"}

,{"uri":"/etc/workflow/models/dam/delete_asset"}

,{"uri":"/etc/workflow/models/dam/delete_dam_asset"}

,{"uri":"/etc/workflow/models/dam/dam_set_last_modified"}

,{"uri":"/etc/workflow/models/dam/dam_update_dam_content_create"}

,{"uri":"/etc/workflow/models/dam/dam_update_dam_content_del"}

,{"uri":"/etc/workflow/models/dam/dam_update_var_folder_create"}

,{"uri":"/etc/workflow/models/dam/dam_update_var_folder_delete"}

,{"uri":"/etc/workflow/models/dam/update_asset"}

,{"uri":"/etc/workflow/models/dam/update_from_lightbox"}

,{"uri":"/etc/workflow/models/my_workflow"}

,{"uri":"/etc/workflow/models/newsletter_example"}

,{"uri":"/etc/workflow/models/product_of_the_day"}

,{"uri":"/etc/workflow/models/publish_example"}

,{"uri":"/etc/workflow/models/request_for_activation"}

,{"uri":"/etc/workflow/models/request_for_deactivation"}

,{"uri":"/etc/workflow/models/scheduled_activation"}

,{"uri":"/etc/workflow/models/scheduled_deactivation"}

,{"uri":"/etc/workflow/models/translation"}

,{"uri":"/etc/workflow/models/welcome_new_employees"}

]

Managing a Workflow Model by its ID

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/models/{id}

   
 HTTP request method
 Actions
 GET Gets the HEAD version of the model (definition and metadata).
 PUT Updates the head version of the model (creates a new version).

The complete model definition for the new version of the model must be added as a parameter called "model". Additionally a "type" parameter is needed as when creating new models and needs to have the value "JSON".
 POST Same behaviour as with PUT. Needed because CQ widgets do not support PUT operations.
 DELETE Deletes the model. In order to solve firewall/proxy issues a POST that contains a X-HTTP-Method-Override header entry with value DELETE will also be accepted as DELETE request.

Example: in the browser, a request to http://localhost:4502/etc/workflow/models/publish_example.tidy.-1.json gets a similar json file to the following one:

{
"description": "This example shows a simple review and publish process.",
"title": "Publish Example",
"jcr:predecessors": [
],
"sling:resourceType": "cq/workflow/components/model",
"jcr:uuid": "675f04fd-eb3c-44b9-9921-90926c8fc0f0",
"jcr:versionHistory": "44fb918c-b081-47d8-95b8-dbd68b9cce08",
"jcr:baseVersion": "75ce2903-9159-4bf7-8b0d-af232e252fbb",
"jcr:primaryType": "cq:WorkflowModel",
"jcr:isCheckedOut": false,
"metaData": {
"tags": "wcm",
"jcr:primaryType": "nt:unstructured"
},
"nodes": {
"jcr:primaryType": "nt:unstructured",
"node0": {
"title": "Start",
"description": "The start node of the workflow.",
"type": "START",
"jcr:primaryType": "cq:WorkflowNode",
"metaData": {
"jcr:primaryType": "nt:unstructured"
}
},
"node1": {
"title": "Validate Content",
"description": "Validate the modified content.",
"type": "PARTICIPANT",
"jcr:primaryType": "cq:WorkflowNode",
"metaData": {
"PARTICIPANT": "admin",
"jcr:primaryType": "nt:unstructured"
}
},
"node2": {
"title": "Publish Content",
"description": "Publish the modified content.",
"type": "PROCESS",
"jcr:primaryType": "cq:WorkflowNode",
"metaData": {
"PROCESS_AUTO_ADVANCE": "true",
"PROCESS": "com.day.cq.wcm.workflow.process.ActivatePageProcess",
"jcr:primaryType": "nt:unstructured"
}
},
"node3": {
"title": "End",
"description": "The end node of the workflow.",
"type": "END",
"jcr:primaryType": "cq:WorkflowNode",
"metaData": {
"jcr:primaryType": "nt:unstructured"
}
}
},
"transitions": {
"jcr:primaryType": "nt:unstructured",
"node0#node1": {
"to": "node1",
"from": "node0",
"jcr:primaryType": "cq:WorkflowTransition",
"metaData": {
"jcr:primaryType": "nt:unstructured"
}
},
"node1#node2": {
"to": "node2",
"from": "node1",
"jcr:primaryType": "cq:WorkflowTransition",
"metaData": {
"jcr:primaryType": "nt:unstructured"
}
},
"node2#node3": {
"to": "node3",
"from": "node2",
"jcr:primaryType": "cq:WorkflowTransition",
"metaData": {
"jcr:primaryType": "nt:unstructured"
}
}
}
}

Managing a Workflow Model by its Version

The following HTTP request methods apply to:

http://localhost:4502/etc/workflow/models/{id}.{version}

   
 HTTP request method
 Actions
 GET Gets the data of the model in the given version (if it exists).

Managing (User) Inboxes

The following HTTP request methods apply to:

http://localhost:4502/bin/workflow/inbox

   
 HTTP request method
 Actions
 GET Lists the work items that are in the inbox of the user, who is identified by the HTTP authentication headers.
 POST Completes the work item whose URI is sent as the parameter "item" and advances the according workflow instance to the next node(s), that is defined by the parameter "route" or "backroute" in case of going a step back.

If the parameter "delegatee" is sent, the work item identified by the parameter "item" is delegated to the specified participant.

Managing a (User) Inbox by the WorkItem ID

The following HTTP request methods apply to:

http://localhost:4502/bin/workflow/inbox/{id}

   
 HTTP request method
 Actions
 GET Gets the data (definition and metadata) of the inbox WorkItem identified by its ID.

Managing the Workflow Engine

The following HTTP request methods apply to: 

http://localhost:4502/etc/workflow

   
 HTTP request method
 Actions
 GET Gets the state of the workflow engine (refer to OSGI documentation to get a list of OSGi SCR service component states) as well as configuration parameters.
 POST Starts/stops the workflow engine. The new state is sent as parameter and is either ACTIVE or DISABLED.

If the new state is not reachable (for example when stopping an already stopped workflow engine) a 409 status response (CONFLICT) is sent to the client.

Example: in the browser, a request to http://localhost:4502/etc/workflow.json gets a similar json file to the following one:

{
state: "ACTIVE"
component.name: "com.day.cq.workflow.impl.CQWorkflowService"
cq.workflow.models: "/etc/workflow/models"
cq.workflow.group: "workflow-users"
service.vendor: "Day Management AG"
cq.workflow.instances: "/etc/workflow/instances"
cq.workflow.superuser: "[Ljava.lang.String;@44945113"
service.pid: "com.day.cq.workflow.impl.CQWorkflowService"
component.id: "197"
cq.workflow.workspace: "crx.default"
service.description: "%cq.workflow.service.description"
cq.workflow.job.retry: "3"
cq.workflow.inbox: "workflow-inbox"
}

Basic Examples and Howtos

How to start a Workflow

To start a workflow, do a POST:

  • to: http://localhost:4502/etc/workflow/instances
  • with the following parameters:
    • model: the model id
    • payload: the payload
    • payloadType: the payload type
    • (optional) startComment: a comment
    • (optional) workflowTitle: the workflow title

Example using curl:

curl -u admin:admin -d "model=/etc/workflow/models/request_for_activation/jcr:content/model&payload=/content/geometrixx/en/company&payloadType=JCR_PATH&workflowTitle=myWorkflowTitle" http://localhost:4502/etc/workflow/instances

How to get a List of all Running Workflows

To get a list of all running workflows, do a GET to:

http://localhost:4502/etc/workflow/instances.RUNNING

Example using curl:

curl -u admin:admin http://localhost:4502/etc/workflow/instances.RUNNING.json

How to stop a Stale Workflow

To stop a stale workflow, do a POST:

  • to: http://localhost:4502/etc/workflow/instances/{id}
  • with the following parameter:
    • state: its value has to be ABORTED

Example using curl:

curl -u admin:admin -d "state=ABORTED"  http://localhost:4502/etc/workflow/instances/{id}

Note

To stop all the stale workflows using curl, you can create a script, loop over each stale workflow and stop each one by using the previous command.

How to change the Workflow Title

To change the Workflow Title displayed in the Instances tab of the workflow console, send a POST command:

  • to: http://localhost:4502/etc/workflow/instances/{id}
  • with the following parameters:
    • action: its value has to be: UPDATE
    • workflowTitle: the workflow title

Example using curl:

curl -u admin:admin -d "action=UPDATE&workflowTitle=myWorkflowTitle" http://localhost:4502/etc/workflow/instances/{id}

Your comments are welcome!
Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

ADD A COMMENT

 

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.

***