From c697a97241e5fbec35005231b3891957bee759a0 Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Thu, 4 Jul 2024 10:53:11 +0300 Subject: [PATCH 1/6] 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", From e29b813d8302d0c770ac809041da16523164a77d Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Thu, 4 Jul 2024 10:53:11 +0300 Subject: [PATCH 2/6] 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..95f9594e040 --- /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** | | | | +| | Inclusive Gateway | ✅ | ❌ | +| | Exclusive Gateway | ✅ | ❌ | +| | Parallel Gateway | ✅ | ❌ | +| | Event-based 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:

+
    +
  • Apply Input Mappings (if applicable): Input variables are mapped to the element's local scope.
    • +
+

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:

+
    +
  • Subscribe to Events (if applicable): The element subscribes to any events it needs to listen for during its execution.
    • +
  • Element Activated: The element is fully activated and ready to perform its primary function.
    • +
+

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:

+
    +
  • Apply Output Mappings (if applicable): Output variables are mapped from the element's local scope to the global scope.
    • +
  • Unsubscribe from Events (if applicable): The element unsubscribes from any events it was listening for.
    • +
+

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", From 11199d68e93a81f8d84ffbc1a6f2054d4751c194 Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Tue, 9 Jul 2024 16:04:45 +0300 Subject: [PATCH 3/6] docs(concepts): improve documentation - adjust text for sections - improve formatting - add sections with limitations and workarounds --- .../concepts/execution-listeners.md | 197 +++++++++++++----- 1 file changed, 141 insertions(+), 56 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index 95f9594e040..fd2283897e8 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -28,11 +28,40 @@ external system interactions, and process monitoring without cluttering the BPMN ## Getting started +### Start listeners + +Triggers custom logic before the element is processed. Useful for initial data setup or preconditions. + +### End listeners + +Triggers custom logic after the element is processed. Ideal for cleanup operations or post-processing tasks. + ### 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. +## 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 + + + + + + +``` + ## Supported elements Execution Listeners can be applied to a variety of BPMN elements, enabling custom logic execution at different points within a process. @@ -46,6 +75,7 @@ Note that for some elements, support is conditional, such as with non-interrupti | | User Task | ✅ | ✅ | | | Script Task | ✅ | ✅ | | | Service Task | ✅ | ✅ | +| | Send Task | ✅ | ✅ | | | Receive Task | ✅ | ✅ | | | Manual Task | ✅ | ✅ | | **Events** | | | | @@ -93,38 +123,112 @@ Note that for some elements, support is conditional, such as with non-interrupti | | Call Activities | ✅ | ✅ | | | Event Subprocess | ✅ | ✅ | -### Start Execution Listener +## Limitations -Triggers custom logic before the element is processed. Useful for initial data setup or preconditions. +- **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). -### End Execution Listener +- **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 an validation error. + While it's possible to have listeners of the same `type` if they are associated with different `eventType` values. -Triggers custom logic after the element is processed. Ideal for cleanup operations or post-processing tasks. +- **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. -## Parameters and configuration +## Workarounds for unsupported Execution Listeners -### Parameters +While some BPMN elements do not support `start` or `end` ELs, there are several workarounds to achieve +similar functionality for specific elements. Here are the recommended strategies: -| 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`). | +### Start Events (Start ELs) -### Example configuration +**Workaround:** Use `start` listeners of process instances or subprocesses to cover the missing `start` listeners for specific start events. + +
+ Example: ```xml - - - - - - + + + + // highlight-next-line + + + + + flow1 + + + ``` -## Limitations +
+ +### Boundary Events (Start ELs) + +**Workaround:** Place the start logic in the `start` ELs of the main activity to which the boundary event is attached. + +
+ Example: -- **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). +```xml + + + + + + + // highlight-next-line + + + + + + + + + + + + + + + +``` + +
+ +### Gateways (End ELs) + +**Workaround:** Use `start` ELs on the element following the gateway to execute the required logic. This allows handling of any post-execution tasks in a dedicated element. + +
+ Example: + +```xml + + + toServiceTaskFlow + + + + + + + // highlight-next-line + + + + toServiceTaskFlow + + +``` + +
+ +By understanding these workarounds, you can effectively design workflows to accommodate the limitations of ELs +and maintain the flexibility and control of your process executions. ## Usage @@ -151,35 +255,16 @@ 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 +- [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. -#### Events +#### Intermediate Catch Events -- **Message Events:** Variables set by ELs can be used to define the message correlation key, +- [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 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 - - -``` +- [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. ## Element processing flow @@ -219,30 +304,30 @@ flowchart LR
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

