Migrate to Zeebe user tasks
Camunda 8.5 introduced a new user task implementation type: Zeebe user tasks.
Zeebe user tasks have several benefits compared to job worked-based user tasks. It includes:
- Running directly on the automation engine for high performance.
- Removing dependencies and round trips to Tasklist.
- A 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.
- 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.
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 existing and new projects | |
|---|---|---|
| Implementation location | Tasklist | Zeebe Does not require Tasklist to run |
| Compatible versions | 8.0 + | 8.5 + |
| Supports Tasklist UI | ✔ Yes | ✔ Yes |
| API | ||
| Supports Tasklist API | ✔ Yes Full support | Partially Queries, GET tasks, forms, variables ℹ Currently, you must use the Camunda 8 and Tasklist APIs to use Zeebe user tasks |
| Supports Camunda 8 API | Ｘ No | ✔ Yes Task state operations (assign/update/complete) |
| Supports job workers | ✔ Yes | Ｘ No |
| Supports task lifecycle events | Ｘ No Basic only: created/completed/canceled | ✔ Yes Full lifecycle events including custom actions |
| Supports task listeners | Ｘ No | ✔ Yes |
| Extras | ||
| 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 |
| Recommendations | 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. | Recommended for existing and 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: |
Switch the implementation type of 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:
- Open a diagram you want to migrate.
- Click on a user task.
- 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+Zor⌘+Zto undo if you accidentally removed your embedded form.
- If a form is embedded, transform it into a linked form before you change the task type implementation. Press
- Open the Implementation section in the properties panel.
- Click the Type dropdown and select Zeebe user task. The linked form or external form reference will be preserved.
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 Camunda 8 API
The Tasklist REST API is not deprecated, and you still need it for queries on both task types.
The following table provides a breakdown of which operations are supported in which API, and for which user tasks.
| Operation | Tasklist API | Camunda 8 API |
|---|---|---|
| Deprecated on 8.7 | Supported from 8.6+ | |
| Query user task | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Get user task | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Retrieve task variables | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Get user task form | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Change task assignment | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Complete task | ✔ Job worker-based user tasks | ✔ Zeebe user tasks |
| Update task | - | ✔ Zeebe user tasks |
| Save and retrieve draft variables | ✔ Job worker-based user tasks | - |
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.
| Operation | Tasklist API | Camunda 8 API |
|---|---|---|
| Query user tasks | POST /tasks/search | POST /user-tasks/search |
| Get user task | GET /tasks/:taskId | GET /user-tasks/:userTaskKey |
| Retrieve task variables | GET /variables/:variableId | POST /tasks/:taskId/variables/search |
| Get task form | GET /forms/:formId | GET /user-tasks/:userTaskKey/form |
| Assign a task | PATCH /tasks/:taskId/assign | POST /user-tasks/:userTaskKey/assignment |
| Unassign a task | PATCH /tasks/:taskId/unassign | DELETE /user-tasks/:userTaskKey/assignee |
| Complete task | PATCH /tasks/:taskId/complete | POST /user-tasks/:userTaskKey/completion |
| Update task | - | PATCH /user-tasks/:userTaskKey |
| Save and retrieve draft variables | POST /tasks/:taskId/variables | - |
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.
📄️ Tasklist API (REST)
Build applications for human-centered processes by querying user tasks, assigning users, and completing tasks with the Tasklist API.
📄️ Camunda 8 API (REST)
Interact with Camunda 8 clusters. Activate jobs and run user task state operations for Zeebe user tasks.
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.