Merge branch 'release-notes-860-alpha5' of https://github.com/camunda…

…/camunda-docs into release-notes-860-alpha5

.github/workflows/sync-rest-api-docs.yaml

@@ -0,0 +1,66 @@
+name: Sync Camunda REST API
+
+on:
+  schedule:
+    - cron: "0 15 * * 4" # Runs every Thursday at 3 PM UTC
+  workflow_dispatch:
+
+jobs:
+  sync-file:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Camunda docs repository
+        uses: actions/checkout@v3
+        with:
+          repository: camunda/camunda-docs
+          path: docs
+
+      - name: Checkout Camunda repository
+        uses: actions/checkout@v3
+        with:
+          repository: camunda/camunda
+          path: rest-spec
+          sparse-checkout: zeebe/gateway-protocol/src/main/proto/rest-api.yaml
+          sparse-checkout-cone-mode: false
+
+      - name: Sync documentation
+        run: |
+          cd docs
+          mv ../rest-spec/zeebe/gateway-protocol/src/main/proto/rest-api.yaml api/camunda/camunda-openapi.yaml
+          npm i
+          npm run api:generate:camunda
+          if git diff-index --quiet HEAD; then
+            echo "No changes to commit."
+            exit 0
+          fi
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: "${{ secrets.GITHUB_TOKEN }}"
+          path: docs
+          title: Update camunda REST API doc
+          body: |
+            ## Description
+
+            This is an autogenerated PR by the [sync api specs workflow](https://github.com/camunda/camunda-docs/tree/main/.github/workflows/sync-rest-api-docs.yaml).
+            This PR contains every changes made to the REST api specs in the [monorepo](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml) in the last week.
+            This PR contains also all the generated OpenAPI files related to the changes.
+
+            ## When should this change go live?
+
+            - There is **no urgency** with this change and can be released at any time.
+
+            ## PR Checklist
+
+            - My changes are for the **next minor** and are in `/docs` directory (aka `/next/`).
+            - 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.
+
+          commit-message: "docs: update REST API spec"
+          branch: update-rest-doc
+          delete-branch: true
+          team-reviewers: camunda/tech-writers
+          reviewers: pepopowitz
+          base: main
+          labels: deploy

.husky/pre-commit

@@ -1,7 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-export NVM_DIR="$HOME/.nvm"
-[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
-
 npx lint-staged

docs/components/components-overview.md

@@ -9,20 +9,7 @@ keywords: ["process automation tools"]
 
 This section contains product manual content for each component in Camunda 8, including conceptual content. Together, these components comprise the Camunda 8 SaaS experience.
 
-- [Concepts](concepts/what-is-camunda-8.md) - Learn more about a variety of Camunda 8 topics with this conceptual documentation on clusters, processes, job workers, workflow patterns, and more.
-- [Console](console/introduction-to-console.md) - With this management application for the included products, create and delete clusters, manage API clients and alerts, and more.
-- [Modeler](modeler/about-modeler.md) - Design and implement diagrams using Camunda's modeling tools, including Web Modeler and Desktop Modeler.
-- [Connectors](connectors/introduction.md) - Integrate with external systems using these reusable building blocks.
-- [Zeebe](zeebe/zeebe-overview.md) - Define processes graphically in BPMN 2.0, choose any gRPC-supported programming language to implement your workers, build processes that react to events from Apache Kafka, and more using this process automation engine powering Camunda 8.
-- [Operate](operate/operate-introduction.md) - Monitor and troubleshoot process instances running in Zeebe, and carry out key operations such as resolving incidents and updating process instance variables with Operate.
-- [Tasklist](tasklist/introduction-to-tasklist.md) - Implement business processes alongside user tasks in Zeebe, and orchestrate human workflows critical to your business to reduce time-to-value for your process orchestration projects with this interface for manual work.
-- [Optimize]($optimize$/components/what-is-optimize) - Geared toward business stakeholders, Optimize offers business intelligence tooling for Camunda enterprise customers. By leveraging data collected during process execution, users can collaboratively examine areas in business processes for improvement.
-
-:::note
-Additionally, Camunda hosts a section of [Best Practices](./best-practices/best-practices-overview.md). A mix of conceptual and practical implementation information, this section hosts our condensed experience using BPMN and DMN on the Camunda tool stack collected by consulting engagement with our customers and feedback from the community.
-:::
-
-![Architecture diagram for Camunda including all the components for SaaS](./img/ComponentsAndArchitecture_SaaS.png)
+See our [introduction to Camunda](/guides/introduction-to-camunda-8.md) if you are new to Camunda, or visiting the Camunda documentation for the first time.
 
 :::note Looking for deployment guides?
 

docs/components/concepts/execution-listeners.md

@@ -4,80 +4,107 @@ title: "Execution listeners"
 description: "An execution listener allows users to react to various events in the workflow execution lifecycle by executing custom logic."
 ---
 
-An execution listener (EL) allows users to react to various events in the workflow execution lifecycle by executing custom logic. This feature provides flexibility and control over the process execution, enabling complex data handling and
-external system interactions without cluttering the BPMN model with technical details.
+An execution listener (EL) allows users to react to various events in the workflow execution lifecycle by executing custom logic.
 
-**Use cases:**
+## About execution listeners
+
+You can use execution listeners to provide flexibility and control over process execution, and handle complex data and external system interactions without cluttering the BPMN model with technical details.
+
+### Use cases
+
+Execution listeners are useful in the following typical cases:
 
 - Pre- and post-processing actions for activities
 - External calculations of variables for element expressions
 - Decoupled processes and data synchronization
 
-## Define a listener
+### Blocking behavior
+
+An execution listener is a blocking operation, meaning that the workflow execution lifecycle only continues once the listener is completed. This ensures that all necessary pre- and post-processing actions defined by the listener are fully executed before the workflow proceeds to the next element.
 
-Execution listeners can be configured per BPMN element within a process. There are two types of listeners:
+## Define an execution listener
 
-- **Start:** Invoked before the element is processed. Useful for setting variables or executing preconditions.
-- **End:** Invoked after the element is processed. Useful for executing cleanup or post-processing tasks.
+You can configure execution listeners per BPMN element within a process.
+
+There are two types of execution listener:
+
+- **Start:** Invoked _before_ the element is processed. Useful for setting variables or executing preconditions.
+- **End:** Invoked _after_ the element is processed. Useful for executing cleanup or post-processing tasks.
 
 Each listener has three properties:
 
-- `eventType` - Specifies when the listener is triggered (`start` or `end`).
-- `type` - The name of the job type.
-- `retries` - The number of job retries.
+| Property    | Description                                                  |
+| :---------- | :----------------------------------------------------------- |
+| `eventType` | Specifies when the listener is triggered (`start` or `end`). |
+| `type`      | The name of the job type.                                    |
+| `retries`   | The number of job retries.                                   |
+
+:::note
+If multiple listeners of the same `eventType` (such as multiple start listeners) are defined on the same activity, they are executed sequentially, one after the other, in the order defined in the BPMN model.
+:::
+
+## Implement an execution listener
 
-## Implement a listener
+Execution listeners are processed by [job workers](/components/concepts/job-workers.md).
 
-Execution listeners are a special kind of [job worker](/components/concepts/job-workers.md). They are based on the same concept of jobs and use the same protocol. You can implement a listener in the same way as a regular job worker. Refer to the
-[job workers documentation](/components/concepts/job-workers.md) for more information.
+- Listeners are based on the same concept of jobs and use the same protocol.
+- You can implement a handler for an execution listener just as you would for a regular job.
+
+See [open a job worker](/apis-tools/java-client-examples/job-worker-open.md) for an example of how to create a job worker and handler that can also process execution listener jobs.
 
 :::note
-Throwing a BPMN error for an execution listener's job is not supported.
+[Throwing a BPMN error](/components/best-practices/development/dealing-with-problems-and-exceptions.md/#throwing-and-handling-bpmn-errors) for an execution listener's job is not supported.
 :::
 
-## Handle variables in a listener
+## Variables in an execution listener
+
+Similar to regular job workers, a listener can read variables of the process instance and set new variables by completing the job with variables. The scope of variables and the effect of the job variables depend on the listener event type.
 
-Similar to regular job workers, a listener can read variables of the process instance and set new variables by
-completing the job with variables. The scope of variables and the effect of the job variables depend on the listener's
-event type.
+### Start listeners
 
-### For start listeners
+Start listeners are invoked after applying the variable input mappings, and before subscribing to events, evaluating the element's expressions, and executing the element's behavior.
 
-The start listeners are invoked after applying the variable input mappings and before subscribing to events, evaluating the element's expressions, and executing the element's behavior.
+- A start listener can read the process instance variables and local variables created by the variable input
+  mappings.
+- If a start listener completes the job with variables, those variables are set as
+  [local variables](/components/concepts/variables.md#local-variables) for the element. Subsequent listeners can access these variables.
 
-A start listener can read the process instance variables and local variables that are created by the variable input
-mappings.
+You can use variables for the following use cases:
 
-If a start listener completes the job with variables, those variables are set as
-[local variables](/components/concepts/variables.md#local-variables) for the element. Subsequent listeners can access these variables.
+| Use case                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gateways                  | <p> [Inclusive](/components/modeler/bpmn/inclusive-gateways/inclusive-gateways.md), [exclusive](/components/modeler/bpmn/exclusive-gateways/exclusive-gateways.md), [event-based gateways](/components/modeler/bpmn/event-based-gateways/event-based-gateways.md): Use ELs to calculate and set variables that determine the outgoing path from these gateways. The custom logic executed by ELs can evaluate current data and set the necessary variables to guide the process flow correctly.</p>                                                                                                                                                                                                                                                          |
+| Intermediate catch events | <p><ul><li><p>[Message events](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events): Variables set by ELs can be used to define the message correlation key, ensuring the correct message is matched with the event.</p></li><li><p>[Timer events](/components/modeler/bpmn/timer-events/timer-events.md#intermediate-timer-catch-events): ELs can define timer expressions based on the calculated variables, enabling dynamic timer configurations.</p></li><li><p>[Signal events](/components/modeler/bpmn/signal-events/signal-events.md#signal-intermediate-catch-events): Variables can determine the signal name, allowing for flexible signal handling based on the current process state.</p></li></ul></p> |
 
-You can use variables for the following cases:
+### End listeners
 
-**Gateways**
+End listeners are invoked after applying the variable output mappings and before leaving the element.
 
-- [Inclusive](/components/modeler/bpmn/inclusive-gateways/inclusive-gateways.md), [exclusive](/components/modeler/bpmn/exclusive-gateways/exclusive-gateways.md), [event-based gateways](/components/modeler/bpmn/event-based-gateways/event-based-gateways.md):
-  Use ELs to calculate and set variables that determine the outgoing path from these gateways. The custom logic executed by ELs can evaluate current data and set the necessary variables to guide the process flow correctly.
+- An end listener can read the process instance variables, the local variables of the element, and the resulting
+  variables of the output mappings.
+- If an end listener completes the job with variables, those variables are propagated to the element's parent scope, like
+  variables from the output mappings. Subsequent listeners can access these variables.
 
-**Intermediate catch events**
+## Incident recovery
 
-- [Message events](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events):
-  Variables set by ELs can be used to define the message correlation key, ensuring the correct message is matched with the event.
-- [Timer events](/components/modeler/bpmn/timer-events/timer-events.md#intermediate-timer-catch-events): ELs can define
-  timer expressions based on the calculated variables, enabling dynamic timer configurations.
-- [Signal events](/components/modeler/bpmn/signal-events/signal-events.md#signal-intermediate-catch-events): Variables can determine the signal name, allowing for flexible signal handling based on the current process state.
+During execution listener processing, issues can arise that lead to [incidents](/components/concepts/incidents.md). For example, these incidents can occur due to job execution failures or problems during expression evaluation.
 
-### For end listeners
+### Job execution failure
 
-The end listeners are invoked after applying the variable output mappings and before leaving the element.
+If an execution listener job fails (for example, if an external service is unavailable), it is retried according to the `retries` property.
 
-An end listener can read the process instance variables, the local variables of the element, and the resulting
-variables of the output mappings.
+If all retries are exhausted and the job still fails, the process halts, and an incident is raised. Once the incident is resolved, only the listener with the failed job is retried, allowing the process to resume from the point of failure without re-executing successfully completed listeners.
 
-If an end listener completes the job with variables, those variables are propagated to the element's parent scope, like
-variables from the output mappings. Subsequent listeners can access these variables.
+### Expression evaluation failure
+
+Incidents can also occur during the evaluation of an execution listener's properties (for example, due to incorrect variable mapping or expression syntax).
+
+If this happens, all listeners of the same event type (`start` or `end`) that were processed before the failure are re-executed once the issue is resolved, even if they had previously completed successfully.
 
 ## Limitations
 
+Execution listeners have the following limitations:
+
 - **Unsupported elements**: The following elements do not support `start` or `end` listeners due to their processing nature:
 
   - Start events (start ELs): Use `start` listeners of process instances or subprocesses to cover the missing `start` listeners for specific start events.
@@ -87,13 +114,16 @@ variables from the output mappings. Subsequent listeners can access these variab
   - Compensation boundary events: Place the ELs on the compensation handler.
 
 - **Duplicate listeners**: Execution listeners must have unique combinations of `eventType` and `type`.
-  If multiple listeners with the same `eventType` and `type` are defined, it will result in a validation error. However, it's possible to have listeners of the same `type` if they are associated with different `eventType` values.
+  Defining multiple listeners with the same `eventType` and `type` results in a validation error. However, you can define listeners with the same `type` if they are associated with different `eventType` values.
+
+- **Interrupting escalation events**: For intermediate throw and end events with an interrupting escalation event, `end` listeners are not executed. The escalation event terminates the element's processing immediately upon activation, bypassing any defined `end` listeners.
 
-- **Interrupting escalation events**: For intermediate throw and end events with an interrupting escalation event, `end` listeners will not be executed. The escalation event terminates the element's processing immediately upon activation, bypassing any defined `end` listeners.
+- **Throwing a BPMN error**: This operation is not supported for execution listener jobs.
 
-## Learn more
+## Related resources
 
 - [Variables](/components/concepts/variables.md)
 - [Expressions](/components/concepts/expressions.md)
+- [Incidents](/components/concepts/incidents.md)
 - [Job workers (basics)](/components/concepts/job-workers.md)
 - [Job workers (Java client)](/apis-tools/java-client/job-worker.md)