+

Element Activation:

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

    -
  • Apply Input Mappings (if applicable): Input variables are mapped to the element's local scope.
    • +
  • Apply Input Mappings (if applicable): Input variables are mapped to the element's local scope.
-

Start Execution Listeners

+

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

+

Finalize Activation:

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

    -
  • Subscribe to Events (if applicable): The element subscribes to any events it needs to listen for during its execution.
    • -
  • Element Activated: The element is fully activated and ready to perform its primary function.
    • +
  • Subscribe to Events (if applicable): The element subscribes to any events it needs to listen for during its execution.
    • +
  • Element Activated: The element is fully activated and ready to perform its primary function.
-

Element Execution

+

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

+

Element Completion:

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

    -
  • Apply Output Mappings (if applicable): Output variables are mapped from the element's local scope to the global scope.
    • -
  • Unsubscribe from Events (if applicable): The element unsubscribes from any events it was listening for.
    • +
  • Apply Output Mappings (if applicable): Output variables are mapped from the element's local scope to the global scope.
    • +
  • Unsubscribe from Events (if applicable): The element unsubscribes from any events it was listening for.
-

End Execution Listeners

+

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

+

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.

From 1c79d70377d405c540a7bcc8fb70f555d2df0ac1 Mon Sep 17 00:00:00 2001 From: Philipp Ossler Date: Mon, 5 Aug 2024 14:52:12 +0200 Subject: [PATCH 4/6] docs(concepts): Improve Execution Listener concept - restructure content - remove not relevant parts - change wording to focus on the user needs --- .../concepts/execution-listeners.md | 407 ++++-------------- 1 file changed, 84 insertions(+), 323 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index fd2283897e8..7a8b3134471 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -4,346 +4,107 @@ title: "Execution Listeners" description: "Execution Listeners for process activities" --- -## Introduction +Execution Listeners (EL) 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, and +external system interactions without cluttering the BPMN model with technical details. -### Overview +**Use cases:** -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. +- Pre- and post-processing actions for activities. +- External calculations of variables for element expressions. +- Decoupled processes and data synchronization. -### Benefits +## Define a listener -- **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. +You configure execution listeners in the process per BPMN element. There are two types of listeners: -### Use cases +- 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. -- 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 - -### Start listeners - -Triggers custom logic before the element is processed. Useful for initial data setup or preconditions. - -### End listeners - -Triggers custom logic after the element is processed. Ideal for cleanup operations or post-processing tasks. - -### 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. - -## 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 - - - - - - -``` - -## 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 | ✅ | ✅ | -| | Send 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** | | | | -| | Inclusive Gateway | ✅ | ❌ | -| | Exclusive Gateway | ✅ | ❌ | -| | Parallel Gateway | ✅ | ❌ | -| | Event-based Gateway | ✅ | ❌ | -| **Processes** | | | | -| | Process Instance | ✅ | ✅ | -| **Subprocesses** | | | | -| | Embedded Subprocess | ✅ | ✅ | -| | Call Activities | ✅ | ✅ | -| | Event Subprocess | ✅ | ✅ | +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. + +## Implement a listener + +Execution listeners are a special kind of [job workers](/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. See the +[job workers documentation](/components/concepts/job-workers.md) for details. + +:::note +Throwing a BPMN error for an execution listener's job is not supported. +::: + +## Handle variables in a 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 available variables and the effect of the job variables depend on the listener's +event type. + +### For start listeners + +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 that are created by the variable input +mappings. + +If a start listener completes the job with variables, the variables are set as +[local variables](/concepts/variables/#local-variables) of the element. Following listeners can read the variables. + +You can use variables for the following cases: + +**Gateways** + +- [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. + +**Intermediate Catch Events** + +- [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 that 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. + +### For end listeners + +The end listeners are invoked after applying the variable output mappings and before leaving the element. + +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, the variables are propagated to the element's parent scope, like +variables from the output mappings. Following listeners can read the variables. ## 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). +- **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. + - Boundary Events (Start ELs): Place the start logic in the `start` ELs of the main activity to which the boundary + event is attached. + - Gateways (End ELs): Use `start` ELs on the element following the gateway to execute the required logic. This allows + handling of any post-execution tasks in a dedicated element. + - Error End Event (End ELs): Place the ELs on the related error catch event. + - 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 an validation error. While it's possible to have listeners of 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 will not be executed. The escalation event terminates the element's processing immediately upon activation, + `end` listeners will not be executed. The escalation event terminates the element's processing immediately upon + activation, bypassing any defined `end` listeners. -## Workarounds for unsupported Execution Listeners - -While some BPMN elements do not support `start` or `end` ELs, there are several workarounds to achieve -similar functionality for specific elements. Here are the recommended strategies: - -### Start Events (Start ELs) - -**Workaround:** Use `start` listeners of process instances or subprocesses to cover the missing `start` listeners for specific start events. - -
- Example: - -```xml - - - - // highlight-next-line - - - - - flow1 - - - -``` - -
- -### Boundary Events (Start ELs) - -**Workaround:** Place the start logic in the `start` ELs of the main activity to which the boundary event is attached. - -
- Example: - -```xml - - - - - - - // highlight-next-line - - - - - - - - - - - - - - - -``` - -
- -### Gateways (End ELs) - -**Workaround:** Use `start` ELs on the element following the gateway to execute the required logic. This allows handling of any post-execution tasks in a dedicated element. - -
- Example: - -```xml - - - toServiceTaskFlow - - - - - - - // highlight-next-line - - - - toServiceTaskFlow - - -``` - -
- -By understanding these workarounds, you can effectively design workflows to accommodate the limitations of ELs -and maintain the flexibility and control of your process executions. - -## 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](/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. - -#### Intermediate Catch Events - -- [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 that 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. - -## 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:

