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: 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

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:

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.

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 Camunda 8 API

note

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
	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
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.