Skip to main content
Version: 8.5

Migrate to Zeebe user tasks

Camunda 8.5 introduces a new user task implementation type: Zeebe user tasks. Zeebe user tasks have several benefits, including:

  • Running directly on the automation engine for high performance.
  • Removing dependencies and round trips to Tasklist.
  • A more powerful API that supports the full task lifecycle.

In this guide, you will learn:

  • Under which circumstances and when you should migrate.
  • How to estimate the impact on a project.
  • The steps you need to take for a successful migration without interrupting your operations.

Decide on your migration path

Zeebe user tasks require migration of the user tasks in both your diagrams and the task API.

With this in mind, you can migrate at your own pace. If you should migrate now or later, and what is required to migrate depends on your current setup and future plans.

Use the following decision helper questionnaire to figure out what's right for you:

Loading form...

Task type differences

Learn the differences between both task types and make an informed decision, and understand the new capabilities of Zeebe user tasks. Refer to this table for important high-level differences of the two task types:

Job worker-based user tasks

Existing implementation

Zeebe user tasks

Recommended for new projects

Implementation locationTasklist

Does not require Tasklist to run

Compatible versions8.0 +8.5 +
Supports Tasklist UI Yes Yes
Supports Tasklist API Yes

Full support


Queries, GET tasks, forms, variables

ℹ Currently, you must use Zeebe and Tasklist APIs to use Zeebe user tasks

Supports Zeebe API No Yes

Task state operations (assign/update/complete)

Supports job workers Yes No
Supports task lifecycle events No

Basic only: created/completed/canceled


Full lifecycle events including custom actions

Supports task listeners No Yes

Task listeners will be introduced in 8.6

Custom actions/outcomes No Yes

Custom actions can be defined on any operation excluding unassign (DELETE assignment, send update beforehand)

Supports task reports in Optimize No Yes

You can continue to use this task type on existing projects when you have a custom task application running on it and do not require any of the above features.

Refer to the decision helper above for a tailored recommendation.

Use this task type on any new projects when you run Tasklist.

Migrate existing projects and task applications/clients to this task type when you require one of the features above, or the following use cases:

  • Implement a full task lifecycle
  • React on any change/events in tasks, such as assignments, escalations, due date updates, or any custom actions
  • Send notifications
  • Track task or team performance
  • Build an audit log on task events
  • Enrich tasks with business data

Refer to the decision helper above for a tailored recommendation.

Switch the implementation type of your user tasks

We recommend you migrate process-by-process, allowing you to thoroughly test the processes in your test environments or via your CI/CD. To do this, take the following steps:

  1. Open a diagram you want to migrate.
  2. Click on a user task.
  3. Check if the task has an embedded form.
    • If a form is embedded, transform it into a linked form before you change the task type implementation. Press Ctrl+Z or ⌘+Z to undo if you accidentally removed your embedded form.
  4. Open the Implementation section in the properties panel.
  5. Click the Type dropdown and select Zeebe user task. The linked form or external form reference will be preserved.
Task Type Selection

Repeat these steps for all user tasks in the process. Then, deploy the process to your development cluster and test it by running the process and ensuring your custom task applications work.

Use the new Zeebe Task API


The Tasklist REST API is not deprecated, and you still need it for queries on both task types.

Operations on Zeebe user tasks which modify the task state have to be performed using the new Zeebe REST API. However, queries and adjacent operations still require the Tasklist REST API. The following table provides a breakdown of which operations are supported in which API, and for which user tasks.

OperationTasklist APIZeebe Task API (8.5)
Query tasks All types← Use Tasklist API
Get task All types← Use Tasklist API
Retrieve task variables All types← Use Tasklist API
Get task form All types← Use Tasklist API
Change task assignment Job worker-based tasks Zeebe tasks
Complete task Job worker-based tasks Zeebe tasks
Update task- Zeebe tasks
Safe and retrieve draft variables All types← Use Tasklist API

You can also operate both task types at the same time in the same application utilizing both APIs. We recommend this for a smooth migration, but you should eventually update all processes to use the new task type to use all benefits. The following image illustrates how to route API calls to the respective APIs:

Task API Architecture

The major changes are:

  • Create and maintain new, additional secrets for the Zeebe REST API.
  • Call dedicated endpoints on separate components (Zeebe vs. Tasklist) for all state modifications on tasks for the respective task types.
  • Manage new request/response objects.

The following table outlines the respective endpoints. Click the endpoints to follow to the API documentation and inspect the differences in the request and response objects.

OperationTasklist APIZeebe Task API (8.5)
Query tasksPOST /tasks/search← Use Tasklist API
Get taskGET /tasks/:taskId← Use Tasklist API
Retrieve task variablesGET /variables/:variableId
POST /tasks/:taskId/variables/search
← Use Tasklist API
Get task formGET /forms/:formId← Use Tasklist API
Assign a taskPATCH /tasks/:taskId/assignPOST /user-tasks/:taskKey/assignment
Unassign a taskPATCH /tasks/:taskId/unassignDELETE /user-tasks/:taskKey/assignee
Complete taskPATCH /tasks/:taskId/completePOST /user-tasks/:taskKey/completion
Update task-PATCH /user-tasks/:taskKey
Safe and retrieve draft variablesPOST /tasks/:taskId/variables← Use Tasklist API

Zeebe Java client

Use the Zeebe Java client when you are building your task application in Java. The client assists with managing authentication and request/response objects.

API differences

Refer to the dedicated sections and API explorers to learn details about the APIs.

Migrate from a job worker implementation

If you are not using the Tasklist API to interact with user tasks and instead implemented job workers, migrate the respective job workers. We plan to introduce task listeners in 8.6. These allow you to implement listeners for task creation in a similar fashion as you implemented the job workers, and ease the migration. We recommend to wait until the release of task listeners.

Troubleshooting and common issues

If your task application does not work properly after migration, check the following:

  • The endpoints return specific error messages when you run them on the wrong task type: Ensure to call the right endpoint for the right task type, c.f. above table.
  • Forms do not appear: Ensure you have extracted embedded forms, if any, and transformed them into linked forms, before you change the task type implementation.
  • Task update operation does not work: The update operation is only available to Zeebe user tasks.