-
    -
  • Apply Input Mappings (if applicable): Input variables are mapped to the element's local scope.
    • -
-

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:

-
    -
  • Subscribe to Events (if applicable): The element subscribes to any events it needs to listen for during its execution.
    • -
  • Element Activated: The element is fully activated and ready to perform its primary function.
    • -
-

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:

-
    -
  • Apply Output Mappings (if applicable): Output variables are mapped from the element's local scope to the global scope.
    • -
  • Unsubscribe from Events (if applicable): The element unsubscribes from any events it was listening for.
    • -
-

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) From 21ea0fd77999d383a55d5d6bcbf219a1565f134f Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Mon, 5 Aug 2024 14:33:07 -0400 Subject: [PATCH 5/6] style(formatting): technical review --- .../concepts/execution-listeners.md | 60 +++++++------------ 1 file changed, 23 insertions(+), 37 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index 7a8b3134471..6f75a9d549e 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -1,18 +1,17 @@ --- id: execution-listeners -title: "Execution Listeners" -description: "Execution Listeners for process activities" +title: "Execution listeners" +description: "An execution listener allows users to react to various events in the workflow execution lifecycle by executing custom logic." --- -Execution Listeners (EL) 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, and +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. **Use cases:** -- Pre- and post-processing actions for activities. -- External calculations of variables for element expressions. -- Decoupled processes and data synchronization. +- Pre- and post-processing actions for activities +- External calculations of variables for element expressions +- Decoupled processes and data synchronization ## Define a listener @@ -29,8 +28,7 @@ Each listener has three properties: ## Implement a listener -Execution listeners are a special kind of [job workers](/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. See the +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. See the [job workers documentation](/components/concepts/job-workers.md) for details. :::note @@ -45,8 +43,7 @@ event type. ### For start listeners -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. +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 that are created by the variable input mappings. @@ -58,19 +55,16 @@ You can use variables for the following cases: **Gateways** -- [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. +- [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. -**Intermediate Catch Events** +**Intermediate catch events** -- [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 that 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 +- [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. +- [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. ### For end listeners @@ -84,26 +78,18 @@ variables from the output mappings. Following listeners can read the variables. ## Limitations -- **Unsupported elements**: The following elements do not support `start` or `end` listeners due to their processing - nature: +- **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. - - Boundary Events (Start ELs): Place the start logic in the `start` ELs of the main activity to which the boundary - event is attached. - - Gateways (End ELs): Use `start` ELs on the element following the gateway to execute the required logic. This allows - handling of any post-execution tasks in a dedicated element. - - Error End Event (End ELs): Place the ELs on the related error catch event. - - Compensation Boundary Events: Place the ELs on the compensation handler. + - Start events (start ELs): Use `start` listeners of process instances or subprocesses to cover the missing `start` listeners for specific start events. + - Boundary events (start ELs): Place the start logic in the `start` ELs of the main activity to which the boundary event is attached. + - Gateways (end ELs): Use `start` ELs on the element following the gateway to execute the required logic. This allows handling of any post-execution tasks in a dedicated element. + - Error end event (end ELs): Place the ELs on the related error catch event. + - 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 an validation error. - While it's possible to have listeners of the same `type` if they are associated with different `eventType` values. + 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. -- **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. +- **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. ## Learn more From 09ad10e741b568391a9af114320bc8a13fc2b7fd Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Wed, 7 Aug 2024 12:48:16 +0300 Subject: [PATCH 6/6] docs(concepts): improve documentation - improve some wordings & formatting - fix broken links - add `Execution listener` term to glossary --- .../concepts/execution-listeners.md | 22 +++++++++---------- docs/reference/glossary.md | 6 +++++ 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index 6f75a9d549e..42ee55fa476 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -15,21 +15,21 @@ external system interactions without cluttering the BPMN model with technical de ## Define a listener -You configure execution listeners in the process per BPMN element. There are two types of listeners: +Execution listeners can be configured per BPMN element within a process. There are two types of listeners: -- 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. +- **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). +- `eventType` - Specifies when the listener is triggered (`start` or `end`). - `type` - The name of the job type. - `retries` - The number of job retries. ## Implement a listener -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. See the -[job workers documentation](/components/concepts/job-workers.md) for details. +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. :::note Throwing a BPMN error for an execution listener's job is not supported. @@ -38,7 +38,7 @@ Throwing a BPMN error for an execution listener's job is not supported. ## Handle variables in a 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 available variables and the effect of the job variables depend on the listener's +completing the job with variables. The scope of variables and the effect of the job variables depend on the listener's event type. ### For start listeners @@ -48,8 +48,8 @@ The start listeners are invoked after applying the variable input mappings and b A start listener can read the process instance variables and local variables that are created by the variable input mappings. -If a start listener completes the job with variables, the variables are set as -[local variables](/concepts/variables/#local-variables) of the element. Following listeners can read the variables. +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. You can use variables for the following cases: @@ -73,8 +73,8 @@ The end listeners are invoked after applying the variable output mappings and be 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, the variables are propagated to the element's parent scope, like -variables from the output mappings. Following listeners can read the variables. +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. ## Limitations diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 20d7a4f0641..2aee03f835f 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -64,6 +64,12 @@ An event represents a state change associated with an aspect of an executing pro - [Internal processing](/components/zeebe/technical-concepts/internal-processing.md#events-and-commands) +### Execution listener + +An execution listener is a mechanism that allows users to execute custom logic at specific points during workflow execution. Execution listeners can be attached to BPMN elements to react to lifecycle events, such as when an element starts or ends. This feature facilitates pre-processing and post-processing tasks without cluttering the BPMN model, functioning similarly to job workers by leveraging the same infrastructure. + +- [Execution listeners](/components/concepts/execution-listeners.md) + ### Exporter An exporter represents a sink to which Zeebe will submit all records within the log. This gives users of Zeebe an opportunity to persist records with the log for future use as this data will not be available after log compaction.