Skip to main content

Migrate to the Orchestration cluster API

This document offers a comprehensive guide to migrate from Camunda's V1 component REST APIs (the Tasklist REST API, for example) to the V2 Orchestration cluster REST API.

Camunda is streamlining the developer experience by creating a unified REST API for Zeebe, Operate, Tasklist, and the Identity components with endpoint parity. This will be a single REST API for the orchestration cluster for a consistent and intuitive API experience to help your teams develop process automation solutions faster.

note

The Administration and Web Modeler APIs will not be part of the Orchestration cluster REST API, as these are platform APIs outside the cluster’s scope.

Over time, there will be a deprecation process for the individual component APIs starting with the former Operate and Tasklist APIs. These will continue to be in the product for the short-term, but it is recommended to begin the adoption of the new API. In addition, we will begin to deprecate several Zeebe gPRC endpoints as well. See the official blog announcement.

This guide considers all public endpoints existing in the component REST APIs and the Orchestration cluster API counterparts or required migration changes.

General endpoint changes​

  • The new API can be found at <cluster>/v2/…> instead of <cluster>/v1/…>.
  • All endpoints are no longer separated by component concerns and all endpoints receive similar support. For example, process definitions, user tasks, and user authorizations were previously spread across separate Tasklist, Operate, and Identity APIs.
  • Naming, response codes, and type handling have been streamlined for all endpoints to provide a consistent UX.
  • Endpoints with similar concerns (variable search, for example) have been consolidated into single endpoints.
  • The request and response payload of every new endpoint might contain new attributes that are not necessarily needed for a migration from a V1 endpoint to V2 but might still be useful. Please consult the V2 API guides for access to all new attributes.

Name changes and mappings​

The following conventions apply to all attributes:

  • key and id fields contain the entity as a prefix, for example, userTaskKey, processDefinitionId. This applies when referencing other resources like formKey in the user task entity, in the respective entities themselves like userTaskKey in the user task entity.
  • The full entity is the prefix to avoid confusion, for example processDefinitionKey instead of processKey (the latter could be interpreted as process instance or process definition).
  • Other attributes of entities themselves have no prefix to avoid clutter, for example version in the process definition entity. In other resources, they have to be referenced with a prefix, like processDefinitionVersion in the process instance entity.
  • The bpmnProcessId and processName are now called processDefinitionId to be easily relatable to the process definition entity, like the processDefinitionKey.
  • The decisionKey and dmnDecisionKey are now aligned to decisionDefinitionKey, the decisionId and dmnDecisionId to decisionDefinitionId. Similar to the processDefinitionId being related to the process definition, those attributes are now easily relatable to the decision definition entity.

Tasklist API​

Form​

Get a form​

  • V1 endpoint: GET /v1/forms/{formId}
  • V2 endpoints:
    • GET /v2/user-tasks/{userTaskKey}/form (link)
    • GET /v2/process-definitions/{processDefinitionKey}/form (link)
  • You cannot fetch forms directly anymore. Instead, fetch them by user task or process definition to get the respective form data.
  • The respective endpoint only takes the key of the resource the form is related to as input parameter.

Task​

Save task draft variables​

  • V1 endpoint: POST /v1/tasks/{taskId}/variables
  • V2 endpoint: This feature is not supported in V2 anymore. Use setting variables as local to the user task's elementInstanceKey as a replacement.

Search task variables​

  • V1 endpoint: POST /v1/tasks/{taskId}/variables/search
  • V2 endpoint: POST /v2/user-tasks/{userTaskKey}/variables/search
  • Request structure changes as outlined in general changes.
  • Renamed attributes
    • variableNames - Use the filter object's name, either with a plain string for one exact match or with { "$in": [ "xyz", ... ]}.
  • Removed attributes
    • includeVariables - The endpoint returns all variables associated with the user task.

Search tasks​

  • Request structure changes as outlined in general changes.
    • The pageSize is now the limit in the page object.
    • The searchAfter and searchBefore are in the page object as after and before.
    • The searchAfterOrEqual and searchBeforeOrEqual options do not exist.
  • Renamed attributes
    • taskDefinitionId - Use elementId as this refers to the user-provided identifier of the BPMN element that created the user task.
    • followUpDate and dueDate filter options - Instead of from and to, use $gte and $lte. Additionally, you can use new comparison filter options.
    • priority filter options - Filter object keys need a $ prefix. Additionally, you can use new comparison filter options like $neq, $exists, and $in.
    • assigned - Use assignee with { "$exists": false }. Multiple filters can be combined in one attribute.
    • assignees - Use assignee with { "$in": [ "xyz", ... ] }. Multiple filters can be combined in one attribute.
    • candidateGroups - Use candidateGroup with { "$in": [ "xyz", ... ] }.
    • candidateUsers - Use candidateUser with { "$in": [ "xyz", ... ] }.
    • taskVariables split up and renamed
      • You can define localVariables and processInstanceVariables.
      • Local variables match the defined name and value and exist in the local scope of the BPMN element instance that created the user task.
      • Process instance variables match the defined name and value and exist anywhere in the process instance that the user task belongs to.
    • tenantIds - Use tenantId with { "$in": [ "xyz", ... ] }.
  • Removed attributes
    • includeVariables - The endpoint does not return variables. Use the search task variables endpoint to retrieve them.
    • implementation - The V2 API supports only Camunda user tasks.

Unassign a task​

  • No input adjustments.

Complete a task​

  • Adjusted attributes
    • variables - Provide the variables as a proper JSON object instead of an array of objects with a name and a serialized JSON string value.

