Skip to content

Commit

Permalink
docs(concepts): improve documentation
Browse files Browse the repository at this point in the history
- improve some wordings & formatting
- fix broken links
- add `Execution listener` term to glossary
  • Loading branch information
ce-dmelnych committed Aug 7, 2024
1 parent fc4292b commit 09ad10e
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 11 deletions.
22 changes: 11 additions & 11 deletions docs/components/concepts/execution-listeners.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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

Expand Down
6 changes: 6 additions & 0 deletions docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 09ad10e

Please sign in to comment.