Skip to main content
Version: 8.7 (unreleased)

Migrate to the Camunda 8 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 Camunda 8 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 Camunda 8 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 Camunda 8 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.

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
    • GET /v2/process-definitions/{processDefinitionKey}/form
  • 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​

  • V1 endpoint: POST /v1/tasks/search
  • V2 endpoint: POST /v2/user-tasks/search
  • 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.
    • 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.
  • Removed attributes
    • 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", ... ] }.
    • 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.
  • Added attributes
    • userTaskKey - Filter for specific user tasks by their unique system identifiers.
    • processDefinitionId - Filter for user tasks by the user-provided unique identifier of the process.
    • elementInstanceKey - Find tasks by the unique system identifier of the instance of the BPMN element that created the user task.

Unassign user task​

  • V1 endpoint: PATCH /v1/tasks/{taskId}/unassign
  • V2 endpoint: DELETE /v2/user-tasks/{userTaskKey}/assignee
  • No input adjustments.

Complete user task​

  • V1 endpoint: PATCH /v1/tasks/{taskId}/complete
  • V2 endpoint: POST /v2/user-tasks/{userTaskKey}/completion
  • 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.
  • Added attributes
    • action - Provide any custom lifecycle for this action or use the default value of "assign".

Assign user task​

  • V1 endpoint: PATCH /v1/tasks/{taskId}/assign
  • V2 endpoint: POST /v2/user-tasks/{userTaskKey}/assignment
  • Renamed attributes
    • allowOverrideAssignment - Use allowOverride, this still refers to allowing to override any existing assignee.
  • Added attributes
    • action - Provide any custom lifecycle for this action or use the default value of "assign".

Get user task​

  • V1 endpoint: GET /v1/tasks/{taskId}
  • V2 endpoint: GET /v2/user-tasks/{userTaskKey}
  • No input adjustments.