8.9 Workflow HTTP interface

Here we'll look into the specifics of the workflow HTTP interface. For a general introduction, see the repository HTTP API.

Most workflow related URLs which return some XML take a "locale" request parameter to specify the prefered locale for localized content (such as labels and descriptions). For example, this can be "?locale=fr" or "?locale=en-US"

/workflow/task

GET:

• no request parameter: all tasks assigned to the current user
• with request parameter select=pooled, all tasks belonging to the user's pools

/workflow/task/<taskId>

GET: retrieves XML representation of the task

POST: depending on the value of the "action" request parameter:

• no action parameter: updates or ends task, as specified in the XML payload (wf:taskUpdateData, see workflowmsg.xsd)
• action=requestPooledTask: assign a pool task to the current user
• action=unassignTask: unassigns the task from the current actor, putting it back into the pool(s)
• action=assignTask: assign the task to a specified actor. To specify the actor, add a request parameter actorType with value "user" or "pools". The ID of the actor itself (thus the user or pool ID) is specified in a request parameter named actor. In case of pools, multiple actor parameters can be given.

/workflow/process

POST: start a new workflow process. The parameters are specified in the XML payload, which is an wf:startProcess element (see workflowmsg.xsd)

/workflow/process/<processId>

GET: retrieves an XML representation of the process instance

POST: perform an action based on the value of the "action" request parameter:

• action=signal: signals an execution path. Additional request parameters: executionPath (required) and transitionName (not required). Returns an XML representation of the execution path.
• action=suspend: suspends a process, no additional parameters needed.
• action=resume: resumes a process, no additional parameters needed.

DELETE: deletes the process instance.

/workflow/processDefinition

GET: retrieves an XML representation of the list of all process definitions, in all their versions. Add a request parameter latestOnly=true to get only the latest version of each process definition.

POST: deploys a new process definition. The payload should be a multipart request containing an item named "processdefinition" which contains the process definition, either in XML form or as a process archive (zip file). The content type of the item should be set accordingly, thus to text/xml or application/zip.

Reloading the sample workflows can be done by using POST with the request parameter action=loadSamples (no body data).

/worfklow/processDefinition/<id>

GET: retrieves an XML representation of this process definition

DELETE: permanently deletes the process definition. Be careful: this also deletes all process instances associated with this definition, without any further warning.

/workflow/processDefinition/<id>/initialVariables

GET: retrieves the (calculated) initial variable values for the start-state task.

/workflow/processDefinitionByName/<name>

GET: retrieves an XML representation of this process definition.

/workflow/pool

GET: retrieves the XML representation of the list of either:

• all pools
• the pools to which a certain user belongs, specified using the request parameter limitToUser=<userId>

POST: creates a new pool, the payload should be an XML document with wf:pool as root element (see pool.xsd)

/workflow/pool/<id>

GET: retrieves an XML representation of the pool

POST: updates the pool by submitting an updated variant of the XML representation retrieved using GET.

DELETE: deletes the pool

/workflow/poolByName/<name>

GET: retrieves an XML representation of the pool.

/workflow/pool/<id>/membership

GET: retrieves the list of users that are member of this pool (as a wf:users element, see pool.xsd).

POST: updates the membership of the pool, according to the value of the "action" request parameter:

• add or remove: adds or removes users to/from the pool. The users should be specified in the XML payload as a wf:users element (see pool.xsd)
• clear: removes all users from the pool

/workflow/query/process

POST: performs a query for processes, the query is described in the XML payload. See Workflow query system for more details.

/workflow/query/task

POST: performs a query for tasks, the query is described in the XML payload. See Workflow query system for more details.

/workflow/query/timer

POST: performs a query for timers, the query is described in the XML payload. See Workflow query system for more details.

/workflow/processInstanceCounts

GET: retrieves the number of instances that exist for each version of each process definition, returned in the form of some XML.

/workflow/timer/*

GET: retrieves an XML representation of the timer.