ADR 004

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

• status-schema.v1.json:contentReference[oaicite:2]{index=2}
• Status.cs
• ErrorContext.cs
• StatusBuilder.cs
• StatusAdapter.cs
• [Global Exception Handler]

Owner

Christian Prior-Mamulyan cprior@gmail.com