Merge branch 'main' into alpha2-release-notes

.github/pull_request_template.md

@@ -26,10 +26,10 @@
 - [ ] I added a redirect for a renamed or deleted page to the .htaccess file.
 -->
 
-<!-- All changes require either and Engineering review or technical writer review. **Many require both!** -->
+<!-- All changes require either an Engineering review or technical writer review. **Many require both!** -->
 
 - [ ] My changes require an [Engineering review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned the Engineering DRI or delegate.
-- [ ] My changes require a [technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned @christinaausley as a reviewer.
+- [ ] My changes require a [technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned @camunda/tech-writers as a reviewer.
 
 <!-- UNCOMMENT THIS SECTION IF APPLICABLE. Changes to **docs infra**, including updates to workflows and adding new npm packages, must be first discussed via issue or #ask-c8-documentation and linked for context.
 - [ ] My changes require a [docs infrastructure review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process). -->

.github/workflows/add-to-project.yaml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   sync-board:
-    if: github.event.requested_reviewer.login == 'akeller' || github.event.requested_reviewer.login == 'christinaausley'
+    if: github.event.requested_reviewer.login == 'akeller' || github.event.requested_reviewer.login == 'christinaausley' || github.event.requested_reviewer.login == 'conceptualshark' || github.event.requested_team.name == 'Tech Writers'
     runs-on: ubuntu-latest
     steps:
       - name: Get project IDs for later steps

docs/apis-tools/administration-api/authentication.md

@@ -67,7 +67,7 @@ The OAuth service rate limits about one request per second for all clients with
 All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
 
-The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+The officially offered [client libraries](/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
 
 If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
 

docs/apis-tools/administration-api/tutorial.md

@@ -23,7 +23,7 @@ Make sure you keep the generated client credentials in a safe place. The **Clien
 ## Getting started
 
 - A detailed API description can be found [here](https://console.cloud.camunda.io/customer-api/openapi/docs/#/) via Swagger. With a valid access token, this offers an interactive API experience against your Camunda 8 cluster.
-- You need authentication to access the API endpoints. Find more information [here](/docs/apis-tools/administration-api/authentication.md).
+- You need authentication to access the API endpoints. Find more information [here](/apis-tools/administration-api/authentication.md).
 
 ## Set up authentication
 

docs/apis-tools/frontend-development/01-task-applications/02-user-task-lifecycle.md

@@ -17,7 +17,7 @@ Refer to the Camunda best practice task life cycle below as a starting point.
 
 ## Camunda best practice task life cycle
 
-The Camunda [Tasklist](/docs/components/tasklist/introduction-to-tasklist.md) component implements a task life cycle optimized to track actual work on individual tasks via [forms](../03-forms/01-introduction-to-forms.md) on a desktop. It separates task assignment from task state to support collaborative ways of working and promote use cases for managers.
+The Camunda [Tasklist](/components/tasklist/introduction-to-tasklist.md) component implements a task life cycle optimized to track actual work on individual tasks via [forms](../03-forms/01-introduction-to-forms.md) on a desktop. It separates task assignment from task state to support collaborative ways of working and promote use cases for managers.
 
 On the happy path, task agents can:
 
@@ -27,7 +27,7 @@ On the happy path, task agents can:
 - The data entered up to this point is preserved. If they are unable to continue, they can `return` a task to the queue for someone else to pick it up, which resets the task data.
 
 :::note
-The state of the task is derived via a CQRS pattern. [Zeebe](/docs/components/zeebe/zeebe-overview.md), Camunda's process execution engine, manages a stream of events. There is no single status attribute in tasks. Instead, tasks derive their status from these events.
+The state of the task is derived via a CQRS pattern. [Zeebe](/components/zeebe/zeebe-overview.md), Camunda's process execution engine, manages a stream of events. There is no single status attribute in tasks. Instead, tasks derive their status from these events.
 :::
 
 ```mermaid

docs/apis-tools/go-client/go-get-started.md

@@ -37,7 +37,7 @@ go mod init zb-user/zb-example
 2. To use the Zeebe Go client library, run the following:
 
 ```bash
-go get github.com/camunda/zeebe/clients/go/v8@v8.5.1
+go get github.com/camunda/camunda/clients/go/v8@v8.6.0
 ```
 
 This adds the following dependency to your `go.mod`, it should look similar to this:
@@ -47,7 +47,7 @@ module github.com/zb-user/zb-example
 
 go 1.21
 
-require github.com/camunda/zeebe/clients/go/v8@v8.5.1
+require github.com/camunda/camunda/clients/go/v8@v8.6.0
 ```
 
 3. Set the connection settings and client credentials as environment variables in your terminal:
@@ -71,8 +71,8 @@ package main
 import (
 	"context"
 	"fmt"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/zbc"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/pb"
+	"github.com/camunda/camunda/clients/go/v8/pkg/zbc"
+	"github.com/camunda/camunda/clients/go/v8/pkg/pb"
 	"os"
 )
 
@@ -278,7 +278,7 @@ Now, we want to do some work within our process. Follow the steps below:
 - Set the **type** of the second task to `fetcher-service`.
 - Set the **type** of the third task to `shipping-service`.
 
-6. Additionally, for the service task `Collect Money` set a [**task-header**](/docs/next/components/modeler/bpmn/service-tasks/#task-headers) with the key `method` and the value `VISA`. This header is used as a configuration parameter for the payment-service worker to hand over the payment method.
+6. Additionally, for the service task `Collect Money` set a [**task-header**](/components/modeler/bpmn/service-tasks/service-tasks.md#task-headers) with the key `method` and the value `VISA`. This header is used as a configuration parameter for the payment-service worker to hand over the payment method.
 
 The consolidated example looks as follows:
 
@@ -297,9 +297,9 @@ package main
 import (
 	"context"
 	"fmt"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/entities"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/worker"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/zbc"
+	"github.com/camunda/camunda/clients/go/v8/pkg/entities"
+	"github.com/camunda/camunda/clients/go/v8/pkg/worker"
+	"github.com/camunda/camunda/clients/go/v8/pkg/zbc"
 	"log"
 	"os"
 )
@@ -413,9 +413,9 @@ package main
 import (
 	"context"
 	"fmt"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/entities"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/worker"
-	"github.com/camunda/zeebe/clients/go/v8/pkg/zbc"
+	"github.com/camunda/camunda/clients/go/v8/pkg/entities"
+	"github.com/camunda/camunda/clients/go/v8/pkg/worker"
+	"github.com/camunda/camunda/clients/go/v8/pkg/zbc"
 	"log"
 	"os"
 )

docs/apis-tools/operate-api/tutorial.md

@@ -9,7 +9,7 @@ In this tutorial, we'll step through examples to highlight the capabilities of t
 
 ## Getting started
 
-- You need authentication to access the API endpoints. Find more information [here](/docs/apis-tools/operate-api/overview.md#authentication).
+- You need authentication to access the API endpoints. Find more information [here](/apis-tools/operate-api/overview.md#authentication).
 - We will use the `bpmn-js` library to render the diagram and add overlays. Visit the documentation on [embedding the pre-packaged viewer](https://bpmn.io/toolkit/bpmn-js/walkthrough/#viewer-pre-packaged) for more details.
 
 ## Set up the demo project

docs/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks.md

@@ -15,7 +15,7 @@ import styles from "./assets/css/cleanImages.module.css";
 import APIArchitectureImg from './assets/img/api-architecture.png';
 import ZeebeTaskSelectionImg from './assets/img/zeebe-user-task-selection.png';
 
-Camunda 8.5 introduces a new [user task](/docs/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type: Zeebe user tasks.
+Camunda 8.5 introduces a new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type: Zeebe user tasks.
 Zeebe user tasks have several benefits, including:
 
 - Running directly on the automation engine for high performance.

docs/apis-tools/tasklist-api/tasklist-api-overview.md

@@ -26,7 +26,7 @@ For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/graphql`, and
 
 To obtain the Tasklist GraphQL schema, visit the API collection in [GitHub](https://github.com/camunda-community-hub/camunda-8-api-postman-collection), which is fully functioning in [Postman](https://www.postman.com/camundateam/workspace/camunda-8-postman/collection/20317927-6394943f-b57c-4c04-acf9-391a8614103b?action=share&creator=11465105).
 
-Alternatively, send a request to the endpoint with a GraphQL introspection query as described [here](https://graphql.org/learn/introspection/), or use the [generated API documentation](/docs/apis-tools/tasklist-api/generated.md).
+Alternatively, send a request to the endpoint with a GraphQL introspection query as described [here](https://graphql.org/learn/introspection/), or use the [generated API documentation](/apis-tools/tasklist-api/generated.md).
 
 There are also several [tools to explore GraphQL APIs](https://altair.sirmuel.design).
 

docs/apis-tools/zeebe-api/gateway-service.md

@@ -160,6 +160,8 @@ message CancelProcessInstanceRequest {
   // the process instance key (as, for example, obtained from
   // CreateProcessInstanceResponse)
   int64 processInstanceKey = 1;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 2;
 }
 ```
 
@@ -254,6 +256,8 @@ message CreateProcessInstanceRequest {
   repeated ProcessInstanceCreationStartInstruction startInstructions = 5;
   // the tenant ID of the process definition
   string tenantId = 6;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 7;
 }
 
 message ProcessInstanceCreationStartInstruction {
@@ -721,6 +725,8 @@ message ModifyProcessInstanceRequest {
   repeated ActivateInstruction activateInstructions = 2;
   // instructions describing which elements should be terminated
   repeated TerminateInstruction terminateInstructions = 3;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 4;
 
   message ActivateInstruction {
     // the id of the element that should be activated
@@ -801,7 +807,8 @@ message MigrateProcessInstanceRequest {
   int64 processInstanceKey = 1;
   // the migration plan that defines target process and element mappings
   MigrationPlan migrationPlan = 2;
-
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 3;
   message MigrationPlan {
     // the key of process definition to migrate the process instance to
     int64 targetProcessDefinitionKey = 1;
@@ -925,6 +932,8 @@ problem, followed by this call.
 message ResolveIncidentRequest {
   // the unique ID of the incident to resolve
   int64 incidentKey = 1;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 2;
 }
 ```
 
@@ -967,6 +976,8 @@ message SetVariablesRequest {
   // be unchanged, and scope 2 will now be `{ "bar" : 1, "foo" 5 }`. if local was false, however,
   // then scope 1 would be `{ "foo": 5 }`, and scope 2 would be `{ "bar" : 1 }`.
   bool local = 3;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 4;
 }
 ```
 
@@ -1123,6 +1134,8 @@ message UpdateJobRetriesRequest {
   int64 jobKey = 1;
   // the new amount of retries for the job; must be positive
   int32 retries = 2;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 3;
 }
 ```
 
@@ -1161,6 +1174,8 @@ message UpdateJobTimeoutRequest {
   int64 jobKey = 1;
   // the duration of the new timeout in ms, starting from the current moment
   int64 timeout = 2;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 3;
 }
 ```
 
@@ -1195,6 +1210,8 @@ message DeleteResourceRequest {
   // The key of the resource that should be deleted. This can be the key
   // of a process definition, the key of a decision requirements definition or the key of a form definition.
   int64 resourceKey = 1;
+  // a reference key chosen by the user and will be part of all records resulting from this operation
+  optional uint64 operationReference = 2;
 }
 ```
 

docs/components/best-practices/architecture/sizing-your-environment.md

@@ -71,15 +71,15 @@ The closer you push throughput to the limits, the more latency you will get. Thi
 
 ### Payload size
 
-Every process instance can hold a payload (known as [process variables](/docs/components/concepts/variables/)). The payload of all running process instances must be managed by the runtime workflow engine, and all data of running and ended process instances is also forwarded to Operate and Optimize.
+Every process instance can hold a payload (known as [process variables](/components/concepts/variables.md)). The payload of all running process instances must be managed by the runtime workflow engine, and all data of running and ended process instances is also forwarded to Operate and Optimize.
 
 The data you attach to a process instance (process variables) influences resource requirements. For example, it makes a big difference if you only add one or two strings (requiring around 1 KB of space) to your process instances, or a full JSON document containing 1 MB. Hence, the payload size is an important factor when looking at sizing.
 
 There are a few general rules regarding payload size:
 
-- The maximum [variable size per process instance is limited](/docs/components/concepts/variables/#variable-size-limitation), currently to roughly 3 MB.
-- We don't recommend storing much data in your process context. Refer to our [best practice on handling data in processes](/docs/components/best-practices/development/handling-data-in-processes/).
-- Every [partition](/docs/components/zeebe/technical-concepts/partitions/) of the Zeebe installation can typically handle up to 1 GB of payload in total. Larger payloads can lead to slower processing. For example, if you run one million process instances with 4 KB of data each, you end up with 3.9 GB of data, and you should run at least four partitions. In reality, this typically means six partitions, as you want to run the number of partitions as a multiple of the replication factor, which by default is three.
+- The maximum [variable size per process instance is limited](/components/concepts/variables.md#variable-size-limitation), currently to roughly 3 MB.
+- We don't recommend storing much data in your process context. Refer to our [best practice on handling data in processes](/components/best-practices/development/handling-data-in-processes.md).
+- Every [partition](/components/zeebe/technical-concepts/partitions.md) of the Zeebe installation can typically handle up to 1 GB of payload in total. Larger payloads can lead to slower processing. For example, if you run one million process instances with 4 KB of data each, you end up with 3.9 GB of data, and you should run at least four partitions. In reality, this typically means six partitions, as you want to run the number of partitions as a multiple of the replication factor, which by default is three.
 
 The payload size also affects disk space requirements, as described in the next section.
 
@@ -124,7 +124,7 @@ Spinning up a Camunda 8 Cluster means you run multiple components that all need
 
 All components are clustered to provide high-availability, fault-tolerance and resiliency.
 
-Zeebe scales horizontally by adding more cluster nodes (pods). This is **limited by the [number of partitions](/docs/components/zeebe/technical-concepts/partitions/)** configured for a Zeebe cluster, as the work within one partition cannot be parallelized by design. Hence, you need to define enough partitions to utilize your hardware. The **number of partitions cannot be changed after the cluster was initially provisioned** (at least not yet), elastic scalability of partitions is not yet possible.
+Zeebe scales horizontally by adding more cluster nodes (pods). This is **limited by the [number of partitions](/components/zeebe/technical-concepts/partitions.md)** configured for a Zeebe cluster, as the work within one partition cannot be parallelized by design. Hence, you need to define enough partitions to utilize your hardware. The **number of partitions cannot be changed after the cluster was initially provisioned** (at least not yet), elastic scalability of partitions is not yet possible.
 
 If you anticipate the load increasing over time, prepare by configuring more partitions than you currently need as a buffer. For example, you could multiply the number of partitions you need for your current load by four to add a buffer. This typically has just a small impact on performance.
 

docs/components/best-practices/architecture/understanding-human-tasks-management.md

@@ -53,7 +53,7 @@ While assigning users to groups is advised, it's not the only option. You could
 
 If you have human tasks in your process, you must make up your mind on how exactly you want to let your users work on their tasks and interact with the workflow engine. You have basically three options:
 
-- [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.
+- [Camunda Tasklist](/components/tasklist/introduction-to-tasklist.md): 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-rest/tasklist-api-rest-overview.md) in the background. This is very flexible, but requires additional development work.