notes_status

Here is the generated file ./docs/status.md, written in README style and targeted at template-consuming developers who need to set and return the Status object in a Maestro-compatible RPA workflow.

---

# Status Handling Guide for Template Consumers

This document explains how to work with the `Status` object inside the MaestroTaskProcess template.

The `Status` object provides structured, machine-readable execution metadata required by the BPMN engine and must be included in all RPA responses.

This template uses the helper class `StatusBuilder` to standardize how you construct `Status` objects.

---

## ✅ When Do You Set the Status?

You will typically set or update the `Status` object at two points:

1. **At the beginning** — initialize with default or failure status (in `Initialize` or `Teardown`)
2. **At the end or on failure** — overwrite it to reflect the outcome of your processing

---

## 🚀 High-Frequency Usage (Core Methods)

These are the methods most template users will need on a daily basis.

### ✅ `StatusBuilder.SetSuccess(...)`

Sets a success status when your business logic completes successfully.

```csharp
stat = StatusBuilder.SetSuccess(
    code: "Completed",
    details: new Dictionary<string, object> {
        { "recordsProcessed", 42 },
        { "workflow", "InvoiceApproval" }
    }
);

Typically called in your "Processing" sequence or after successful completion of a subworkflow.

---

❌ StatusBuilder.SetNonRetryable(...)

Use when the request is invalid or unsatisfiable, and retrying it will not help.

stat = StatusBuilder.SetNonRetryable(
    errorMessage: "Unsupported operation",
    exceptionType: "InvalidCommandException"
);

Called when inputs are malformed, a feature is unsupported, or validation fails.

---

🔁 StatusBuilder.SetRetryable(Exception)

Use when a transient or system-level issue prevents completion, and retrying may succeed.

Try
    ' business logic
Catch ex As Exception
    stat = StatusBuilder.SetRetryable(ex)
End Try

Retryable failures might include network issues, timeouts, or temporary system errors.

---

🧩 Medium-Frequency Usage (Advanced / Optional)

These are used in slightly more advanced or refined scenarios.

🔧 StatusBuilder.Create(...)

Allows complete control over all fields in the Status object.

stat = StatusBuilder.Create(
    isSuccess: false,
    errorMessage: "Partial failure occurred",
    errorType: "unknown",
    details: customDetailsDict
);

Recommended when building dynamic or conditional status responses.

---

🧼 StatusBuilder.NormalizeDetails(...)

Optionally enrich or sanitize the details dictionary with environment metadata.

details = StatusBuilder.NormalizeDetails(
    details,
    workflow: "CustomerCleanup",
    env: "Test",
    version: "v1"
);

Helpful when multiple developers or systems will interpret the output trace.

---

🛠️ Outputs: stat → out_Status

In your final response assignment (e.g., in "Teardown" or a Finally block):

out_Status = StatusBuilder.ToDictionary(stat)

This ensures the Status object is Maestro-compatible (Dictionary<string, object> with correct keys and formats).

---

🔐 Enums and ErrorType Validation

The allowed values for errorType are:

• "retryable"
• "nonretryable"
• "unknown"

If you provide an invalid value to Create(...), StatusBuilder will throw an exception. Always use the predefined methods when possible.

---

✅ Summary

Scenario	Method
Happy path completed	SetSuccess(...)
Known input/business failure	SetNonRetryable(...)
Transient/system error	SetRetryable(...)
Full control	Create(...)
Enrich details block	NormalizeDetails(...)
Final serialization	ToDictionary(...)

---

For additional examples, see: 📄 status-schema.v1.json 📄 StatusBuilder.cs

Would you like this file saved as a ready-to-commit `.md` file with inline links updated based on actual folder paths?