Configuring error handling

Each node in your BPMN process can have one or more error mappings that define how Maestro handles errors thrown at runtime. Use the Error mapping property in the properties panel to specify which errors a node catches, under what conditions, and how to route them.

Errors and error mappings

Maestro distinguishes between two related concepts:

• Errors are defined at the process level. They represent named error types that any node in the process can reference.
• Error mappings are defined at the element level. Each node has its own list of mappings that link to process-level errors and define the catch conditions for that specific node.

When a node throws an error at runtime, Maestro evaluates its error mappings in priority order and applies the first mapping whose condition evaluates to true.

Adding an error mapping

1. Select the node on the canvas.
2. In the properties panel, go to Error mapping.
3. Select Add mapping.
4. Configure the mapping fields (see Error mapping properties below).

Error mapping properties

Campo	Description
Erro	The process-level error this mapping catches. Select from the dropdown, or click the menu button to open the error creation dialog and define a new error inline. Selecting an error sets the mapping's errorRef to the ID of the chosen process-level error.
Condição	Defines when this mapping applies. Use the variable picker to build the expression, or switch to the JavaScript or C# editor for complex conditions. Leave empty to catch the error unconditionally.
Detalhes	A free-text description for the mapping. Use this to document the intent of the mapping for your team.

Reordering mappings by priority

Maestro evaluates error mappings in the order they appear. To change evaluation order, drag a mapping to a new position in the list. The mapping at the top is evaluated first.

Error propagation

Once an error mapping matches, Maestro routes the error to the appropriate handler attached to the node:

• Boundary events: The error propagates to the error boundary event attached to the node, and the process follows the boundary event's outgoing path.
• Event subprocesses: Errors raised in the parent process propagate to event subprocesses that use an error start event, triggering centralized error handling defined in the subprocess.

For modeling patterns that use boundary events and event subprocesses, see Errors and recovery.

Creating process-level errors

Process-level errors are shared across all nodes in the process. To create a new error:

1. In the Error field of any mapping, click the menu button.
2. In the dialog that opens, enter a name and, optionally, an error code.
3. Select Create. The error is added to the process and selected in the current mapping.

The same error can be referenced by mappings on multiple nodes.