4238 - Documentation for task priority

docs/components/modeler/bpmn/user-tasks/user-tasks.md

@@ -83,6 +83,14 @@ import ISO8601DateTime from '../assets/react-components/iso-8601-date-time.md'
 <ISO8601DateTime/>
 :::
 
+### Defining a priority
+
+User tasks support specifying a priority using the `zeebe:priorityDefinition` extension element. This enables you to prioritize a user task relative to other tasks within the same process, as well as across different processes.
+
+To assign a priority to a user task, you must specify it using the `priority` attribute. The priority must be an integer between `0` and `100`.If not provided, the default value is `50`.
+
+You can set the priority either as a static integer value or by using an [expression](/components/concepts/expressions.md). Expressions are evaluated when the user task is activated and must result in an integer within the specified range.
+
 ### Variable mappings
 
 By default, all Zeebe user task variables are merged into the process instance. This

docs/components/tasklist/introduction-to-tasklist.md

@@ -6,7 +6,7 @@ description: "Orchestrate human workflows critical to your business with an out-
 
 Tasklist is a ready-to-use application to rapidly implement business processes alongside [user tasks](/components/modeler/bpmn/user-tasks/user-tasks.md).
 
-With Tasklist, orchestrate human workflows critical to your business and reduce time-to-value for your process orchestration projects with an out-of-the-box interface for manual work.
+With Tasklist you can orchestrate human workflows critical to your business and reduce time-to-value for your process orchestration projects with an out-of-the-box interface.
 
 As you model a business process using BPMN and deploy it to the [Zeebe](/docs/components/zeebe/zeebe-overview.md) engine, users are notified in Tasklist when they're assigned a task, and run the work that's required for the specific task.
 

docs/components/tasklist/userguide/defining-task-priorities.md

@@ -0,0 +1,51 @@
+---
+id: defining-task-priorities
+title: Defining task priorities
+description: "Bring your tasks in order by having clear prioritization."
+---
+
+import styles from "./styles.module.css";
+
+A [User Task event](/docs/next/components/modeler/bpmn/user-tasks) supports specifying a priority as an integer value. It determines the task's importance in relation to other tasks within processes.
+
+The supported priority values range from 0 to 100, with a default value of 50. A higher priority value indicates higher importance.
+
+When displayed in Tasklist, priority values are mapped to the following default labels:
+
+- 0-25: **Low**
+- 26-50: **Medium**
+- 51-75: **High**
+- 76-100: **Critical**
+
+These labels give Tasklist users a clear view of tasks, making it easier to assess a task's urgency. They also make sorting and filtering simple, helping users prioritize the most important tasks.
+
+## Step-by-step guide
+
+Below are the instructions on how to define task priorities for Tasklist users.
+
+### 1. Model a BPMN Process
+
+Begin by modeling your BPMN process in the Modeler. Ensure that necessary user tasks are defined within the process.
+
+### 2. Set a Priority for User Tasks
+
+While configuring a user task, you can assign a priority value. It can be defined via an expression.
+The priority value determines the task's importance relative to others.
+
+![set-user-task-priority-in-modeler](img/modeler-user-task-priority.jpg)
+
+### 3. Deploy and Start the Process
+
+Once the process is fully defined and all configurations are complete, it can be deployed and started. The priority values are now associated with each user task within the process.
+
+### 4. Task Priority in Tasklist
+
+Tasklist users can view the tasks assigned to them within their task list. Each task card displays the assigned priority label, ensuring users have a clear understanding of the task's importance.
+
+![set-user-task-priority-in-modeler](img/tasklist–tasks-with-priority.jpg)
+
+### 5. Sort Tasks by Priority
+
+Task users can sort tasks by priority. This functionality helps them organize their workload by focusing on urgent items first.
+
+![set-user-task-priority-in-modeler](img/tasklist-tasks-with-priority-sorting.jpg)

docs/components/tasklist/userguide/tasklist-get-started.md → docs/components/tasklist/userguide/managing-tasks.md

@@ -1,6 +1,6 @@
 ---
-id: tasklist-get-started
-title: Getting started
+id: managing-tasks
+title: Managing tasks
 description: "How to assign and complete tasks in Tasklist."
 ---
 

docs/components/tasklist/userguide/using-tasklist.md

@@ -8,25 +8,23 @@ import TasklistTasksPageSpecifications from '../img/tasklist-page-specifications
 import TaskTileSpecification from '../img/task-tile-specification.png';
 import styles from "./styles.module.css";
 
-Tasklist provides a user-friendly interface for managing and completing tasks that require manual interaction.
+Tasklist provides a user-friendly interface for managing and completing tasks that require manual interaction. It shows you all user tasks that appear in processes running in [Zeebe](/docs/components/zeebe/zeebe-overview.md).
 
-Tasklist shows you all user tasks that appear in processes running in [Zeebe](/docs/components/zeebe/zeebe-overview.md).
+:::info
+When a user is granted Tasklist access, the user has full access to the respective process instance data.
+:::
 
 The user interaction with a task may involve making updates, adding variables, filling out a [Camunda Form](../../../guides/utilizing-forms.md), or simply reviewing and completing the task.
 
 User tasks can be automatically assigned to users and groups in the BPMN process, or they must be self-assigned from Tasklist.
 Once assigned to a user, the task can be completed. The user can unassign the task if they do not intend to work on it.
 
-:::info
-When a user is granted Tasklist access, the user has full access to the respective process instance data.
-:::
-
-## Tasks overview
-
 Tasklist has two main pages:
 
