Workflow

GET /workflow/processdefinition (filtered-query) accepts the following additional parameters:

Every process definition response, from both the single-item read and the collection query, includes its own deploymentId field. A reader can therefore discover valid filter values from any prior response, without needing outside knowledge of Flowable’s internal deployment ID scheme.

Reading a single process definition adds start-form data when the process declares a start form key:

Unlike ProcessInstanceResource, TaskInstanceResource, TaskInstanceHistoryResource, and DeadLetterJobEntityResource, this resource does not implement applySortKeys. Its queryCollection calls Flowable’s query.list() directly, with no sort-key handling of any kind. It therefore silently ignores a _sortKeys parameter on its queries, rather than rejecting or applying it.

Deleting a process definition undeploys it (cascade=false). The resource translates a PersistenceException from the underlying store (for example, when running instances still reference the definition) to a 409 Conflict. Create, update, and patch are not supported on this resource.

GET /workflow/processdefinition/{procdefid}/taskdefinition lists every BPMN UserTask element in the given process definition, each with its form key and form property handlers attached. Its queryCollection accepts only _queryId=ALL_IDS and rejects any other value, including filtered-query, with a BadRequestException ("Unknown query-id"). Unlike every other resource on this page, it therefore has no additional filter parameters or _sortKeys support to document. The query above always returns the full, unfiltered, unsorted list of UserTask elements for the given process definition. Reading a single task definition by its BPMN element ID returns the same shape for that one task, or NotFoundException if no matching UserTask exists in the process. This resource is read-only. Create, update, delete, and instance-level action are all unsupported.

POST /workflow/processinstance starts a new process instance, either by process key (_key) or by a specific process definition ID (_processDefinitionId). It also accepts an optional _businessKey. When a request supplies both _key and _processDefinitionId, _processDefinitionId takes precedence. The createInstance method starts the instance via startProcessInstanceById. It extracts the supplied _key value from the request but never uses it. Only when _processDefinitionId is absent does _key take effect, via startProcessInstanceByKey. When a request supplies neither, _key resolves to null, and createInstance passes it through to startProcessInstanceByKey as-is. What the underlying Flowable engine does with a null process key in that case is engine-internal behavior. This page does not assert it, the same evidentiary boundary applied to the migrate and claim actions elsewhere on this page. The remaining request body becomes the initial process variables. Every started instance also receives an internal openidmcontext variable carrying a copy of the caller’s security context (authentication ID and authorization). Scripts and expressions inside the process use it to act with the starting user’s identity (see Scripting and Expression Integration). The resource strips this variable back out of every variable listing and read response before it reaches the REST caller.

GET /workflow/processinstance lists only unfinished instances. GET /workflow/processinstance/history lists all historic instances regardless of completion. The same ProcessInstanceResource class serves both routes, constructed with a different history query (unfinished() vs. no filter). Every other operation (create, read, update, delete, action) behaves identically no matter which of the two paths reached it.

The following additional parameters apply to filtered-query:

Unlike _businessKey, no caller can set businessStatus through this resource at all. When a create request comes in, createInstance extracts only _key, _processDefinitionId, and _businessKey from it. An update request instead hits updateInstance, which unconditionally returns a not-supported error. The resource’s only instance action, migrate, does not touch it either. A running instance’s business status can therefore come only from the process itself, through the embedded Flowable engine’s own API, never through this REST resource.

Sortable keys are processInstanceId, processDefinitionId, processInstanceBusinessKey, startTime, endTime, durationInMillis, and tenantId.

Reading a single instance includes its non-context process variables and the list of historic tasks that ran under it. Requesting the diagram field also renders a base64-encoded PNG diagram (the same encoding used for the process-definition diagram) with the process instance’s currently active activities highlighted. This applies only if the deployed process definition has a graphical BPMN notation. Otherwise the resource silently omits the diagram field rather than causing an error.

Deleting an instance (DELETE, addressable from either path) cancels the running process via RuntimeService.deleteProcessInstance, recording the deletion reason "Deleted by Wren:IDM.". It returns the instance’s last known historic state.

The migrate action (no request body) moves a running instance onto the process definition returned by Flowable’s latestVersion() query for the same process definition key. It rejects the request if no instance or no later definition exists, or if the instance is already on the latest version. All three rejection cases return a BadRequestException (each with a distinct message), so a caller can treat any 400 response from this action as one of those three named conditions. A failure during the migration call itself instead returns a generic InternalServerErrorException.

GET /workflow/taskinstance (filtered-query) accepts the following additional parameters:

Supplying multiple comma-separated groups to taskCandidateGroup matches a task if it is a candidate for any one of the listed groups. It does not require the task to be a candidate for all of them.

Sortable keys are _id, name, description, priority, assignee, processInstanceId, executionId, createTime, dueDate, and tenantId.

Reading a task adds its form properties, current variables (openidmcontext excluded), the assignee (or, when a delegation is pending, the delegate instead), and its candidate users/groups. This resource has no way to place a task into delegation itself. It only reads DelegationState.PENDING, never sets it, so a task reaches that state only through the BPMN process definition or the Flowable engine directly. Updating a task can change assignee, description, name, and owner. The resource ignores other fields. Deleting a task accepts an optional deleteReason additional parameter.

This resource supports two instance actions:

The claim action calls Flowable’s TaskService.claim(resourceId, userId) directly. Wrenidm’s own code does not check the task’s current assignee beforehand, and it has no separate branch for an already-assigned task. Whether TaskService.claim itself succeeds unconditionally or only on an unclaimed task is Flowable engine-internal behavior. This page does not assert it, the same evidentiary boundary applied to the migrate action above.

GET /workflow/taskinstance/history exposes the same task instances through Flowable’s history API. It is query- and read-only. Create, update, delete, and action all return notSupportedOnInstance/notSupportedOnCollection. The following additional parameters apply to filtered-query:

As with TaskInstanceResource above, supplying multiple comma-separated groups to taskCandidateGroup matches a task if it is a candidate for any one of the listed groups. It does not require the task to be a candidate for all of them.

Unlike TaskInstanceResource, taskCandidateOrAssigned and unassigned are not supported here.

Sortable keys are taskId, taskName, description, priority, assignee, processInstanceId, executionId, tenantId, _id (maps to orderByHistoricActivityInstanceId(), a different sort than TaskInstanceResource’s own `_id, which maps to orderByTaskId()), processDefinitionId, durationInMillis, startTime, endTime, owner, dueDate, deleteReason, and taskDefinitionKey.

GET /workflow/job/deadletter lists jobs that exhausted their retry count, filterable by jobId, executionId, processDefinitionId, and processInstanceId, and sortable by createTime, executionId, _id, processInstanceId, and retries. Reading a single dead-letter job by ID returns its job representation, or NotFoundException if no such job exists. The retry action (no request body) moves a dead-letter job back to the executable job queue with one retry attempt. This resource does not support create, update, delete, and collection-level action.