Assign a task​

  • Renamed attributes
    • allowOverrideAssignment - Use allowOverride, this still refers to allowing to override any existing assignee.

Get a task​

  • No input adjustments.

Variables​

Get a variable​

  • variableId - Use variableKey as this refers to the unique system identifier of the variable.

Operate API​

Decision definition​

Search decision definitions​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • id - Use decisionDefinitionKey instead.
    • key of type int64 - Use decisionDefinitionKey of type string.
    • decisionId - Use decisionDefinitionId instead.
    • decisionRequirementsKey of type int64 - This is now of type string.
  • Removed attributes from the filter object
    • decisionRequirementsName - Can no longer be used for filtering.
    • decisionRequirementsVersion - Can no longer be used for filtering.

Get decision definition by key​

  • V1 endpoint: GET /v1/decision-definitions/{key}
  • V2 endpoint: GET /v2/decision-definitions/{decisionDefinitionKey}
  • No input adjustments.

Search decision instances​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • id - Use decisionInstanceId instead.
    • key of type int64 - Use decisionInstanceKey of type string.
    • processDefinitionKey of type int64 - This is now of type string.
    • processInstanceKey of type int64 - This is now of type string.
    • decisionId - Use decisionDefinitionId instead.
    • decisionName - Use decisionDefinitionName instead.
    • decisionVersion - Use decisionDefinitionVersion instead.
    • decisionType - Use decisionDefinitionType instead.
  • Removed attributes in the filter object
    • result - Can no longer be used for filtering.
    • evaluatedInputs - Can no longer be used for filtering.
    • evaluatedOutputs - Can no longer be used for filtering.

Get decision instance by id​

  • No input adjustments.

Search decision requirements​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • id - Use decisionRequirementsKey instead.
    • key of type int64 - Use decisionRequirementsKey of type string.
    • name - Use decisionRequirementsName instead.

Get decision requirements by key​

  • No input adjustments.

Get decision requirements as XML by key​

  • No input adjustments.

Variable​

Search variables for process instances​

  • Response structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • key of type int64 - Use variableKey of type string.
    • processInstanceKey of type int64 - This is now of type string.
    • scopeKey of type int64 - This is now of type string.
    • truncated - Use isTruncated instead.

Get variable by key​

  • No input adjustments.

Process definition​

Search process definitions​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • key of type int64 - Use processDefinitionKey of type string instead.
    • bpmnProcessId - Use processDefinitionId instead.

Get process definition by key​

  • V1 endpoint: GET /v1/process-definitions/{key}
  • V2 endpoint: GET /v2/process-definitions/{processDefinitionKey}
  • No input adjustments.

Get process definition as XML by key​

  • V1 endpoint: GET /v1/process-definitions/{key}/xml
  • V2 endpoint: GET /v2/process-definitions/{processDefinitionKey}/xml
  • No input adjustments.

Process instance​

Search process instances​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • key of type int64 - Use processInstanceKey of type string instead.
    • processVersion - Use processDefinitionVersion instead.
    • processVersionTag - Use processDefinitionVersionTag instead.
    • bpmnProcessId - Use processDefinitionId instead.
    • parentFlowNodeInstanceKey - Use parentElementInstanceKey of type string instead.
    • parentKey - Use parentProcessInstanceKey of type string instead.
    • state - Use value TERMINATED instead of value CANCELED.
    • incident - Use hasIncident instead.
  • Adjusted attributes in the filter object
    • parentProcessInstanceKey - Type changed from int64 to string.
    • processDefinitionKey - Type changed from int64 to string.

Get process instance by key​

  • No input adjustments.

Delete process instance and all dependant data by key​

  • V1 endpoint: DELETE /v1/process-instances/{key}
  • V2 endpoint: This feature is not yet available in V2. It will be added in a future version.

Get flow node statistic by process instance key​

  • V1 endpoint: GET /v1/process-instances/{key}/statistics
  • V2 endpoint: GET /v2/process-instances/{processInstanceKey}/statistics/element-instances
  • No input adjustments.

Get sequence flows of process instance by key​

  • V1 endpoint: GET /v1/process-instances/{key}/sequence-flows
  • V2 endpoint: GET /v2/process-instances/{processInstanceKey}/sequence-flows
  • No input adjustments.

Flownode instances​

Search flownode instances​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • key of type int64 - Use elementInstanceKey of type string instead.
    • flowNodeId - Use elementId instead.
    • flowNodeName - Use elementName instead.
    • incident - Use hasIncident instead.
  • Adjusted attributes in the filter object
    • processInstanceKey - Type changed from int64 to string.
    • processDefinitionKey - Type changed from int64 to string.
    • incidentKey - Type changed from int64 to string.
  • Removed attributes from the filter object
    • startDate - Can no longer be used for filtering.
    • endDate - Can no longer be used for filtering.

Get flownode instance by key​

  • No input adjustments.

Incidents​

Search incidents​

  • Request structure changes as outlined in general changes.
    • searchAfter is now the after in the page object.
    • size is now the limit in the page object.
  • Renamed attributes in the filter object
    • key of type int64 - Use incidentKey of type string instead.
    • type - Use errorType instead.
    • message - Use errorMessage instead.
  • Adjusted attributes in the filter object
    • processInstanceKey - Type changed from int64 to string.
    • processDefinitionKey - Type changed from int64 to string.
    • jobKey - Type changed from int64 to string.

Get incident by key​

  • No input adjustments.