ADR 004 - rpapub/MaestroTaskProcess GitHub Wiki

ADR-004: Procedural Error Handling and Status Finalization Strategy

Status

Proposed

Context

The MaestroTaskProcessTemplate is a reusable UiPath Studio project designed to serve as a task implementation pattern within UiPath Maestro BPMN workflows. These processes must return structured execution output—most importantly the status object defined by status-schema.v1.json:contentReference[oaicite:0]{index=0}.

Traditional templates like REFramework use state machines and queue items. However, MaestroTaskProcessTemplate is intentionally designed to be procedural and API-like, emphasizing:

  • Structured inputs and outputs (JSON schemas)
  • Synchronous execution as BPMN task elements
  • Clear separation between internal business logic and external Maestro contract formatting

This ADR addresses how we manage status and errors throughout the linear execution flow.

Decision

We adopt the following layered and Go-inspired strategy for error handling and status output:

✅ Procedural Workflow Structure

The MainEntrypoint.xaml follows a linear flow:

  1. Initialize
  2. Validate
  3. Processing
  4. Teardown

No state machines or implicit transaction logic is used.

✅ Centralized Error Context

  • A global variable GlobalVariables.err holds a custom ErrorContext object.
  • This context is initialized in Initialize, optionally populated by the Global Exception Handler, and updated in user code on demand.
  • This replaces the need for scattered error-related variables (errorType, errorMessage, etc.).

✅ Internal Status Model

  • The internal variable stat : Status represents the current execution state.
  • It is initialized using StatusBuilder.Create(...) in Initialize.
  • It is mutated, not reassigned, throughout the workflow.
  • It follows the structure defined in status-schema.v1.json.

✅ Adapter-Based Finalization

  • In Teardown, the existing stat object is updated based on the global ErrorContext using:
    • StatusAdapter.UpdateFromError(stat, err)
    • StatusAdapter.MarkSuccess(stat) (if no error)
  • The final object is converted to JObject using StatusAdapter.ToJObject(stat)
  • The output argument Status : JObject receives this result.

This pattern separates logic-layer mutation from contract-layer serialization, treating StatusAdapter as a formal adapter from Status → JObject.

✅ Global Exception Handling

A standard Studio Global Exception Handler:contentReference[oaicite:1]{index=1} is used to populate the GlobalVariables.err context when unhandled exceptions occur. This allows a unified mechanism to record retryable/non-retryable errors while maintaining forward-only, sequence-driven flow.

Rationale

Design Objective How This Approach Satisfies It
Simplicity Procedural sequences are easier to debug and extend
API contract compliance Status output fully conforms to status-schema.v1.json
Traceability Centralized error state supports detailed reporting
Layered architecture Builders, models, adapters, and utils are clearly separated
Future extensibility Can support retry strategies, payload introspection, or enriched tracing

Consequences

  • Developers working within the template only need to interact with:
    • req : Request
    • stat : Status
    • err : ErrorContext
  • No need to manage dictionary assignments or create output manually.
  • Error flow and status response logic is fully testable and encapsulated.

Related

Owner

Christian Prior-Mamulyan [email protected]