Migrate to Camunda user tasks
Camunda 8.5 introduced a new user task implementation type: Camunda user task.
Camunda user tasks have several benefits compared to Job worked-based user tasks, including:
- 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
Camunda 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
To make an informed decision, you should understand the differences between both task types and the new capabilities of Camunda user tasks. Refer to this table for important high-level differences between the two task types:
Camunda user tasks Recommended for new and existing projects | Job worker-based user tasks Existing implementation | |
|---|---|---|
| Implementation location | Zeebe Does not require Tasklist to run | Tasklist |
| Compatible versions | 8.5 + | 8.0 + |
| Supports Tasklist UI | ✔ Yes | ✔ Yes |
| API | ||
| Supports Camunda 8 API | ✔ Yes Full support | Ｘ No |
| Supports Tasklist API (deprecated) | Partially Queries, GET tasks, forms, variables ℹ You must use Zeebe and Tasklist APIs to manage Camunda user tasks | ✔ Yes Full support |
| Supports job workers | Ｘ No | ✔ Yes |
| Supports task lifecycle events | ✔ Yes Full lifecycle events including custom actions | Ｘ No Basic only: created/completed/canceled |
| Supports task listeners | ✔ Yes | Ｘ No |
| Extras | ||
| Custom actions/outcomes | ✔ Yes Custom actions can be defined on any operation excluding unassign (DELETE assignment, send update beforehand) | Ｘ No |
| Supports task reports in Optimize | ✔ Yes | Ｘ No |
| Recommendations | 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: | 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. |
Change 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 Camunda 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.
How Tasklist API (V1) compares to Camunda 8 API (V2)
The Tasklist REST API is deprecated and will be deleted with the 8.9 release.
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 |
|---|---|---|
| Query tasks | ✔ All types | ✔ Camunda user tasks |
| Get task | ✔ All types | ✔ Camunda user tasks |
| Retrieve task variables | ✔ All types | ✔ Camunda user tasks |
| Get task form | ✔ All types | ✔ Camunda user tasks |
| Change task assignment | ✔ Job worker-based tasks | ✔ Camunda user tasks |
| Complete task | ✔ Job worker-based tasks | ✔ Camunda user tasks |
| Update task | Not supported | ✔ Camunda user tasks |
| Safe and retrieve draft variables | ✔ Job worker-based tasks | Not supported |
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 | Not supported | 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 Camunda 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 Camunda user tasks.