PATCH /user-tasks/:userTaskKey
@@ -378,4 +373,4 @@ If your task application does not work properly after migration, check the follo
- **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](#use-the-new-camunda-8-api).
- **Forms do not appear**: Ensure you have extracted embedded forms, if any, and [transformed them into linked forms](/components/modeler/bpmn/user-tasks/user-tasks.md#camunda-form-linked), before you change the task type implementation.
-- **Task update operation does not work**: The update operation is only available to Zeebe user tasks.
+- **Task update operation does not work**: The update operation is only available to Camunda user tasks.
diff --git a/docs/apis-tools/tasklist-api-rest/assets/forms/userTaskMigrationDecisionHelperForm.js b/docs/apis-tools/tasklist-api-rest/assets/forms/userTaskMigrationDecisionHelperForm.js
index c2220d4d347..1a03e94c802 100644
--- a/docs/apis-tools/tasklist-api-rest/assets/forms/userTaskMigrationDecisionHelperForm.js
+++ b/docs/apis-tools/tasklist-api-rest/assets/forms/userTaskMigrationDecisionHelperForm.js
@@ -302,7 +302,7 @@ export default {
},
{
content:
- '\n\n\n{{#if conditions.useUserTasks = "no" or (conditions.runCustomTaskApp = "no" and conditions.runTasklistUI = "no") }}\n\nNothing to do for you!
\nSince you do not use user tasks, you do not have to worry about migrating them.
\nHowever, if you plan to introduce them at any point in time, you can refer to this decision helper again.\n
\n{{/if}}\n\n{{#if conditions.runCustomTaskApp = "notYet" and conditions.runTasklistUI = "yes" and conditions.requireLifecycle != null }}\n\nUse Zeebe user tasks
\nAs you plan to introduce a custom task application, \nuse "Zeebe user tasks" as the implementation type for your user tasks.\n
\nFirst switch the implementation type of all your user tasks to "Zeebe user tasks",\nbefore you start developing your custom task application. \nJob-based user tasks are not supported in the Zeebe API for user tasks.
\nYou can safely migrate your existing user tasks to the new task type,\nsince the Camunda Tasklist UI supports both task types.\n
\n{{/if}}\n\n{{#if conditions.runCustomTaskApp = "notYet" and conditions.runTasklistUI = "no" }}\n\nUse Zeebe user tasks
\nAs you plan to introduce a custom task application, \nuse "Zeebe user tasks" as the implementation type for your user tasks.\n
\n{{/if}}\n\n{{#if conditions.requireLifecycle = "no" and conditions.runCustomTaskApp != "notYet"}}\n\n
No immediate action needed\nSince you do not plan to use task lifecycle features, there is no urgent need for you to migrate.
\n{{#if conditions.runTasklistUI = "yes"}}\nThe Camunda Tasklist UI works with both job-based or Zeebe-based
user tasks.\nIt does not require any technical migration from your side.
\n{{/if}}\nHowever, we still recommend to consider a migration as it might ease a future adoption of those features. \n
\n
Use Zeebe user tasks\nTo use task lifecycle features, change the implementation type of your user tasks to Zeebe user tasks.
\nWhile the Camunda Tasklist UI works with both job-based or Zeebe-based
user tasks,\nonly Zeebe-based user tasks support lifecycle features.
\n{{#if conditions.distribution = "sm"}}\n
\nIn addition, to use the task lifecycle events and metrics,\nconsider to implement a
custom exporter.\n{{/if}}\n
\n
Use Zeebe user tasks\nTo use task lifecycle features, change the implementation type of your user tasks to Zeebe user tasks.
\nThis requires you to migrate your custom task application(s) first to use the new Zeebe API for user tasks.
\nWe recommend you to either
\n
\n- Upgrade your dev cluster to 8.5, migrate your task application(s) on dev, and migrate your processes step-by-step on dev. \n Once done and tested, move over to production. Recommended for small to mid-size projects.
\n- Upgrade your dev and prod cluster to 8.5 and write an adapter layer that routes task operation calls to the respective API\n(existing job-based tasks to the Tasklist API, and Zeebe-based tasks to the Zeebe Task API). The Tasklist query API returns the task implementation type\nrequired for the routing. Using this approach, you can migrate each process step-by-step to production, and operate both types at the same. \nThis approach is recommended for larger projects and ensures smoothest migration without interrupting operations and continous delivery.
\n
\n{{#if conditions.distribution = "sm"}}\nIn addition, to use the task lifecycle events and metrics,\nconsider to implement a
custom exporter.\n{{/if}}\n
\n
Read more
\nTODO\n\n{{/if}}\n',
+ '\n\n\n{{#if conditions.useUserTasks = "no" or (conditions.runCustomTaskApp = "no" and conditions.runTasklistUI = "no") }}\n\nNothing to do for you!
\nSince you do not use user tasks, you do not have to worry about migrating them.
\nHowever, if you plan to introduce them at any point in time, you can refer to this decision helper again.\n
\n{{/if}}\n\n{{#if conditions.runCustomTaskApp = "notYet" and conditions.runTasklistUI = "yes" and conditions.requireLifecycle != null }}\n\nUse Camunda user tasks
\nAs you plan to introduce a custom task application, \nuse "Camunda user tasks" as the implementation type for your user tasks.\n
\nFirst switch the implementation type of all your user tasks to "Camunda user tasks",\nbefore you start developing your custom task application. \nJob-based user tasks are not supported in the Zeebe API for user tasks.
\nYou can safely migrate your existing user tasks to the new task type,\nsince the Camunda Tasklist UI supports both task types.\n
\n{{/if}}\n\n{{#if conditions.runCustomTaskApp = "notYet" and conditions.runTasklistUI = "no" }}\n\nUse Camunda user tasks
\nAs you plan to introduce a custom task application, \nuse "Camunda user tasks" as the implementation type for your user tasks.\n
\n{{/if}}\n\n{{#if conditions.requireLifecycle = "no" and conditions.runCustomTaskApp != "notYet"}}\n\n
No immediate action needed\nSince you do not plan to use task lifecycle features, there is no urgent need for you to migrate.
\n{{#if conditions.runTasklistUI = "yes"}}\nThe Camunda Tasklist UI works with both job-based or Zeebe-based
user tasks.\nIt does not require any technical migration from your side.
\n{{/if}}\nHowever, we still recommend to consider a migration as it might ease a future adoption of those features. \n
\n
Use Camunda user tasks\nTo use task lifecycle features, change the implementation type of your user tasks to Camunda user tasks.
\nWhile the Camunda Tasklist UI works with both job-based or Zeebe-based
user tasks,\nonly Zeebe-based user tasks support lifecycle features.
\n{{#if conditions.distribution = "sm"}}\n
\nIn addition, to use the task lifecycle events and metrics,\nconsider to implement a
custom exporter.\n{{/if}}\n
\n
Use Camunda user tasks\nTo use task lifecycle features, change the implementation type of your user tasks to Camunda user tasks.
\nThis requires you to migrate your custom task application(s) first to use the new Zeebe API for user tasks.
\nWe recommend you to either
\n
\n- Upgrade your dev cluster to 8.5, migrate your task application(s) on dev, and migrate your processes step-by-step on dev. \n Once done and tested, move over to production. Recommended for small to mid-size projects.
\n- Upgrade your dev and prod cluster to 8.5 and write an adapter layer that routes task operation calls to the respective API\n(existing job-based tasks to the Tasklist API, and Zeebe-based tasks to the Zeebe Task API). The Tasklist query API returns the task implementation type\nrequired for the routing. Using this approach, you can migrate each process step-by-step to production, and operate both types at the same. \nThis approach is recommended for larger projects and ensures smoothest migration without interrupting operations and continous delivery.
\n
\n{{#if conditions.distribution = "sm"}}\nIn addition, to use the task lifecycle events and metrics,\nconsider to implement a
custom exporter.\n{{/if}}\n
\n
Read more
\nTODO\n\n{{/if}}\n',
label: "HTML",
type: "html",
layout: {
diff --git a/docs/apis-tools/tasklist-api-rest/assets/img/camunda-user-task-selection.png b/docs/apis-tools/tasklist-api-rest/assets/img/camunda-user-task-selection.png
new file mode 100644
index 00000000000..ed83b9a52af
Binary files /dev/null and b/docs/apis-tools/tasklist-api-rest/assets/img/camunda-user-task-selection.png differ
diff --git a/docs/apis-tools/tasklist-api-rest/assets/img/zeebe-user-task-selection.png b/docs/apis-tools/tasklist-api-rest/assets/img/zeebe-user-task-selection.png
deleted file mode 100644
index 88b540d9286..00000000000
Binary files a/docs/apis-tools/tasklist-api-rest/assets/img/zeebe-user-task-selection.png and /dev/null differ
diff --git a/docs/apis-tools/tasklist-api-rest/specifications/search-tasks.api.mdx b/docs/apis-tools/tasklist-api-rest/specifications/search-tasks.api.mdx
index e8e2b223ace..9a6fa3c735a 100644
--- a/docs/apis-tools/tasklist-api-rest/specifications/search-tasks.api.mdx
+++ b/docs/apis-tools/tasklist-api-rest/specifications/search-tasks.api.mdx
@@ -55,7 +55,7 @@ An array used to specify a list of variable names that should be included in the
Array [
]
priority object
-Rules to filter out tasks by their priority. Applicable only for Zeebe user tasks.
+Rules to filter out tasks by their priority. Applicable only for Camunda user tasks.
diff --git a/docs/apis-tools/zeebe-api-rest/tutorial.md b/docs/apis-tools/zeebe-api-rest/tutorial.md
new file mode 100644
index 00000000000..f6dabb65736
--- /dev/null
+++ b/docs/apis-tools/zeebe-api-rest/tutorial.md
@@ -0,0 +1,182 @@
+---
+id: zeebe-api-tutorial
+title: Tutorial
+description: "New to the Zeebe API? Step through our tutorial to assign and unassign a user to and from a Camunda user task."
+---
+
+In this tutorial, we'll step through examples to highlight the capabilities of the Zeebe API, such as assigning and unassigning a user to and from a job worker-based user task managed by Camunda, also known as a Camunda user task.
+
+## Prerequisites
+
+- If you haven't done so already, [create a cluster](/guides/create-cluster.md).
+- Upon cluster creation, [create your first client](/guides/setup-client-connection-credentials.md). Ensure you check the `Zeebe` client scope box.
+
+:::note
+Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer.
+:::
+
+- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.
+- Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies.
+
+## Getting started
+
+- You need authentication to access the API endpoints. Find more information [here](./zeebe-api-rest-authentication.md).
+
+## Set up authentication
+
+If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client id and client secret. Then, we return the actual token that can be passed as an authorization header in each request.
+
+To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add your `ZEEBE_CLIENT_ID`, `ZEEBE_CLIENT_SECRET`, `ZEEBE_BASE_URL`, and `ZEEBE_AUDIENCE`, which is `zeebe.camunda.io` in a Camunda 8 SaaS environment. For example, your audience may be defined as `ZEEBE_AUDIENCE=zeebe.camunda.io`.
+
+These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites).
+
+Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.
+
+:::note
+
+In this tutorial, we will execute arguments to assign and unassign a user to and from a Camunda user task. You can examine the framework for processing these arguments in the `cli.js` file before getting started.
+
+:::
+
+## Assign a Camunda user task (POST)
+
+:::note
+In this tutorial, you will capture a **Camunda user task** ID to assign and unassign users in this API. Camunda 8.5 introduced this new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type, and these Camunda user tasks are different from job worker-based user tasks. To learn more about task type differences, see [migrating to Camunda user tasks](/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md#task-type-differences).
+:::
+
+First, let's script an API call to assign a Camunda user task.
+
+To do this, take the following steps:
+
+1. In the file named `zeebe.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls:
+
+```javascript
+const authorizationConfiguration = {
+ clientId: process.env.ZEEBE_CLIENT_ID,
+ clientSecret: process.env.ZEEBE_CLIENT_SECRET,
+ audience: process.env.ZEEBE_AUDIENCE,
+};
+```
+
+2. Examine the function `async function assignUser([userTaskKey, assignee])` below this configuration. This is where you will script out your API call.
+3. Within the function, you must first generate an access token for this request, so your function should now look like the following:
+
+```javascript
+async function assignUser([userTaskKey, assignee]) {
+ const accessToken = await getAccessToken(authorizationConfiguration);
+}
+```
+
+4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Zeebe API URL beneath your call for an access token by defining `zeebeApiUrl`:
+
+`const zeebeApiUrl = process.env.ZEEBE_BASE_URL`
+
+5. On the next line, script the API endpoint to assign a Camunda user task:
+
+```javascript
+const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignment`;
+```
+
+6. Configure your POST request to the appropriate endpoint, including an authorization header based on the previously acquired `accessToken`:
+
+```javascript
+const options = {
+ method: "POST",
+ url,
+ headers: {
+ Accept: "application/json",
+ Authorization: `Bearer ${accessToken}`,
+ },
+ data: {
+ // The body contains information about the new assignment.
+ assignee: assignee,
+ },
+};
+```
+
+7. Call the assign endpoint, process the results from the API call, and emit an error message from the server if necessary:
+
+```javascript
+try {
+ // Call the assign endpoint.
+ const response = await axios(options);
+
+ // Process the results from the API call.
+ if (response.status === 204) {
+ console.log(`User task assigned to ${assignee}.`);
+ } else {
+ // Emit an unexpected error message.
+ console.error("Unable to assign this user!");
+ }
+} catch (error) {
+ // Emit an error from the server.
+ console.error(error.message);
+}
+```
+
+1. In your terminal, run `node cli.js zeebe assign
`, where `` is the Camunda user task ID you've captured from Tasklist, and `` is the assignee's email address. Include your own email address if you would like to see these results in your user interface.
+
+:::note
+This `assign` command is connected to the `assignUser` function at the bottom of the `zeebe.js` file, and executed by the `cli.js` file. While we will assign and unassign users in this tutorial, you may add additional arguments depending on the API calls you would like to make.
+:::
+
+If you have a valid user and task ID, the assignment will now output. If you have an invalid API name or action name, or no arguments provided, or improper/insufficient credentials configured, an error message will output as outlined in the `cli.js` file. If no action is provided, it will default to "assign" everywhere, except when unassigning a user.
+
+## Unassign a Camunda user task (DELETE)
+
+To unassign a user from a Camunda user task, you can use the same Camunda user task ID from the previous exercise and take the following steps:
+
+1. Outline your function, similar to the steps above:
+
+```javascript
+async function unassignUser([userTaskKey]) {
+ const accessToken = await getAccessToken(authorizationConfiguration);
+
+ const ZeebeApiUrl = process.env.ZEEBE_BASE_URL;
+
+ const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignee`;
+}
+```
+
+2. Configure the API call using the DELETE method:
+
+```javascript
+const options = {
+ method: "DELETE",
+ url,
+ headers: {
+ Accept: "application/json",
+ Authorization: `Bearer ${accessToken}`,
+ },
+};
+```
+
+3. Process the results from the API call. For example:
+
+```javascript
+try {
+ // Call the delete endpoint.
+ const response = await axios(options);
+
+ // Process the results from the API call.
+ if (response.status === 204) {
+ console.log("User task has been unassigned!");
+ } else {
+ // Emit an unexpected error message.
+ console.error("Unable to unassign this user task!");
+ }
+} catch (error) {
+ // Emit an error from the server.
+ console.error(error.message);
+}
+```
+
+4. In your terminal, run `node cli.js zeebe unassign `, where `` is the Camunda user task ID.
+
+## If you get stuck
+
+Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `zeebe.js` file.
+
+## Next steps
+
+You can script several additional API calls as outlined in the [Zeebe API reference material](./zeebe-api-rest-overview.md).
diff --git a/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md b/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md
new file mode 100644
index 00000000000..22917565797
--- /dev/null
+++ b/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md
@@ -0,0 +1,29 @@
+---
+id: zeebe-api-rest-overview
+title: "Overview"
+description: "Interact with Zeebe clusters. Run user task state operations for Camunda user tasks."
+---
+
+## Introduction
+
+The Zeebe REST API is a REST API designed to interact with the Zeebe process automation engine.
+
+:::note
+Ensure you [authenticate](./zeebe-api-rest-authentication.md) before accessing the Zeebe REST API.
+:::
+
+## Context paths
+
+For SaaS: `https://${REGION}.zeebe.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
+
+:::note
+Find your region and cluster id under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
+
+For Self-Managed, the host and port depend on your configuration. The context path mentioned here is the default for the Zeebe component.
+:::
+
+## API Explorer
+
+See [the interactive Zeebe REST API Explorer][zeebe-api-explorer] for specifications, example requests and responses, and code samples of interacting with the Tasklist REST API.
+
+[zeebe-api-explorer]: ./specifications/zeebe-rest-api.info.mdx
diff --git a/docs/components/concepts/process-instance-migration.md b/docs/components/concepts/process-instance-migration.md
index 9e13aa0d367..8ba66dd1f0a 100644
--- a/docs/components/concepts/process-instance-migration.md
+++ b/docs/components/concepts/process-instance-migration.md
@@ -370,8 +370,8 @@ The following limitations exist that may be supported in future versions:
- An element that becomes nested in a newly added subprocess
- An element that was nested in a subprocess is no longer nested in that subprocess
- Mapping instructions cannot change the element type
-- Mapping instructions cannot change the task implementation, e.g. from a job worker user task to a Zeebe user task
-- The process instance must be in a wait state, i.e. waiting for an event or external input like job completion. It may not be taking a sequence flow or triggering an event while migrating the instance
+- Mapping instructions cannot change the task implementation, for example, from a job worker user task to a Camunda user task.
+- The process instance must be in a wait state, i.e. waiting for an event or external input like job completion. It may not be taking a sequence flow or triggering an event while migrating the instance.
A full overview of error codes can be found in the migration command [RPC](/apis-tools/zeebe-api/gateway-service.md#migrateprocessinstance-rpc) or [REST](/apis-tools/camunda-api-rest/specifications/migrate-process-instance.api.mdx).
diff --git a/docs/components/modeler/bpmn/user-tasks/user-tasks.md b/docs/components/modeler/bpmn/user-tasks/user-tasks.md
index 90a64a6191c..773dc0b22d6 100644
--- a/docs/components/modeler/bpmn/user-tasks/user-tasks.md
+++ b/docs/components/modeler/bpmn/user-tasks/user-tasks.md
@@ -12,19 +12,21 @@ When the user task instance is completed, the process instance continues.
-:::info
-Camunda 8 also supports the implementation of user tasks with a [service task](/components/modeler/bpmn/service-tasks/service-tasks.md)-like behavior.
-Refer to the [job worker implementation](#job-worker-implementation) section below.
-Version 8.4 and below are limited to the job worker implementation.
-:::
+## User task implementation types
+
+A default user task implementation type is the **Camunda user task** with the `zeebe:userTask` extension element.
+It is the recommended implementation type that is introduced on Camunda version 8.6.
-## Define a user task
+Alternatively, user tasks can be implemented with **Job workers** by removing the `zeebe:userTask` extension element.
+Refer to the [Job worker implementation](#job-worker-implementation) section for details.
-A user task is marked as a **Zeebe user task** by the `zeebe:userTask` extension element. Without the `zeebe:userTask` extension element, the user task behaves like a [service task](#job-worker-implementation).
+## Camunda user tasks
-You can define assignments, scheduling, variable mappings, and a form for the user task as detailed in the following sections.
+Camunda user tasks support assignments, scheduling, task updates, variable mappings, and a form for a user task as detailed in the following sections.
-The [job worker implementation](#job-worker-implementation) section details the differences and limitations of job worker-based user tasks.
+:::note
+The Camunda user task implementation type was previously referred to as the **Zeebe user task**.
+:::
### Assignments
@@ -98,7 +100,7 @@ To set the priority of a user task, specify the priority in the `priority` attri
### Variable mappings
-By default, all Zeebe user task variables are merged into the process instance. This
+By default, all Camunda user task variables are merged into the process instance. This
behavior can be customized by defining an output mapping at the user task.
Input mappings can be used to transform the variables into a different format.
@@ -158,21 +160,22 @@ configuration parameters for tasklist applications.
## Job worker implementation
-A user task does not have to be managed by Zeebe. Instead, you can also use
-job workers to implement a custom user task logic. Note that you will lose all the task lifecycle and state management features that Zeebe provides and will have to implement them yourself. Use job workers only in case you require a very specific implementation of user tasks that can't be implemented on top of Zeebe user tasks.
+A user task does not have to be managed by Zeebe. You can implement custom user task logic using Job workers.
+
+To define a Job worker implementation for a user task, simply remove the `zeebe:userTask` extension element from the task. User tasks implemented via Job workers behave similarly to service tasks, with two key differences:
+
+- Visual representation: The visual marker distinguishes user tasks from service tasks.
+- Model semantics: The interpretation and purpose in the process model differ.
:::info
-If you started using Camunda 8 with version 8.4 or a lower version and upgraded to 8.5 or newer, your user tasks are probably implemented as job workers. Refer to the [migration guide](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md) to find a detailed list of the differences between the task implementation types and learn how to migrate to Zeebe user tasks.
+The job worker implementation for user tasks is deprecated. We recommend using [Camunda user tasks](#camunda-user-tasks) instead for enhanced functionality and adherence to best practices. For a detailed comparison of task implementation types and guidance on migrating to Camunda user tasks, see the [migration guide](/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md).
:::
-You can define a job worker implementation for a user task by removing its `zeebe:userTask` extension element.
-
-User tasks with a job worker implementation behave exactly like [service tasks](/components/modeler/bpmn/service-tasks/service-tasks.md). The differences between these task
-types are the visual representation (i.e. the task marker) and the semantics for the model.
+When a process instance reaches a user task with a Job worker implementation:
-When a process instance enters a user task with job worker implementation, it creates
-a corresponding job and waits for its completion. A job worker should request jobs of the job type `io.camunda.zeebe:userTask`
-and process them. When the job is completed, the process instance continues.
+1. Zeebe creates a corresponding job and waits for its completion.
+2. A Job worker processes jobs of the type io.camunda.zeebe:userTask.
+3. Once the job is completed, the process instance resumes execution.
Use [task headers](/components/modeler/bpmn/service-tasks/service-tasks.md#task-headers) to pass static parameters to the job
worker.
@@ -183,16 +186,19 @@ to transform the variables passed to the job worker, or to customize how the var
### Limitations
-User tasks based on a job worker implementation provide no insight into the lifecycle of the task in the engine.
-You need to manage the user task's lifecycle in your own application outside the engine.
-This also limits available metrics and reporting for such user tasks to what is available for service tasks.
+User tasks implemented using Job workers come with significant limitations when compared to [Camunda user tasks](#camunda-user-tasks):
+
+1. **API compatibility**:
+ You cannot use the [Camunda 8 API](/docs/apis-tools/camunda-api-rest/camunda-api-rest-overview.md) to manage user tasks based on Job workers. These tasks are restricted to the functionality provided for [service tasks](/components/modeler/bpmn/service-tasks/service-tasks.md). Job worker-based user tasks can only be managed using the deprecated [Tasklist API](/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) or [Zeebe API](/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md).
+
+2. **Lifecycle management**:
+ The Zeebe engine provides no visibility into lifecycle and state management features of Job worker-based user tasks. This means that you must handle these aspects in your custom application, outside the engine. Consider this approach only if your use case requires a highly specific user task implementation that cannot be achieved with Camunda user tasks.
-All user task-specific data like assignments and scheduling information is provided in the job as
-[task headers](/components/modeler/bpmn/service-tasks/service-tasks.md#task-headers).
+3. **Reduced metrics and reporting**:
+ Metrics and reporting for such user tasks are limited to the capabilities available for service tasks. This means you lose access to user task-specific insights provided by the Zeebe engine.
-You cannot use the Camunda 8 Zeebe User Task API to work on user tasks based on job workers.
-Overall, you are limiting those user tasks to the capabilities of [service tasks](/components/modeler/bpmn/service-tasks/service-tasks.md).
-Zeebe user task-specific features are not available to those user tasks.
+4. **Task-specific operations**:
+ Assignments, scheduling, and other user task-specific details are included in the job as [task headers](/components/modeler/bpmn/service-tasks/service-tasks.md#task-headers). These must be handled in your custom implementation. Advanced user task features offered by Camunda are not available for Job worker-based user tasks.
## Additional resources
diff --git a/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md b/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md
index cf43c6b50c5..2c2bb1f251e 100644
--- a/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md
+++ b/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md
@@ -90,7 +90,7 @@ To correct any instances affected by this issue, we recommend the following step
### Camunda Form (embedded)
:::info
-Embedded forms are supported only by job worker-based user tasks and are not available for the [Zeebe user task implementation type](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-implementation-types).
+Embedded forms are only supported for job worker-based user tasks. They are not available for the [Camunda user task implementation type](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-implementation-types).
:::
When choosing **Camunda Form (embedded)** as type you have the option to directly paste the form's JSON schema into the **Form JSON configuration** field of the properties panel.
diff --git a/docs/reference/announcements/870.md b/docs/reference/announcements/870.md
index cf4c795311c..b7aeb54749f 100644
--- a/docs/reference/announcements/870.md
+++ b/docs/reference/announcements/870.md
@@ -35,12 +35,12 @@ The deprecation process for the [Operate](/apis-tools/operate-api/overview.md) a
- Version 8.7, 8.8: These APIs are still available but deprecated, and so not recommended for new implementations.
- Version 8.9: These APIs will be removed.
-### Deprecated: Job-based User Tasks querying
+### Deprecated: Job-based user tasks querying
-As `Job-worker` user tasks will be deprecated in Camunda 8.9, Camunda recommends you start using `Camunda User Tasks` (formerly known as `Zeebe User Task`) in your process definitions.
+As **job-worker** user tasks will be deprecated with Camunda 8.9, Camunda recommends using **Camunda user tasks** (formerly known as **Zeebe user tasks**) in your process definitions. Note that you may still see references of **Zeebe user tasks** in your XML, but this is the same thing as Camunda user tasks.
-- Version 8.7, 8.8: `Job-worker` user tasks are available for querying, but Camunda modelers automatically apply the `Camunda user task` and show a warning message for each job worker user task.
-- Version 8.9: `Job-worker` user tasks will be deprecated. With Camunda 8.9 and later, customers can use the `Job-worker` implementation of user tasks as standard jobs with headers to enable open architecture and composable solutions.
+- Version 8.7, 8.8: **Job-worker** user tasks are available for querying, but Camunda Modeler automatically applies the **Camunda user task** and shows a warning message for each job worker user task.
+- Version 8.9: **Job-worker** user tasks will be deprecated. With Camunda 8.9+, customers can use the **job-worker** implementation of user tasks as standard jobs with headers to enable open architecture and composable solutions.
### Deprecated: Zeebe gRPC API endpoints
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
index 0ed65c96669..29220d9dfea 100644
--- a/docs/reference/glossary.md
+++ b/docs/reference/glossary.md
@@ -274,7 +274,12 @@ This way, a Camunda workflow can receive messages from an external system or ser
A user task is used to model work that needs to be done by a human and is assisted by a business process execution engine or software application. This differs from [manual tasks](/components/modeler/bpmn/manual-tasks/manual-tasks.md), which are not assisted by external tooling.
+With 8.7, Camunda offers job worker-based user tasks managed by Camunda, also known as Camunda user tasks (and formerly known as Zeebe user tasks). Note that you may still see references of **Zeebe user tasks** in your XML, but this is the same thing as Camunda user tasks.
+
+Camunda recommends using Camunda user tasks in your process definitions. With 8.7, **job-worker** user tasks are available for querying, but Camunda Modeler automatically applies the **Camunda user task** and shows a warning message for each job worker user task.
+
- [User tasks](/components/modeler/bpmn/user-tasks/user-tasks.md)
+- [Migrate to Camunda user tasks](/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md)
### Webhook Connector
diff --git a/docs/reference/release-notes/850.md b/docs/reference/release-notes/850.md
index d514f55adca..23e61dd0d92 100644
--- a/docs/reference/release-notes/850.md
+++ b/docs/reference/release-notes/850.md
@@ -108,7 +108,7 @@ The first iteration of this feature brings back existing features from Camunda 7
-The first step to offer an intuitive and consistent experience via a single, [unified Camunda 8 REST API](https://camunda.com/blog/2024/03/streamlining-camunda-apis-zeebe-rest-api/) is to provide the Zeebe REST API. With this release, developers can use the Zeebe REST API to manage [Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md), enabling immediate task state changes. The Zeebe REST API includes support for Identity authentication and multi-tenancy, ensuring parity to the Zeebe gRPC API.
+The first step to offer an intuitive and consistent experience via a single, [unified Camunda 8 REST API](https://camunda.com/blog/2024/03/streamlining-camunda-apis-zeebe-rest-api/) is to provide the Zeebe REST API. With this release, developers can use the Zeebe REST API to manage [Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md), enabling immediate task state changes. The Zeebe REST API includes support for Identity authentication and multi-tenancy, ensuring parity to the Zeebe gRPC API.
### Refactoring suggestions Modeler
diff --git a/optimize/components/userguide/process-analysis/user-task-analytics.md b/optimize/components/userguide/process-analysis/user-task-analytics.md
index 10911b005b5..f11de691d46 100644
--- a/optimize/components/userguide/process-analysis/user-task-analytics.md
+++ b/optimize/components/userguide/process-analysis/user-task-analytics.md
@@ -57,7 +57,7 @@ To evaluate user tasks, the following features are available in the report build
- Currently, user task analytics can be used only with assigned or unassigned time. We are working on analyzing net-work time.
- This will only work with Tasklist and custom task applications implementing the complete [Camunda Tasklist Lifecycle]($docs$/apis-tools/frontend-development/task-applications/introduction-to-task-applications/).
-- User task analytics only work correctly if all user tasks in a process are of type `Zeebe user task`. The `Job worker` user type does not contain task lifecycle information and is therefore not displayed in the view `User tasks` view.
+- User task analytics only work correctly if all user tasks in a process are of type `Camunda user task` (formerly Zeebe user task). The `job worker` user type does not contain task lifecycle information and is therefore not displayed in the `User tasks` view.
:::
diff --git a/optimize/self-managed/optimize-deployment/configuration/system-configuration-platform-8.md b/optimize/self-managed/optimize-deployment/configuration/system-configuration-platform-8.md
index f89a7ad4d52..f90787423b3 100644
--- a/optimize/self-managed/optimize-deployment/configuration/system-configuration-platform-8.md
+++ b/optimize/self-managed/optimize-deployment/configuration/system-configuration-platform-8.md
@@ -43,7 +43,7 @@ To use multi-tenancy, the feature must be enabled across all components.
| multitenancy.enabled | false | Enables the Camunda 8 multi-tenancy feature in Optimize. |
| security.auth.ccsm.baseUrl | null | The base URL of Identity. |
-### Settings related to Camunda 8 Zeebe user tasks
+### Settings related to Camunda user tasks (formerly Zeebe user tasks)
Camunda 8 Self-Managed only
diff --git a/sidebars.js b/sidebars.js
index edd1d995612..3e8146c8eb0 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -887,7 +887,7 @@ module.exports = {
},
{
"Migration manuals": [
- "apis-tools/migration-manuals/migrate-to-zeebe-user-tasks",
+ "apis-tools/migration-manuals/migrate-to-camunda-user-tasks",
"apis-tools/migration-manuals/migrate-to-camunda-api",
],
},
diff --git a/static/.htaccess b/static/.htaccess
index d0fdc799642..34d8a3d6b17 100644
--- a/static/.htaccess
+++ b/static/.htaccess
@@ -102,7 +102,7 @@ RewriteRule ^docs/next/apis-tools/zeebe-api-rest/zeebe-api-rest-authentication/?
RewriteRule ^docs/next/apis-tools/zeebe-api-rest/zeebe-api-tutorial/?$ /docs/next/apis-tools/camunda-api-rest/camunda-api-rest-overview/$1 [R=301,L]
# Move migrating to Zeebe user tasks
-RewriteRule ^docs/next/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks/?$ /docs/next/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks/$1 [R=301,L]
+RewriteRule ^docs/next/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks/?$ /docs/next/apis-tools/migration-manuals/migrate-to-camunda-user-tasks/$1 [R=301,L]
RewriteRule ^docs/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks/?$ /docs/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks/$1 [R=301,L]
RewriteRule ^docs/8.6/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks/?$ /docs/8.6/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks/$1 [R=301,L]
diff --git a/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/01-introduction-to-task-applications.md b/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/01-introduction-to-task-applications.md
index 9f29b2dc237..3d343cdcc74 100644
--- a/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/01-introduction-to-task-applications.md
+++ b/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/01-introduction-to-task-applications.md
@@ -59,7 +59,7 @@ Task details are shown when a task is selected from the queue. A [form](/guides/
:::tip
Typically, a task application utilizes forms to capture information from the user, to make a decision, to collect the results from a real-world task, or to provide task instructions to the user.
-However, a [user task](/components/modeler/bpmn/user-tasks/user-tasks.md/#user-task-forms) is not limited to forms. A user task could also represent navigating to an external desktop or web application, where a task is to be performed, such as updating a record in a CRM. You can even use them to track physical work or actions using sensors, IoT devices, or any interface that can talk to the web, by using the [APIs](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) or registering a [job worker](/components/concepts/job-workers.md) to the job type `io.camunda.zeebe:userTask` (compatible with [job worker-based user tasks](/components/modeler/bpmn/user-tasks/user-tasks.md) only).
+However, a [user task](/components/modeler/bpmn/user-tasks/user-tasks.md/#user-task-forms) is not limited to forms. A user task could also represent navigating to an external desktop or web application, where a task is to be performed, such as updating a record in a CRM. You can even use them to track physical work or actions using sensors, IoT devices, or any interface that can talk to the web, by using the [APIs](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) or registering a [job worker](/components/concepts/job-workers.md) to the job type `io.camunda.zeebe:userTask` (compatible with [job worker-based user tasks](/components/modeler/bpmn/user-tasks/user-tasks.md) only). However, note that job worker-based user tasks are deprecated with Camunda 8.6. While these are currently still supported, consider [migrating to Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md).
For these cases, utilize the flexible [custom form key](/components/modeler/web-modeler/advanced-modeling/form-linking.md/#custom-form-key).
:::
diff --git a/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/03-task-application-architecture.md b/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/03-task-application-architecture.md
index b0027b95827..55323053473 100644
--- a/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/03-task-application-architecture.md
+++ b/versioned_docs/version-8.6/apis-tools/frontend-development/01-task-applications/03-task-application-architecture.md
@@ -80,6 +80,6 @@ click ZeebeRest "../../../zeebe-api-rest/zeebe-api-rest-overview"
Follow these resources to learn more about the individual components:
- Learn how to use the [Camunda 8 API](/apis-tools/camunda-api-rest/specifications/assign-user-task.api.mdx) for task, variable, and form retrieval, and to run operations on Zeebe user tasks.
-- Familiarize yourself with the [Tasklist API](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) to run operations on job worker-based user tasks.
+- Familiarize yourself with the [Tasklist API](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) to run operations on job worker-based user tasks. However, note that job worker-based user tasks are deprecated with Camunda 8.6. While these are currently still supported, consider [migrating to Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md).
- Understand how to design, embed, and customize [forms](/apis-tools/frontend-development/03-forms/01-introduction-to-forms.md).
- Understand how this architecture fits into the overall Camunda architecture with the [Java greenfield stack](/components/best-practices/architecture/deciding-about-your-stack.md).
diff --git a/versioned_docs/version-8.6/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md b/versioned_docs/version-8.6/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md
index d1f19118f98..b3d1722d537 100644
--- a/versioned_docs/version-8.6/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md
+++ b/versioned_docs/version-8.6/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md
@@ -16,7 +16,7 @@ import ZeebeTaskSelectionImg from '../tasklist-api-rest/assets/img/zeebe-user-ta
Camunda 8.5 introduced a new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type: Zeebe user tasks.
-Zeebe user tasks have several benefits compared to job worked-based user tasks. It includes:
+Zeebe user tasks have several benefits compared to job worked-based user tasks (which while still supported, are now deprecated with 8.6). Such benefits include:
- Running directly on the automation engine for high performance.
- Removing dependencies and round trips to Tasklist.
diff --git a/versioned_docs/version-8.6/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md b/versioned_docs/version-8.6/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md
index 31bedd5f7cd..c7de8fb7b05 100644
--- a/versioned_docs/version-8.6/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md
+++ b/versioned_docs/version-8.6/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md
@@ -8,7 +8,7 @@ description: "Build applications for human-centered processes by querying user t
:::note
Camunda introduced the [Camunda 8 REST API](/apis-tools/camunda-api-rest/camunda-api-rest-overview.md) with `8.6` to manage and query process entities such as processes, decisions, forms, and user tasks.
-Camunda has also introduced [Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md) to build more advanced functionalities. If you use Zeebe user tasks with `8.6`, task management endpoints in the Tasklist API will not work.
+Job worker-based user tasks are deprecated with Camunda 8.6. While these are currently still supported, Camunda has also introduced [Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md) to build more advanced functionalities. If you use Zeebe user tasks with `8.6`, task management endpoints in the Tasklist API will not work.
:::
## Introduction
diff --git a/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/tutorial.md b/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/tutorial.md
index 2bb1795037a..36d9be4c625 100644
--- a/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/tutorial.md
+++ b/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/tutorial.md
@@ -41,7 +41,7 @@ In this tutorial, we will execute arguments to assign and unassign a user to and
## Assign a Zeebe user task (POST)
:::note
-In this tutorial, you will capture a **Zeebe user task** ID to assign and unassign users in this API. Camunda 8.5 introduced this new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type, and these Zeebe user tasks are different from job worker-based user tasks. See more details on task type differences in the [migrating to Zeebe user tasks documentation](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md#task-type-differences).
+In this tutorial, you will capture a **Zeebe user task** ID to assign and unassign users in this API. Camunda 8.5 introduced this new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type, and these Zeebe user tasks are different from job worker-based user tasks (which while still supported, are now deprecated with 8.6). See more details on task type differences in the [migrating to Zeebe user tasks documentation](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md#task-type-differences).
:::
First, let's script an API call to assign a Zeebe user task.
diff --git a/versioned_docs/version-8.6/components/modeler/bpmn/user-tasks/user-tasks.md b/versioned_docs/version-8.6/components/modeler/bpmn/user-tasks/user-tasks.md
index 90a64a6191c..cef90cd1f2f 100644
--- a/versioned_docs/version-8.6/components/modeler/bpmn/user-tasks/user-tasks.md
+++ b/versioned_docs/version-8.6/components/modeler/bpmn/user-tasks/user-tasks.md
@@ -26,6 +26,10 @@ You can define assignments, scheduling, variable mappings, and a form for the us
The [job worker implementation](#job-worker-implementation) section details the differences and limitations of job worker-based user tasks.
+:::note
+With 8.6, job worker-based user tasks are now deprecated. While these are currently still supported, consider [migrating to Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md).
+:::
+
### Assignments
User tasks support specifying assignments, using the `zeebe:AssignmentDefinition` extension element.
diff --git a/versioned_docs/version-8.6/components/modeler/web-modeler/advanced-modeling/form-linking.md b/versioned_docs/version-8.6/components/modeler/web-modeler/advanced-modeling/form-linking.md
index cf43c6b50c5..4f558fe9ca8 100644
--- a/versioned_docs/version-8.6/components/modeler/web-modeler/advanced-modeling/form-linking.md
+++ b/versioned_docs/version-8.6/components/modeler/web-modeler/advanced-modeling/form-linking.md
@@ -90,7 +90,7 @@ To correct any instances affected by this issue, we recommend the following step
### Camunda Form (embedded)
:::info
-Embedded forms are supported only by job worker-based user tasks and are not available for the [Zeebe user task implementation type](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-implementation-types).
+Embedded forms are supported only by job worker-based user tasks and are not available for the [Zeebe user task implementation type](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-implementation-types). However, job worker-based user tasks are now deprecated with 8.6. While these are currently still supported, consider [migrating to Zeebe user tasks](/apis-tools/migration-manuals/migrate-to-zeebe-user-tasks.md).
:::
When choosing **Camunda Form (embedded)** as type you have the option to directly paste the form's JSON schema into the **Form JSON configuration** field of the properties panel.