From 1275743ebd120c6f8db6eee749dbd39e773d866a Mon Sep 17 00:00:00 2001 From: Dmitriy Melnychuk Date: Mon, 2 Sep 2024 07:43:01 +0300 Subject: [PATCH 1/4] docs(concepts/EL): improve Execution Listener documentation Scope: - Added details about the blocking behavior of ELs - Described how the system handles incidents raised during EL job or expression failures. - Updated limitations section. - Enhanced documentation structure and added references to relevant resources & code example. --- .../concepts/execution-listeners.md | 29 +++++++++++++++++-- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index 42ee55fa47..fd52280452 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -13,6 +13,11 @@ external system interactions without cluttering the BPMN model with technical de - External calculations of variables for element expressions - Decoupled processes and data synchronization +**Blocking behavior:** + +An execution listener is a blocking operation, meaning that the workflow execution lifecycle will only continue 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. + ## Define a listener Execution listeners can be configured per BPMN element within a process. There are two types of listeners: @@ -26,13 +31,17 @@ Each listener has three properties: - `type` - The name of the job type. - `retries` - The number of job retries. +:::note +If multiple listeners of the same `eventType` (e.g., multiple start listeners) are defined on the same activity, they will be executed sequentially, one after the other, in the order they are defined in the BPMN model. +::: + ## 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. Refer to the -[job workers documentation](/components/concepts/job-workers.md) for more information. +Execution listeners are processed by [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 handler for an execution listener just as you would for a regular job. +Refer to the [open a job worker](/apis-tools/java-client-examples/job-worker-open.md) example to see 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 @@ -76,6 +85,18 @@ 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. +## Recovery after incidents + +During execution listener processing, issues can arise that lead to [incidents](/components/concepts/incidents.md). +These incidents may occur due to job execution failures or problems during expression evaluation. Here's how the system handles these situations: + +- **Job execution failure**: If an execution listener job fails (e.g., an external service is unavailable), it will be retried according to the `retries` property. + 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. + +- **Expression evaluation failure**: Incidents can also occur during the evaluation of an execution listener's properties (e.g., due to incorrect variable mapping or expression syntax). + When this happens, all listeners of the same event type (`start` or `end`) that were processed before the failure will be re-executed once the issue is resolved, even if they had completed successfully before. + ## Limitations - **Unsupported elements**: The following elements do not support `start` or `end` listeners due to their processing nature: @@ -90,10 +111,12 @@ variables from the output mappings. Subsequent listeners can access these variab 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. +- **Throwing a BPMN error**: This operation is not supported for execution listener jobs. ## Learn more - [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) From 9b5533a47e716ce939120980d96a0da07461ba9b Mon Sep 17 00:00:00 2001 From: mesellings Date: Wed, 4 Sep 2024 10:04:48 +0100 Subject: [PATCH 2/4] TW review: Edits for structure, grammar, readability, style --- .../concepts/execution-listeners.md | 119 +++++++++--------- 1 file changed, 63 insertions(+), 56 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index fd52280452..a41499b75e 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -4,101 +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 -**Blocking behavior:** +### Blocking behavior -An execution listener is a blocking operation, meaning that the workflow execution lifecycle will only continue 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. +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. -## Define a listener +## Define an execution listener -Execution listeners can be configured per BPMN element within a process. There are two types of listeners: +You can configure execution listeners per BPMN element within a process. -- **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. +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` (e.g., multiple start listeners) are defined on the same activity, they will be executed sequentially, one after the other, in the order they are defined in the BPMN model. +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 a listener +## Implement an execution listener + +Execution listeners are processed by [job workers](/components/concepts/job-workers.md). -Execution listeners are processed by [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 handler for an execution listener just as you would for a regular job. -Refer to the [open a job worker](/apis-tools/java-client-examples/job-worker-open.md) example to see how to create a job worker and handler that can also process execution listener jobs. +- 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](/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 - -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. - -### For start listeners +## Variables in an execution listener -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. +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. -A start listener can read the process instance variables and local variables that are created by the variable input -mappings. +### Start listeners -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. +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. -You can use variables for the following cases: +- 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. -**Gateways** +You can use variables for the following use cases: -- [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. +| Use case | Description | +| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 |

| -**Intermediate catch events** +### End listeners -- [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. +End listeners are invoked after applying the variable output mappings and before leaving the element. -### For end listeners +- 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. -The end listeners are invoked after applying the variable output mappings and before leaving the element. +## Incident recovery -An end listener can read the process instance variables, the local variables of the element, and the resulting -variables of the output mappings. +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. -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. +The system handles these situations as follows: -## Recovery after incidents +### Job execution failure -During execution listener processing, issues can arise that lead to [incidents](/components/concepts/incidents.md). -These incidents may occur due to job execution failures or problems during expression evaluation. Here's how the system handles these situations: +- If an execution listener job fails (for example, if an external service is unavailable), it is retried according to the `retries` property. +- 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. -- **Job execution failure**: If an execution listener job fails (e.g., an external service is unavailable), it will be retried according to the `retries` property. - 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. +### Expression evaluation failure -- **Expression evaluation failure**: Incidents can also occur during the evaluation of an execution listener's properties (e.g., due to incorrect variable mapping or expression syntax). - When this happens, all listeners of the same event type (`start` or `end`) that were processed before the failure will be re-executed once the issue is resolved, even if they had completed successfully before. +- 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. @@ -108,12 +114,13 @@ These incidents may occur due to job execution failures or problems during expre - 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) From 989978c868885ac63bc6be4fef2e98fd5ad3a3bc Mon Sep 17 00:00:00 2001 From: mesellings Date: Wed, 4 Sep 2024 11:33:06 +0100 Subject: [PATCH 3/4] TW edit: Change bullets to para --- docs/components/concepts/execution-listeners.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index a41499b75e..c41befb4b0 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -93,13 +93,15 @@ The system handles these situations as follows: ### Job execution failure -- If an execution listener job fails (for example, if an external service is unavailable), it is retried according to the `retries` property. -- 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 execution listener job fails (for example, if an external service is unavailable), it is retried according to the `retries` property. + +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. ### 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. +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 From a56777cf71f5d48d6ce88e47e0f7fe214650356e Mon Sep 17 00:00:00 2001 From: mesellings Date: Wed, 4 Sep 2024 11:36:02 +0100 Subject: [PATCH 4/4] TW edit: Removed superfluous sentence --- docs/components/concepts/execution-listeners.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/components/concepts/execution-listeners.md b/docs/components/concepts/execution-listeners.md index c41befb4b0..2be378c28a 100644 --- a/docs/components/concepts/execution-listeners.md +++ b/docs/components/concepts/execution-listeners.md @@ -89,8 +89,6 @@ End listeners are invoked after applying the variable output mappings and before 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. -The system handles these situations as follows: - ### Job execution failure If an execution listener job fails (for example, if an external service is unavailable), it is retried according to the `retries` property.