ADR-005: Explicit Coupling Between GlobalHandler and MainEntrypoint via Global Error Context

Status

Proposed

Context

The MaestroTaskProcessTemplate relies on a global variable GlobalVariables.err to carry error context from the global exception handler (GlobalHandler.xaml) into the main workflow (MainEntrypoint.xaml), particularly for producing schema-compliant status output.

Due to UiPath Studio limitations, this variable must be typed as Object, and casting is required during access. This creates an implicit contract between the exception handler and teardown logic that must be respected across workflows.

Some may view this as tight coupling. However, this design mirrors precedent in UiPath’s REFramework, which uses global variables (SystemError, TransactionItem, etc.) across loosely structured XAML workflows. Given that this template is designed for expert developers and maintained by a single author, this coupling is a deliberate and accepted trade-off.

Decision

We will explicitly couple GlobalHandler.xaml and MainEntrypoint.xaml via the global variable GlobalVariables.err, relying on:

• A centralized helper class GlobalErrorHelpers for all access
• Convention over configuration to maintain consistency
• Clear documentation of the global contract

This design provides a stable and predictable handoff of error state while minimizing reliance on brittle try/catch patterns.

Rationale

Reason	Justification
✅ Alignment with REFramework	REFramework similarly uses globals to connect workflows and manage state.
✅ Clear ownership	Template is authored and maintained centrally, with strict discipline.
✅ Traceable and testable	Behavior is explicit and lends itself well to testing and logging.
✅ Avoids bloated arguments	No need to pass error objects manually across multiple sequences.
✅ Protectable via helpers	All logic is funneled through GlobalErrorHelpers to reduce misuse.

Consequences

• The err global variable must never be set directly except via GlobalHandler.xaml or GlobalErrorHelpers.
• The Teardown section of MainEntrypoint.xaml assumes a non-null, castable ErrorContext or uses GlobalErrorHelpers.GetOrCreate() to enforce this.
• Any misuse (e.g., assigning a string to err) could lead to runtime exceptions and must be caught in code reviews or tests.

Mitigations

• All access is funneled through GlobalErrorHelpers (includes GetOrCreate(), Set(), HasError(), SetError()).
• Unit and integration tests should verify correct propagation and serialization of error status.
• Annotations in XAML explicitly warn about the contract.

Alternatives Considered

• Passing error via arguments: Rejected due to verbosity and cross-sequence complexity.
• Using exception rethrow/abort only: Incompatible with the need to return schema-compliant status output to Maestro.
• Storing ErrorContext in a persisted queue or file: Overkill and introduces latency.

Related

• ADR-004: Procedural Error Handling and Status Finalization
• GlobalErrorHelpers.cs
• GlobalHandler.xaml
• MainEntrypoint.xaml → Teardown sequence

Owner

Christian Prior-Mamulyan [email protected]