docs(frontend): Merge frontend-docs section into 8.4 (#3229)

* docs(frontend): Merge frontend-docs section into 8.4

* run prettier

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Steven Hicks <steven.j.hicks@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

versioned_docs/version-8.4/apis-tools/frontend-development/introduction-to-task-applications.md

@@ -0,0 +1,141 @@
+---
+id: introduction-to-task-applications
+title: "Introduction to task applications"
+description: "Task applications are the interface between humans and Camunda processes to orchestrate human work."
+---
+
+import TasklistProcessesImg from './img/tasklist-processes.png';
+import TasklistDetailsImg from './img/tasklist-details.png';
+import TaskAssignmentImg from './img/task-assignment.png';
+import TaskLifecycleImg from './img/task-lifecycle.png';
+import styles from "./styles.module.css";
+
+Task applications are the interface between humans and Camunda processes to orchestrate human work. Learn key concepts of the architecture of task applications before you build your own.
+
+:::note
+If you are not familiar with the idea of human task management itself, read the [introduction to human task management](/components/best-practices/architecture/understanding-human-tasks-management.md) first.
+:::
+
+## What are task applications?
+
+Task applications are end-user applications that allow humans to perform work orchestrated with a process. A [user task](/components/modeler/bpmn/user-tasks/user-tasks.md/#user-task-forms) (also referred to as a **human task**) represents a single **work item** to be performed by an individual or a group. The jobs of a task application include:
+
+- Listing available tasks and allowing users to select a task to work on.
+- Providing filter and search options for users so they can more easily find the right next task to work on.
+- Presenting the selected task and an interface for completing the task, usually via a form.
+- Providing an interface to create new tasks, e.g. by starting a new process.
+- Provide insight into the progress of work tasks, including processes and cases.
+- Aggregate information so users and their managers can assess the impact on process goals, such as KPIs and SLAs.
+- Ensure tasks are visible only to authorized users.
+
+Task applications play a key role in the orchestration of business processes. They enable the orchestration of processes that still contain manual work instead of automating each process step in advance. This unlocks the potential for continuous improvement and for identifying opportunities for process optimization and automation.
+
+:::tip
+Not sure if you should use Camunda Tasklist, build your custom task application, or use a third-party application? Read the [guide to understand human task management](/components/best-practices/architecture/understanding-human-tasks-management.md#deciding-about-your-task-list-frontend) first.
+:::
+
+## Tasklist layout
+
+Camunda 8 comes with a ready-to-use Tasklist UI that implements all key concepts of a task application. The Tasklist UI is a generic task application; your custom task application should probably be tailored to your specific use case and also include external data sources and tools.
+
+The Tasklist UI is split into two main pages: the [tasks page](#task-page) and the [processes page](#processes-page).
+
+### Task page
+
+The task page lists all tasks pending for a user or user group, and allows users to pick and claim a task from that queue to work on. On the same page, the details of a selected task are displayed including the form that the user must submit in order to execute and complete the task.
+
+The task page is divided into two panels, similar to the layout of messaging clients:
+
+<img src={TasklistDetailsImg} className={styles.noShadow} alt="Task details page in Tasklist" />
+
+#### Task queue side panel
+
+The **task queue side panel** lists all tasks \pending for a user or user group. It comes with filter and sort options that allow users to identify the right task to work on next. The tasks can be sorted by the creation date, due date, or follow-up date.
+
+Learn more how to work with the task queue in the [Tasklist user guide](/components/tasklist/userguide/using-tasklist.md).
+
+#### Task details panel
+
+The **task details panel** shows the details of the selected task. A [form](/guides/utilizing-forms.md) is displayed in the center of the details panel, which must be filled out to complete a task.
+
+:::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 registering a [job worker](/components/concepts/job-workers.md) to the job type `io.camunda.zeebe:userTask`.
+
+For these cases, utilize the flexible [custom form key](/components/modeler/web-modeler/advanced-modeling/form-linking.md/#custom-form-key).
+:::
+
+On the top of the form, a header shows the title of the task to work on, and the current assignee. Depending on the status of the assignment, a button allows you to assign the task to yourself or release it to the queue.
+
+At the bottom of the form there is a button with which you can complete the task.
+
+To the right of the task, you find additional information about the task, such as the [due date](/components/modeler/bpmn/user-tasks/user-tasks.md#scheduling) of the task, or the [user groups that can work on this task](/self-managed/concepts/access-control/user-task-access-restrictions.md).
+
+Potential extensions are dependent on your use case. You can consider adding more buttons to the bottom of the panel to indicate different task outcomes such as "approve" or "reject", or you could add a list of attachments to the right panel.
+
+Learn more how to work with the task details panel in the [Tasklist user guide](/components/tasklist/userguide/using-tasklist.md).
+
+### Processes page
+
+The **Processes** page lists all processes available to the logged in user, and allows the user to start a process from there.
+
+<img src={TasklistProcessesImg} style={{width: 800}} alt="Processes page in Tasklist" />
+
+Potential extensions are dependent on your use case. You can consider grouping processes by apps, domains, or teams, showing a process history, or adding a list of open process instances or cases.
+
+Learn more about the **Processes** page in the [Tasklist documentation](/components/tasklist/userguide/starting-processes.md).
+
+<!-- TODO move this to "concepts" -->
+
+## Task lifecycle
+
+Every task follows a task lifecycle. In the typical task lifecycle, a task can:
+
+- Be **created**, but not yet assigned
+- Have **candidates** to work on
+- Be **assigned** and ready to work
+- Be **delegated** to another user
+- Be **completed** or **canceled**
+
+Before you create your task application, you should be clear about which task lifecycle is suitable for your use case.
+
+<img src={TaskLifecycleImg} className={styles.noShadow} style={{width: 800}} alt="Task lifecycle" />
+
+The lifecycle of human tasks is mostly a generic issue. There is no need to model common aspects into all your processes, as this often makes models unreadable. Use Camunda task management features or implement your requirements in a generic way.
+
+<img src={TaskAssignmentImg} className={styles.noShadow} style={{width: 600}} alt="Task assignment in group and personal queues" />
+
+Every task can be assigned to either a group of people, or a specific individual. An individual can **claim** a task, indicating that they are picking the task from the pool (to avoid multiple people working on the same task).
+
+As a general rule, you should assign human tasks in your business process to groups of people instead of specific individuals. This avoids bottlenecks (such as high workloads on single individuals or employees being on sick leave) and can greatly improve your process performance.
+
+In the [XML of a user task](/components/modeler/bpmn/user-tasks/user-tasks.md#xml-representations), this is represented as follows:
+
+```xml
+<bpmn:userTask id="task_review_loan">
+  <bpmn:extensionElements>
+    <zeebe:assignmentDefinition candidateGroups="Loan team" />
+  </bpmn:extensionElements>
+```
+
+Then, require individual members of that group to explicitly claim tasks before working on them. This way, you avoid different people trying to work on the same task at the same time, which can cause a race condition.
+
+## Additional elements and alternative use cases
+
+Often, task applications support the collaborative work on tasks, generally done using **comments**. **Document management** is a common use case of task applications, allowing users to upload, manage, and review **attachments**. Task applications are also the right place to browse, reference, and manage **case management data**.
+
+Task applications are not limited to web applications to be worked on desktops. Camunda has been used successfully for the the development of omnichannel customer-facing applications, such as **mobile banking apps**, often via a **backend-for-frontend** implementation.
+
+<!--
+TODO Section to be added once pages are available
+
+## Next steps
+
+You learned the basic concepts of a task application. Your possible next steps are:
+
+* Learn how to utilize Camunda 8 APIs to query and execute tasks in your task application, and to enrich it with process execution data.
+* Learn how to embed or customize Camunda Forms to render unique, tailored forms that can be designed by business users.
+* Run through a comprehensive guide on how to build your own task application.
+* Run throuh a guide on how to integrate with low-code tools to design your task application.
+-->

versioned_docs/version-8.4/apis-tools/frontend-development/sidebar-schema.js

@@ -0,0 +1,10 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+
+module.exports = {
+  "Frontend development": [
+    {
+      type: "autogenerated",
+      dirName: "apis-tools/frontend-development",
+    },
+  ],
+};

versioned_docs/version-8.4/apis-tools/frontend-development/styles.module.css

@@ -0,0 +1,11 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.noShadow {
+  box-shadow: none !important;
+  border: none !important;
+}

versioned_docs/version-8.4/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md

@@ -2,13 +2,12 @@
 id: tasklist-api-rest-overview
 title: "Overview"
 sidebar_position: 1
-description: "Tasklist API is a REST API and provides searching, getting, and changing Tasklist data."
+description: "Build applications for human-centered processes by querying human tasks, assigning users, and completing tasks with the Tasklist API."
 ---
 
 ## Introduction
 
-Tasklist API is a REST API and provides searching, getting, and changing Tasklist data.
-Requests and responses are in JSON notation. Some objects have additional endpoints.
+The Tasklist API is a REST API designed to build task applications for human-centered processes. The API allows you to query user tasks, assign users to these tasks, and complete these tasks.
 
 :::note
 Ensure you [authenticate](./tasklist-api-rest-authentication.md) before accessing the Tasklist API.
@@ -30,6 +29,8 @@ Work with this API in our [Postman collection](https://www.postman.com/camundate
 
 ## Endpoints
 
+Requests and responses are in JSON notation.
+
 | Endpoint (HTTP verb + URL path)                                                                                                                                 |                                                                       Description |
 | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------: |
 | **Tasks**                                                                                                                                                       |                                                                                   |

versioned_docs/version-8.4/apis-tools/working-with-apis-tools.md

@@ -11,6 +11,7 @@ This section steps through two concepts for integration:
 
 - **Control your Camunda 8 process automation** by [deploying processes](/components/modeler/web-modeler/run-or-publish-your-process.md#deploy-a-process), [starting process instances](/components/modeler/web-modeler/run-or-publish-your-process.md), [activating jobs](/components/concepts/job-workers.md), and more using supplemental and community-maintained **Zeebe client libraries**.
 - **Interact with the Camunda 8 ecosystem** by learning about [Camunda Components](/components/components-overview.md) and their APIs to communicate with your cluster, search, get and change data, create Cloud API clients, and more.
+- **Develop a custom front end for task applications** by learning the basic architecture of task applications, the APIs for interacting with Camunda 8 through your applications, and the open source form.js library for creating and embedding human task forms into these applications.
 
 :::note
 You're permitted to use these web apps and APIs for free with the Free Edition in non-production environments. To use the software in production, [purchase the Camunda Enterprise Edition](https://camunda.com/products/cloud/camunda-cloud-enterprise-contact/). Read more in our [licensing](../reference/licenses.md) documentation.
@@ -101,3 +102,10 @@ It is also possible to [build your own client](../apis-tools/build-your-own-clie
 In addition to APIs and clients, the Camunda Developer Experience team is looking for feedback on popular community clients turned SDKs. While these are currently on the Camunda Community Hub, we are actively iterating and evaluating feedback to fully support them.
 
 - [NodeJS SDK](https://github.com/camunda-community-hub/camunda-8-sdk-node-js)
+
+## Develop a custom frontend for task applications
+
+Camunda 8 provides APIs and JavaScript libraries to allow frontend developers to build custom task applications or to integrate with third-party tools or UI builders. The extensible Camunda Forms framework allows developers to build complex forms that can be rendered anywhere, while being maintained by business developers using Camunda Modeler.
+
+<DocCardList items={[{type:"link", href:"/docs/apis-tools/frontend-development/introduction-to-task-applications", label: "Task applications", docId:"apis-tools/frontend-development/introduction-to-task-applications"}
+]}/>

versioned_docs/version-8.4/components/best-practices/architecture/understanding-human-tasks-management.md

@@ -55,7 +55,7 @@ If you have human tasks in your process, you must make up your mind on how exact
 
 - [Camunda Tasklist](/docs/components/tasklist/introduction-to-tasklist/): The Tasklist application shipped with Camunda. This works out-of-the-box and has a low development effort. However, it is limited in terms of customizability and how much you can influence the user experience.
 
-- Custom task list application: You can develop a custom task list and adapt this to your needs without compromises. Human tasks are shown inside your custom application, following your style guide and usability concept. You will use the [Camunda Tasklist API](../../../apis-tools/tasklist-api/generated.md) in the background. This is very flexible, but requires additional development work.
+- Custom task list application: You can develop a custom task list and adapt this to your needs without compromises. Human tasks are shown inside your custom application, following your style guide and usability concept. You will use the [Camunda Tasklist API](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) in the background. This is very flexible, but requires additional development work.
 
 - Third party tasklist: If our organization already has a task list application rolled out to the field, you might want to use this for tasks created by Camunda. You will need to develop some synchronization mechanism. The upside of this approach is that your end users might not even notice that you introduce a new workflow engine.
 

versioned_sidebars/version-8.4-sidebars.json

@@ -967,6 +967,14 @@
         },
         "apis-tools/build-your-own-client"
       ]
+    },
+    {
+      "Frontend development": [
+        {
+          "type": "autogenerated",
+          "dirName": "apis-tools/frontend-development"
+        }
+      ]
     }
   ],
   "Reference": [