From c697a97241e5fbec35005231b3891957bee759a0 Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Thu, 4 Jul 2024 10:53:11 +0300 Subject: [PATCH] docs(concepts): Add documentation for Execution Listeners This commit introduces initial documentation for ELs in Camunda 8. It includes the following sections: - **Introduction**: Overview, benefits, and use cases of ELs. - **Getting Started**: Steps to enable ELs in BPMN models. - **Supported Elements**: A table of BPMN elements that support `start` and `end` ELs. - **Parameters and Configuration**: Explanation of EL parameters and example configurations. - **Limitations**: ELs limitations. - **Usage**: How to define Job Workers to process EL jobs. - **Variables**: Handling variables within ELs, including scope and dynamic variable handling. - **Examples**: Some examples of EL usage. - **Element Processing Flow**: A flowchart and detailed steps describing the lifecycle of elements with ELs. - **FAQ**: Common questions and troubleshooting tips. - **References**: Links to additional documentation. The documentation aims to provide a guide for developers to effectively implement and utilize Execution Listeners in their workflows. --- .../concepts/execution-listeners.md | 267 ++++++++++++++++++ sidebars.js | 1 + 2 files changed, 268 insertions(+) create mode 100644 docs/components/concepts/execution-listeners.md diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md new file mode 100644 index 00000000000..812430c06d7 --- /dev/null +++ b/docs/components/concepts/execution-listeners.md @@ -0,0 +1,267 @@ +--- +id: execution-listeners +title: "Execution Listeners" +description: "Execution Listeners for process activities" +--- + +## Introduction + +### Overview + +Execution Listeners (EL) in Camunda 8 allow 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, +external system interactions, and process monitoring without cluttering the BPMN model with technical details. + +### Benefits + +- **Automate pre and post-execution logic:** Simplifies process models by removing the need for additional technical steps. +- **Enhanced monitoring:** Provides real-time notifications and data export capabilities. +- **Improved process control:** Facilitates complex variable handling and decision-making within the workflow. + +### Use cases + +- Pre and post-processing actions for activities. +- Real-time notifications about process instance progress. +- Data export for reporting. +- Decoupled processes and data synchronization. +- Dynamic variable fetching and calculation before gateway and event elements. + +## Getting started + +### Enabling Execution Listeners + +Execution Listeners are enabled by configuring them in the BPMN model. +Ensure the necessary extensions and configurations are in place before deploying process definitions with EL. + +## Supported elements + +Execution Listeners can be applied to a variety of BPMN elements, enabling custom logic execution at different points within a process. +The following table provides a comprehensive overview of which elements support `start` and `end` ELs. +Note that for some elements, support is conditional, such as with non-interrupting escalation events. + +| **Element Type** | Sub-Type | Start EL | End EL | +| :-------------------------: | :------------------ | :------: | :----------------------: | +| **Tasks** | | ✅ | ✅ | +| | Business Rule Task | ✅ | ✅ | +| | User Task | ✅ | ✅ | +| | Script Task | ✅ | ✅ | +| | Service Task | ✅ | ✅ | +| | Receive Task | ✅ | ✅ | +| | Manual Task | ✅ | ✅ | +| **Events** | | | | +| _Start Events_ | | | | +| | None | ❌ | ✅ | +| | Message | ❌ | ✅ | +| | Signal | ❌ | ✅ | +| | Timer | ❌ | ✅ | +| _Intermediate Catch Events_ | | | | +| | Message | ✅ | ✅ | +| | Timer | ✅ | ✅ | +| | Signal | ✅ | ✅ | +| | Link | ✅ | ✅ | +| _Intermediate Throw Events_ | | | | +| | None | ✅ | ✅ | +| | Message | ✅ | ✅ | +| | Escalation | ✅ | ✅ (if not interrupting) | +| | Signal | ✅ | ✅ | +| | Compensation | ✅ | ✅ | +| | Link | ✅ | ✅ | +| _Boundary Events_ | | | | +| | Error | ❌ | ✅ | +| | Message | ❌ | ✅ | +| | Timer | ❌ | ✅ | +| | Signal | ❌ | ✅ | +| | Escalation | ❌ | ✅ | +| | Compensation | ❌ | ❌ | +| _End Events_ | | | | +| | None | ✅ | ✅ | +| | Error | ✅ | ❌ | +| | Message | ✅ | ✅ | +| | Terminate | ✅ | ✅ | +| | Escalation | ✅ | ✅(if not interrupting) | +| | Signal | ✅ | ✅ | +| | Compensation | ✅ | ✅ | +| **Gateways** | | | | +| | Exclusive Gateway | ❌ | ✅ | +| | Parallel Gateway | ❌ | ✅ | +| | Event-based Gateway | ❌ | ✅ | +| | Inclusive Gateway | ❌ | ✅ | +| **Processes** | | | | +| | Process Instance | ✅ | ✅ | +| **Subprocesses** | | | | +| | Embedded Subprocess | ✅ | ✅ | +| | Call Activities | ✅ | ✅ | +| | Event Subprocess | ✅ | ✅ | + +### Start Execution Listener + +Triggers custom logic before the element is processed. Useful for initial data setup or preconditions. + +### End Execution Listener + +Triggers custom logic after the element is processed. Ideal for cleanup operations or post-processing tasks. + +## Parameters and configuration + +### Parameters + +| Parameter | Type | Required | Description | +| :------------ | :----------------------- | :------: | ------------------------------------------------------------ | +| **eventType** | `string`, `fixed values` | Yes | Specifies when the EL should be executed (`start` or `end`). | +| **type** | `string`, `expression` | Yes | Defines the job worker type. | +| **retries** | `string`, `expression` | No | Number of retries if a failure occurs (default is `3`). | + +### Example configuration + +```xml + + + + + + +``` + +## Limitations + +- **Unsupported elements**: Some elements do not support `start` or `end` listeners due to their processing nature. For more details refer to the table of [supported elements](#supported-elements). + +## Usage + +### Job Workers + +To process EL jobs, a Job Worker should be defined. Job Workers handle specific tasks by subscribing to jobs of a +particular type and executing the associated business logic. They allow for flexible and reusable logic in workflows. +For more detailed information on how to create and manage Job Workers, +refer to the [Camunda Job Workers documentation](/components/concepts/job-workers.md) & [Job Worker example](apis-tools/java-client-examples/job-worker-open.md). + +## Variables + +### Scope + +Variables set during the completion of an EL job are local to the element where the EL is defined. +This design choice helps to prevent global variable scope cluttering, ensuring that the variables +are contained within the context of the specific element they are associated with. + +### Dynamic variable handling + +Execution Listeners enable the dynamic fetching and calculation of variables for the next steps in the process, +based on the current data. This functionality is particularly useful for elements such as gateways and events, +allowing for more informed decision-making and precise control over process flow. + +#### Gateways + +- **Inclusive, Exclusive, Event-Based Gateways:** 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. + +#### Events + +- **Message Events:** Variables set by ELs can be used to define the message correlation key, + ensuring that the correct message is matched with the event. +- **Timer Events:** ELs can define timer expressions based on the calculated variables, enabling dynamic timer configurations. +- **Signal Events:** Variables can determine the signal name, allowing for flexible signal handling based on the current process state. + +## Examples + +### Simple example + +A service task with execution listeners for pre and post-processing. + +```xml + + + // highlight-start + + + + + // highlight-end + + +``` + +## Element processing flow + +Understanding where Execution Listeners fit into the element processing flow is crucial for designing efficient workflows. +The following flowchart visualizes the element processing flow with Execution Listeners: + +```mermaid +flowchart LR + subgraph Activation + ElementActivation["Element Activation"] + StartExecutionListeners["Start Execution Listeners"] + FinalizeActivation["Finalize Activation"] + end + + subgraph Execution + ElementExecution["Element Execution"] + end + + subgraph Completion + EndExecutionListeners["End Execution Listeners"] + ElementCompletion["Element Completion"] + FinalizeCompletion["Finalize Completion"] + end + + ElementActivation -->|if 'start' ELs configured| StartExecutionListeners + StartExecutionListeners:::execution-listeners --> FinalizeActivation + ElementActivation --> FinalizeActivation + FinalizeActivation --> ElementExecution + ElementExecution --> ElementCompletion + ElementCompletion -->|if 'end' ELs configured| EndExecutionListeners + EndExecutionListeners:::execution-listeners --> FinalizeCompletion + ElementCompletion --> FinalizeCompletion + + classDef execution-listeners fill:gray +``` + +
+ Element lifecycle steps +