-- Tasks page
-- [Processes page](./starting-processes.md)
+- [Tasks page](#tasks-overview) to manage tasks.
+- [Processes page](./starting-processes.md) to start processes.
+
+## Tasks overview
 
 The **Tasks** page lists all tasks available to a user or user group and allows users to assign themselves a task from the list to work on.
 
@@ -41,8 +39,9 @@ The queue shows the preview of available tasks with the following information:
 
 - Task name
 - Name of the process the task belongs to
-- Task context description ([can be optionally configured](/docs/components/concepts/variables.md#context-variable))
+- Task context description ([it can be optionally configured](/docs/components/concepts/variables.md#context-variable))
 - Assignee
+- Priority
 - Creation date
 - Due date
 - Follow up date
@@ -53,23 +52,25 @@ The queue shows the preview of available tasks with the following information:
 
 Select a task from the list to view its details.
 
+The task includes a form that has to be filled out and submitted to complete a task.
+
 ![tasklist-task-details-form](./img/tasklist-task-details-form.png "Task completion form")
 
-Tasks often include a form that has to be filled out and submitted to complete a task. If the task doesn’t have a form, it will display task variables.
+If the task doesn’t have a form, it will display task variables.
 
 ![tasklist-with-variables-claimed-by-me](img/tasklist-with-variables-claimed-by-me_light.png "Task variables")
 
 ### View process diagram
 
-From the task detail page you can switch to the **Processes** tab. This provides a visual representation of the BPMN diagram the task is part of, and may help you understand how an individual task fits into the larger workflow, what activities happened earlier, and what’s coming next.
+From the task detail page you can switch to the **Process** tab. This provides a visual representation of the BPMN diagram the task is part of, and may help you understand how an individual task fits into the larger workflow, what activities happened earlier, and what’s coming next.
 
 ![tasklist-process-diagram](./img/tasklist-task-details-process-diagram.png "Process diagram preview")
 
 :::note
 The diagram indicates the version of the process instance in which the task was initiated.
 :::
 
-#### Role-based access (RBA)
+#### Resource-based access (RBA)
 
 If your organization has RBA enabled, the process diagram will be displayed only to users that have permission to view process and decision definitions.
 
@@ -81,9 +82,10 @@ To group tasks and quickly find relevant assignments, use [task filters](./using
 
 ## Ordering
 
-Click the order icon ![order-icon](img/order-icon.png) to order the tasks. You can arrange them by the date of creation, the due date, or the follow-up date.
+Click the order icon ![order-icon](img/order-icon.png) to order the tasks. You can arrange them by the date of creation, due date, follow-up date, or priority.
+
+The follow-up date defines the latest time you should start working on a task. The due date provides a deadline for when the task should be finished.
 
-The follow-up date defines the latest time you should start working on a task, helping you prioritize work.
-The due date provides a deadline for when the task should be finished.
+The priority defines urgency of a task in relation to others.
 
 ![tasklist-task-ordering](img/tasklist-task-ordering.png "Order tasks by dates")

docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md

@@ -106,6 +106,12 @@ The following attributes/elements can be migrated:
   - `camunda:assignee` to `zeebe:assignmentDefinition assignee`
   - `camunda:candidateGroups` to `zeebe:assignmentDefinition candidateGroups`
   - `camunda:candidateUsers` to `zeebe:assignmentDefinition candidateUsers`
+- Task schedule:
+  - `camunda:dueDate` to `zeebe:taskSchedule dueDate`
+  - `camunda:followUpDate` to `zeebe:taskSchedule followUpDate`
+- Task priority:
+  - `camunda:priority` to `zeebe:priorityDefinition priority`
+- Form handling:
   - `camunda:formKey` to `zeebe:formDefinition formKey`, but Camunda 8 requires you to embed the form definition itself into the root element of your BPMN XML models, see [the user task documentation](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms).
   - `camunda:formRef` to `zeebe:formDefinition formId`
   - `camunda:formRefBinding` to `zeebe:formDefinition bindingType`
@@ -121,9 +127,6 @@ The following attributes/elements **cannot** yet be migrated:
   - `camunda:formProperty`
   - `camunda:formRefVersion`
 - `camunda:taskListener`
-- `camunda:dueDate`
-- `camunda:followUpDate`
-- `camunda:priority`
 
 ### Business rule tasks
 

optimize_sidebars.js

@@ -1162,13 +1162,17 @@ module.exports = {
               "components/tasklist/userguide/using-tasklist/"
             ),
             docsLink(
-              "Getting started",
-              "components/tasklist/userguide/tasklist-get-started/"
+              "Managing tasks",
+              "components/tasklist/userguide/managing-tasks/"
             ),
             docsLink(
               "Using filters",
               "components/tasklist/userguide/using-filters/"
             ),
+            docsLink(
+              "Defining task priorities",
+              "components/tasklist/userguide/defining-task-priorities/"
+            ),
             docsLink(
               "Starting processes",
               "components/tasklist/userguide/starting-processes/"

sidebars.js

@@ -433,8 +433,9 @@ module.exports = {
         {
           "User guide": [
             "components/tasklist/userguide/using-tasklist",
-            "components/tasklist/userguide/tasklist-get-started",
+            "components/tasklist/userguide/managing-tasks",
             "components/tasklist/userguide/using-filters",
+            "components/tasklist/userguide/defining-task-priorities",
             "components/tasklist/userguide/starting-processes",
           ],
         },