When an element with ELs is processed in Zeebe, the following steps outline its lifecycle, highlighting where start and end ELs are executed:

+

Element Activation

+

The process instance reaches the element and begins its activation. This initial phase prepares the element for execution and typically includes:

+ +

Start Execution Listeners

+

If start ELs are defined, they are executed. These listeners can perform setup tasks and have access to input variables (if any defined).

+

Finalize Activation

+

The element completes any additional actions required for activation. This usually includes:

+ +

Element Execution

+

The core activity of the element is carried out. This step represents the main purpose of the BPMN element (e.g., a task being performed).

+

Element Completion

+

Once the primary activity is finished, the element begins its completion phase, which includes:

+ +

End Execution Listeners

+

During the element completion stage, if end ELs are defined, they are executed after applying output mappings (if any defined). These listeners can perform cleanup tasks and have access to output variables.

+

Finalize Completion

+

The element executes any additional actions required for element completion and execution transits to the next element.

+

By placing custom logic at strategic points within the element lifecycle, you can enhance process control, improve data handling, and integrate seamlessly with external systems.

+
+ +## FAQ + +### Common questions + +- **Can execution listeners be used with all BPMN elements?** + - No, some elements have limitations due to their processing nature. See the table of [supported elements](#supported-elements). + +### Troubleshooting + +- **Execution Listener not triggering** + - Verify the configuration and ensure the element supports the specified listener type. + +## Learn more + +- [Variables](/components/concepts/variables.md) +- [Expressions](/components/concepts/expressions.md) +- [Job workers (basics)](/components/concepts/job-workers.md) +- [Job workers (Java client)](/apis-tools/java-client/job-worker.md) diff --git a/sidebars.js b/sidebars.js index f10cf266968..6d8be9e17d1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -66,6 +66,7 @@ module.exports = { "components/concepts/clusters", "components/concepts/processes", "components/concepts/job-workers", + "components/concepts/execution-listeners", "components/concepts/process-instance-creation", "components/concepts/messages", "components/concepts/signals",