@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-rpa/references/error-handling-guide.md

@@ -0,0 +1,381 @@
+# Error Handling Guide
+
+Production-grade error handling and resilience for modern UiPath projects (Windows / Cross-platform) — XAML and coded. Covers exception taxonomy, Try/Catch discipline, Retry Scope, ContinueOnError, Throw/Rethrow, screenshot-on-error, fail-fast validation, the Global Exception Handler, state recovery, transaction boundaries, idempotent/compensating writes, sensitive-data handling, and retry ownership across layers.
+
+Scope boundary — this guide owns the **decision layer and resilience patterns**. For mechanics owned elsewhere, link out, don't restate:
+
+- Raw `TryCatch` / `Throw` / `Rethrow` XAML shapes + the Rule 24 `Sequence`-wrap → [common-activity-card.md](common-activity-card.md).
+- `ContinueOnError`-swallow gotcha, Studio Web `Throw.Exception` round-trip, `s:Exception` alias → [xaml/common-pitfalls.md](xaml/common-pitfalls.md).
+- Per-activity property surfaces → `activity-docs/UiPath.System.Activities/<ver>/activities/{RetryScope,TryCatch,Throw,Rethrow}.md`.
+- REFramework exception flow, queue retry, `MaxConsecutiveSystemExceptions` → [reframework-guide.md](reframework-guide.md).
+- C# expression-binding mechanics (`CSharpValue`/`CSharpReference`) → [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md).
+- Long-running / persistence interplay → [xaml/long-running-workflow-guide.md](xaml/long-running-workflow-guide.md).
+
+> Legacy (.NET 4.6.1) projects: use [legacy/error-handling-guide.md](legacy/error-handling-guide.md) instead.
+
+VB primary; C# expression forms given inline. Coded (`.cs`) uses the C# forms directly — see [§ Coded](#coded-c).
+
+---
+
+## 1. Exception Taxonomy
+
+Two families. Classify correctly — misclassification either wastes retries on bad data or skips recoverable failures.
+
+| | Business exception | System / Application exception |
+|---|---|---|
+| **Type** | `UiPath.Core.BusinessRuleException` | `System.Exception` (and any other subclass) |
+| **Cause** | Invalid / missing INPUT DATA (bad format, missing field, rule violated) | Transient TECHNICAL failure (app crash, timeout, selector not found, network, file lock) |
+| **Retry fixes it?** | **No** — data won't change on retry; needs a human | **Maybe** — transient, may clear on retry |
+| **Action** | Log, skip item, mark failed | Retry (limited), reset app state, then escalate |
+| **Orchestrator queue Auto-Retry** | Not retried | Retried (when enabled) |
+
+**Rules:**
+
+1. `BusinessRuleException` and `System.ApplicationException` are **siblings** — both inherit directly from `System.Exception`, neither from the other. A `System.Exception` catch matches everything; a `BusinessRuleException` catch matches only business exceptions.
+2. Business classification is **never automatic** — you must `Throw New BusinessRuleException(...)` explicitly. Any unhandled error that isn't an explicit business throw surfaces as a system exception.
+3. Qualify as `UiPath.Core.BusinessRuleException` when ambiguous — the name also exists in other namespaces. `UiPath.Core` is imported by default in new projects, so the short name resolves; use the full name in coded files or on a compiler-ambiguity error.
+4. `Check True` / `Check False` throw `CheckpointException`, **not** `BusinessRuleException`. For business validation use `If` + `Throw New BusinessRuleException(...)`.
+5. **Isolated invoke loses the type:** a `BusinessRuleException` from a workflow invoked with **Isolated** checked arrives at the caller as `System.Exception` (separate process), breaking type-based `Catch` routing. If the caller routes on type, don't use Isolated. If you must, catch inside the isolated workflow and return a structured status / error-code **output argument**, or throw with a stable code prefix the caller matches — never route on the human-readable `Message` (it changes, localizes, and carries variable data).
+
+---
+
+## 2. Choose the Mechanism
+
+| Need | Use | Notes |
+|------|-----|-------|
+| Handle / classify a failure, run compensating logic | **Try/Catch** | Wrap external interactions (UI, file, network, DB) — not assignments or control flow |
+| Auto-retry a flaky action with a success check | **Retry Scope** | Add a Condition to verify the action landed; keep the body idempotent |
+| Reject bad input before any work | **Fail-fast** + `Throw New BusinessRuleException` | Validate all inputs up front (§7) |
+| Tolerate an expected, non-critical failure | **`ContinueOnError=True`** | Narrow set only (§6). Never on data/critical writes |
+| Centralized last-line logging / screenshot across the whole process | **Global Exception Handler** | One per project; not a substitute for local Try/Catch (§8) |
+| Per-transaction retry + system/business split at scale | **REFramework** | [reframework-guide.md](reframework-guide.md) |
+
+Default posture: **fail-fast on bad data, Try/Catch around every external interaction, Retry Scope for transient UI/network steps, GEH for centralized observability.** Don't blanket-wrap pure logic.
+
+---
+
+## 3. Try/Catch Discipline
+
+Raw XAML shape and the mandatory `Sequence` wrap: [common-activity-card.md § TryCatch](common-activity-card.md). Rules that matter for correctness:
+
+1. **Order catches specific → general; `System.Exception` last.** The designer/readers rely on this; a `System.Exception` clause above specific ones makes them unreachable. (Place `BusinessRuleException`, `TimeoutException`, `SelectorNotFoundException` first.)
+2. **Never leave a Catch empty** — violates Workflow Analyzer `ST-DBP-003`. At minimum `Log Message` the exception. Applies to XAML and coded alike.
+3. **Catch only what you'll act on.** Wrap external interactions; don't wrap a whole `Process.xaml` in a catch-all that hides where the failure was.
+4. **`Finally` is cleanup only** — close/kill apps, dispose connections, delete temp files. No business logic. Use `ContinueOnError=True` on best-effort cleanup so a missing resource doesn't mask the original error.
+5. **`Finally` DOES run when the Catch rethrows** (modern, verified) — cleanup is safe to place there even on a rethrow path. (Older legacy-era guidance claiming Finally is skipped on Rethrow does **not** apply to modern Windows / Cross-platform projects.)
+6. **Don't design business recovery around runtime/process termination.** Out-of-memory, a killed host process, and UiPath fatal faults can tear the job down without your Catch/Finally running — treat them as unrecoverable, not as something to handle.
+7. **`exception.Source` returns the activity TYPE, not its DisplayName**, when the Try/Catch and the failing activity are in the same workflow. To capture the failing step's name, move the risky step into its own workflow and wrap the `Invoke Workflow File`.
+
+---
+
+## 4. Throw & Rethrow
+
+Raw XAML shapes: [common-activity-card.md § Throw / § Rethrow](common-activity-card.md). `Throw.Exception` is a **constructor expression**, not a string.
+
+```vb
+' Throw a business exception (build the message in an Assign first for complex text)
+New BusinessRuleException("Invoice " & invoiceId & " amount " & amount.ToString("F2") & " is negative")
+```
+```csharp
+new BusinessRuleException($"Invoice {invoiceId} amount {amount:F2} is negative")
+```
+
+1. **`Rethrow` preserves the original exception type AND stack trace** (verified). Use it inside a `Catch` to log / screenshot, then propagate unchanged. `Rethrow` is Catch-only — outside a `Catch.Action` it throws `InvalidOperationException`.
+2. **Never `Throw New Exception(ex.Message)` to re-surface** — it resets the stack trace to the throw site and drops the type (.NET `CA2200` anti-pattern). Use `Rethrow`. Use `Throw New <Type>(...)` only to *translate* to a different exception type (e.g. wrap a system error as a business one).
+3. Place `Rethrow` last in the `Catch` body — anything after is unreachable.
+
+---
+
+## 5. Retry Scope
+
+Property surface (`NumberOfRetries`, `RetryInterval`, `ContinueOnError`, `LogRetriedExceptions`): [activity-docs/UiPath.System.Activities/26.4/activities/RetryScope.md](activity-docs/UiPath.System.Activities/26.4/activities/RetryScope.md). Two bodies: **Action** (`ActivityBody` — activities to attempt) and an optional **Condition** (`ActivityFunc(Of Boolean)` — a check that the action landed). A retry fires when the Action throws **or** the Condition returns `False`. Verified XAML shape (the property-element names aren't in the activity doc):
+
+```xml
+<ui:RetryScope NumberOfRetries="3" RetryInterval="00:00:05" DisplayName="Retry Scope">
+  <ui:RetryScope.ActivityBody>
+    <ActivityAction>
+      <Sequence><!-- activities to attempt (keep idempotent) --></Sequence>
+    </ActivityAction>
+  </ui:RetryScope.ActivityBody>
+  <ui:RetryScope.Condition>
+    <ActivityFunc x:TypeArguments="x:Boolean">
+      <!-- a Boolean-returning check (Element Exists, or Check True on a stored State).
+           Omit this whole block for exception-only retry. -->
+    </ActivityFunc>
+  </ui:RetryScope.Condition>
+</ui:RetryScope>
+```
+
+`xmlns:ui="http://schemas.uipath.com/workflow/activities"` — the same schema provides `ui:LogMessage` and the `ui:BusinessRuleException` type used in a `Catch`: `<Catch x:TypeArguments="ui:BusinessRuleException">` (verified — the specific catch loads and matches `BusinessRuleException` ahead of `s:Exception`, in both VB and C# expression XAML). The CLR-namespace form `xmlns:uic="clr-namespace:UiPath.Core;assembly=UiPath.System.Activities"` + `uic:BusinessRuleException` is equivalent and is what some bundled samples use — either resolves.
+
+**Verified count semantics — total executions equals `NumberOfRetries` (NOT 1 + retries):**
+
+| `NumberOfRetries` | Action executions |
+|---|---|
+| `0` | **0 — the Action never runs (no-op).** Use `1` for a single guaranteed run. |
+| `1` | 1 (0 retries) |
+| `3` (default) | 3 (1 initial + 2 retries) |
+
+> Verified by run: `=3` runs the Action exactly 3 times then throws the last error; `=0` runs it zero times.
+
+1. **`RetryInterval` is a `TimeSpan`, not a number of seconds.** The literal `3` is parsed as a TimeSpan = **3 days**. Write `00:00:05` for 5 seconds (default `00:00:05`).
+2. **Condition logic is inverted vs a while-loop:** Condition `True` **exits**; `False` triggers another attempt. With no Condition the scope is exception-driven only (retries on throw, succeeds on the first error-free run).
+3. **Keep the Action idempotent** — it re-runs in full on every attempt. `Add Queue Item`, `Append Range`, `Write Range`, `Insert Rows`, and payment/order POSTs **duplicate** on retry. Retry Scope has no built-in dedup; guard mutations with an existence check or idempotency key.
+4. **Nest Retry Scope INSIDE Try/Catch** (retry innermost). After exhausting attempts it rethrows the last error to the outer Catch.
+5. **Modern UI Automation `Click` / `Type Into` have built-in "Verify execution" retry** — prefer it for single UI steps; reach for Retry Scope for multi-step blocks. In modern design, `Check App State` can't sit directly in the Condition — store its `State` to a Boolean and reference that.
+6. **Orchestration Processes:** Retry Scope (and `Delay`) are unsupported in `Main` — wrap in a `No Persist Scope`.
+7. **Retry attempts are near-invisible by default** — `LogRetriedExceptions=False`, and when enabled `RetriedExceptionsLogLevel` defaults to `Trace`, below the usual Orchestrator log level, so retry evidence disappears. Enable it and set the level intentionally, or log the attempt count yourself.
+
+---
+
+## 6. ContinueOnError
+
+`ContinueOnError=True` tells an activity to **suppress its fault and continue** — for activities and error types that honor it, the activity doesn't throw, so an enclosing `Catch` never fires and the failure is silent. It is **not a universal shield**: some activities/exceptions ignore it (e.g. a `NetHttpRequest` timeout still throws — rule 3 below). Default `False`. Workflow Analyzer `UI-ANA-017` flags every `True`. Background: [xaml/common-pitfalls.md](xaml/common-pitfalls.md).
+
+1. **First thing to check when "my Try/Catch isn't catching"** — a `ContinueOnError=True` on the activity (or its scope) ate the error.
+2. **On a scope activity** (`Use Application/Browser`, `Attach`, `Retry Scope`, `On Element Appear`, `Trigger Scope`) `True` **cascades** — it suppresses errors from every nested child, including intentional business throws. Set it on the specific child, never the scope, unless you mean to silence the whole block.
+3. **HTTP failure behavior differs by activity — handle the one you use:**
+   - **Modern HTTP Request (`NetHttpRequest`)** — `ContinueOnError=True` by default. A network failure (`HttpRequestException` — DNS / SSL / refused) becomes a synthetic **`503`** response (message in `TextContent`), so it does **not** throw — check `StatusCode`. But a **timeout (`TaskCanceledException`) is NOT caught — it throws even with `ContinueOnError=True`.** For critical calls set `ContinueOnError=False` (network errors then propagate as `HttpRequestException`) and handle timeouts explicitly. ([NetHttpRequest.md § ContinueOnError Behavior](activity-docs/UiPath.Web.Activities/2.5/activities/NetHttpRequest.md))
+   - **Classic `HttpClient`** — with `ContinueOnError=True` the error is swallowed and execution continues with an **unpopulated response and `StatusCode` left at `0`**; a downstream parse of the empty body then crashes. Set `ContinueOnError=False`, or check `StatusCode` before using the body. ([HttpClient.md](activity-docs/UiPath.Web.Activities/2.5/activities/HttpClient.md))
+
+| `ContinueOnError=True` | Verdict |
+|---|---|
+| `Element Exists` / `Check App State` (returns Boolean, never throws) | Fine |
+| Best-effort cleanup in `Finally` (close a maybe-open dialog) | Fine |
+| Data-scrape "next page" selector that vanishes on the last page | OK, paired with an existence check |
+| HTTP / DB write / file write / any output used downstream | **Never** — silent failure → corrupt/empty data |
+
+---
+
+## 7. Fail-Fast Input Validation
+
+Validate **all** required inputs in one `Sequence` at the start, before any business logic. Throw `BusinessRuleException` immediately with the offending value in the message.
+
+```vb
+If String.IsNullOrWhiteSpace(in_InvoiceNumber) Then Throw New BusinessRuleException("Invoice number is empty")
+If in_Amount <= 0 Then Throw New BusinessRuleException("Amount must be positive: " & in_Amount.ToString())
+```
+
+Catch every problem up front, not one run at a time. Don't validate inside loops — validate once before the loop. Guiding principle: **fail fast, fail loud** — surface bad data immediately with context; never let an invalid value flow into business logic and fail obscurely later.
+
+---
+
+## 8. Global Exception Handler (GEH)
+
+A project-wide handler the runtime invokes when an activity faults. **One per project.** Use it for centralized logging / screenshots and a global retry/abort verdict — not as a replacement for local Try/Catch.
+
+### Scaffold
+
+A dedicated workflow with exactly two non-removable, case-sensitive arguments: `errorInfo` (In, `ExceptionHandlerArgs`) and `result` (Out, `ErrorAction`). Both types live in `UiPath.Activities.Contracts` (XAML alias `xmlns:uico="http://schemas.uipath.com/workflow/activities/contracts"`). Verified scaffold:
+
+```xml
+<Activity x:Class="GlobalHandlerX"
+ xmlns="http://schemas.microsoft.com/netfx/2009/xaml/activities"
+ xmlns:ui="http://schemas.uipath.com/workflow/activities"
+ xmlns:uico="http://schemas.uipath.com/workflow/activities/contracts"
+ xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
+  <x:Members>
+    <x:Property Name="errorInfo" Type="InArgument(uico:ExceptionHandlerArgs)">
+      <x:Property.Attributes><RequiredArgumentAttribute /></x:Property.Attributes>
+    </x:Property>
+    <x:Property Name="result" Type="OutArgument(uico:ErrorAction)">
+      <x:Property.Attributes><RequiredArgumentAttribute /></x:Property.Attributes>
+    </x:Property>
+  </x:Members>
+  <!-- Include standard TextExpression.NamespacesForImplementation / ReferencesForImplementation
+       (copy from any project .xaml) AND add UiPath.Activities.Contracts to the namespace list so
+       the ErrorAction enum resolves in expressions. -->
+  <Sequence>
+    <!-- log errorInfo.Exception, optionally screenshot, then set the verdict (verified Assign form): -->
+    <Assign>
+      <Assign.To><OutArgument x:TypeArguments="uico:ErrorAction">[result]</OutArgument></Assign.To>
+      <Assign.Value><InArgument x:TypeArguments="uico:ErrorAction">[ErrorAction.Abort]</InArgument></Assign.Value>
+    </Assign>
+  </Sequence>
+</Activity>
+```
+
+The verdict expression is the imported enum name — `ErrorAction.Abort` — **not** `uico:ErrorAction.Abort` (the `uico:` prefix is XML-only; inside a VB/C# expression it's invalid). `ErrorAction` resolves only if `UiPath.Activities.Contracts` is in `NamespacesForImplementation`.
+
+`errorInfo` exposes: `Exception` (the `System.Exception`), `ActivityInfo` (`.Name`, `.TypeName` of the faulting activity), `RetryCount`, `Variables("name")`, `Arguments("name")`, `WorkflowArguments("name")`.
+
+### Registration
+
+Register the file in `project.json` under `runtimeOptions` (verified — build clean):
+
+```json
+"runtimeOptions": {
+  "exceptionHandlerWorkflow": "GlobalHandlerX.xaml"
+}
+```
+
+1. **One per project.** Cannot be `Main.xaml`. **Not available for Library projects** — libraries must rely on Try/Catch and propagation.
+2. **Removing a GEH is two edits, both required:** delete the handler `.xaml` AND remove the `exceptionHandlerWorkflow` key from `project.json`. Deleting only the file leaves a stale registration pointing at a missing workflow.
+
+### Verdicts — `ErrorAction`
+
+Set `result` to one of (enum `UiPath.Activities.Contracts.ErrorAction`):
+
+| Verdict | Effect |
+|---|---|
+| `Continue` | **Re-throw** the exception (let normal propagation / local Catch handle it). *Not* "skip" — a common community misreading. |
+| `Ignore` | Suppress the error, continue from the **next** activity. |
+| `Retry` | Re-execute the **failed activity**. |
+| `Abort` | Stop the job after the handler finishes. |
+
+### Verdict logic — avoid the runaway loop
+
+The GEH re-enters at **every** call-stack level a fault propagates through, so an unconditional `result = ErrorAction.Retry` compounds — an always-failing activity is retried far more than intended and can loop without end. Always gate the verdict. XAML `If.Condition` expression forms (VB):
+
+1. **Classify first** — business data won't fix itself, so abort: `[TypeOf errorInfo.Exception Is BusinessRuleException]` → set `result = ErrorAction.Abort`.
+2. **Filter the faulting activity type** — don't "retry" scaffolding: `[New HashSet(Of String)({"Throw","Rethrow","TryCatch","RetryScope","Sequence"}).Contains(errorInfo.ActivityInfo.TypeName)]` → `Continue` (re-throw), don't retry.
+3. **Gate retries on `RetryCount`** — `[errorInfo.RetryCount < 2]` → `Retry`, else `Abort`.
+
+### Interplay and limits
+
+- **When the GEH fires — three cases:**
+  1. **Caught and handled** — the faulting activity's own Try/Catch catches it (no rethrow): GEH does **not** fire.
+  2. **Fully unhandled** — nothing up the call stack catches it: GEH fires, then its verdict applies. Verified under `uip rpa run`.
+  3. **Nested / call-stack** — version-sensitive: some Studio versions invoke the GEH *first-chance*, before a local `Catch`, for an activity nested in a `Sequence` inside `Try` (reported in 25.0.157). Don't assume a local Try/Catch always shields the GEH in deeply-nested code. See [UiPath Global Exception Handler docs](https://docs.uipath.com/studio/latest/user-guide/global-exception-handler).
+- **Retries activities, not workflows.** To retry a whole workflow, wrap it in your own loop / Retry Scope.
+- **Don't combine with REFramework** — REFramework's per-state Try/Catch and the GEH fight; business exceptions get caught/retried and can loop. Pick one strategy.
+- **Debugging:** on a fault Studio pauses, highlights the activity, shows the exception in **Locals** / **Call Stack**; the ribbon offers Continue / Retry / Ignore / Abort. The debug **Retry** button does **not** invoke the GEH; only Continue does.
+
+**Verifying the GEH:** to fire it, run a workflow that throws an **unhandled** error — a `Throw` not wrapped in a local Try/Catch. Verified by run: with the handler registered, `uip rpa run` executes the handler (its logs appear) and honors the verdict — e.g. returning `Ignore` skips the faulting activity and the run completes with `hasErrors:false`. An agent that needs to exercise GEH logic just triggers an unhandled error.
+
+---
+
+## 9. Screenshot-on-Error
+
+For unattended post-mortem, capture a screenshot in the Catch (or GEH) before propagating. Modern activity: **Take Screenshot** (`UiPath.UIAutomationNext.Activities.NTakeScreenshot`, package `UiPath.UIAutomation.Activities`).
+
+1. **Use an absolute path** including folder + `.png` — relative paths resolve into the NuGet cache. Create the directory first.
+2. **Set `ContinueOnError=True` on the capture** so a failed screenshot doesn't abort the handler.
+3. **Take Screenshot needs an interactive session** — under unattended Robots with no display it fails (`Win32Exception 0x80004005`) or silently writes nothing. For reliable unattended post-mortem prefer **Orchestrator session recording** (Robot 2023.2+) over the activity.
+4. **Treat screenshots as sensitive data** — they routinely capture PII, credentials, invoices, and open sessions. Write to an access-controlled folder / storage bucket (not a world-readable temp), name files by job/transaction id + timestamp, set a retention + cleanup policy, and don't attach raw screenshots to logs that ship to a broad audience.
+
+---
+
+## 10. Logging Exceptions
+
+1. **Log `exception.ToString()`** (type + message + full stack), not just `.Message` — `.Message` alone loses the root cause. Guard null: `If(exception IsNot Nothing, exception.ToString(), "<missing>")`.
+2. **Level:** `Error` for caught system exceptions; `Warn` for recoverable business exceptions; `Fatal` for unrecoverable. Only `Trace`/`Verbose` capture argument values (PII risk) — don't log secrets.
+3. **Log before you handle** — emit the exception detail before the Catch swallows or rethrows it.
+4. **Limits:** `Log Message` truncates at 10,000 chars; Automation Cloud drops robot logs > 50 KB. The Orchestrator robot log level overrides local config (default `Information`).
+
+---
+
+## 11. Recover to a Known State Before Retrying
+
+Retrying a UI or system action without resetting state usually repeats the failure or corrupts data. After a system exception, **before the next attempt**:
+
+1. Dismiss blocking popups / modal dialogs.
+2. Return the app or browser to a known anchor (home / search page); reattach, or close and reopen if the window is gone.
+3. Clear partially-entered form data; discard half-built records.
+4. Re-login if the session expired or timed out.
+5. Clean up partial artifacts (temp files, interrupted downloads).
+6. **Verify the expected screen is present** (`Check App State` / `Element Exists`) before re-running the action.
+
+Wire this reset into the Retry Scope Action (run it first, ahead of the real step) or into the Catch before a manual retry. Rule: **a retry that skips state recovery is usually a bug.**
+
+## 12. Transaction Boundary (outside REFramework)
+
+Scope error handling to **one item**, not the whole loop, so a single bad item can't abort the batch. Two recipes by source:
+
+**Queue-backed — let Orchestrator own retry.** Get a queue item, process, then set its status with `Set Transaction Status`:
+- **Success** on completion.
+- **BusinessException** on bad data → Orchestrator does **not** retry; flagged for human review.
+- **ApplicationException** on a transient/system failure → Orchestrator retries per the queue's `Max # of retries`.
+
+Don't wrap your own per-item retry loop on top — the queue owns transaction retry (§15). Carry the item `Reference` / id in every log line.
+
+**DataTable / list — own a status column + bounded in-workflow retry.** No queue, so you own status and retry:
+
+```
+For each row/item:
+  Try
+    Validate                  ' Throw BusinessRuleException on bad data
+    Process                   ' external interactions
+    Status column = "Success"
+  Catch BusinessRuleException  ' bad data — do NOT retry
+    Status = "Failed: business"; log; continue to next item
+  Catch Exception              ' transient — bounded retry of the SAME item, then escalate
+    Status = "Failed: system"; log
+  Finally
+    Persist the status column; release per-item resources
+```
+
+1. **One Try/Catch per item** — a single bad item must not abort the batch.
+2. `BusinessRuleException` → mark failed/skipped, continue. System exception → bounded retry of the **same** item, then escalate.
+3. Persist per-item status and release resources in `Finally`; include an **item id / correlation id** in every log line.
+
+## 13. Compensation & Resume-Safe Writes
+
+A failure partway through external writes leaves partial side effects. Make writes safe to re-run:
+
+1. **Idempotency key** on API creates (client-generated id or `Idempotency-Key` header) so a retried create doesn't duplicate.
+2. **Check-before-create** when no key is available — query by natural key first. **Not concurrency-safe on its own:** two robots can both check, see nothing, and both create. Back it with a server-side unique constraint / upsert, a lock or reservation record, or a downstream reconciliation pass — don't rely on the check alone.
+3. **Record the external id immediately** after creation (persist before the next step) so a resumed run continues from it instead of re-creating.
+4. **Never blindly retry a non-idempotent write** (payment, append, keyless POST) — see §5 rule 3.
+5. **Define compensation** for partial work: delete the created draft, void the transaction, or mark the record for manual reconciliation.
+
+## 14. Sensitive Data in Logs & Screenshots
+
+Error paths are where secrets leak — exceptions and screenshots capture live data.
+
+1. **Never log** credentials, auth headers/tokens, full request/response bodies, bank/card numbers, full customer identifiers, or document images unless explicitly approved. Redact or hash first.
+2. `exception.ToString()` is right for the stack trace (§10), but the **message may still contain secrets or input values** — sanitize messages you build; don't echo raw input.
+3. Treat screenshots as sensitive data — restricted storage, id+timestamp naming, retention/cleanup, access control (§9).
+4. `Trace` / `Verbose` capture argument values (PII) — keep them out of production, and don't defeat the project's excluded-logged-data settings (`Private:*`, `*password*`).
+
+## 15. Who Owns the Retry — Pick One Layer
+
+Retries **stack multiplicatively**: 3 local × 3 queue × 3 job = up to 27 executions of the same work, with duplicate side effects. Assign one owner per concern.
+
+| Layer | Owns | Don't use it for |
+|---|---|---|
+| **Orchestrator queue retry** (`Max # of retries`) | Business-transaction retry, when queues are used | short transient UI blips |
+| **Retry Scope** | Short transient retry around **one** flaky action | whole-transaction retry |
+| **Global Exception Handler** | Centralized logging/screenshot + a global verdict | business-transaction retry (§8) |
+| **Orchestrator job/process retry** | Whole-job restart (use sparingly) | per-item or per-action retry |
+
+1. Queues present → queue retry owns transaction retry; keep Retry Scope for sub-second UI flakiness only.
+2. **Don't enable retry at every layer** — pick the lowest layer that fully resets state (§11) and disable the rest.
+
+---
+
+## Coded (C#)
+
+Coded workflows use the same types and rules:
+
+```csharp
+if (string.IsNullOrWhiteSpace(invoiceNumber))
+    throw new BusinessRuleException($"Invoice number is empty");   // using UiPath.Core;
+try { /* external interaction */ }
+catch (BusinessRuleException) { Log("business error", LogLevel.Warn); throw; }  // bare throw = preserve stack
+catch (Exception ex)         { Log(ex.ToString(), LogLevel.Error); throw; }
+```
+
+- `throw;` (bare) preserves the stack trace; `throw ex;` resets it — same `CA2200` rule as Rethrow vs Throw-new.
+- Workflow Analyzer rules (`ST-DBP-003`, etc.) apply to `.cs` workflows too.
+- Retry: a plain `for` loop with `try/catch` and a delay, or call a Retry Scope from XAML. C# expression-binding mechanics for XAML activities: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md); coded `using` directives: [coded/coding-guidelines.md](coded/coding-guidelines.md).
+
+---
+
+## Anti-patterns
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Try/Catch isn't catching" | `ContinueOnError=True` on the activity/scope swallowed it | Set `False`; check the enclosing scope too (§6) |
+| "GEH isn't firing" | a local Try/Catch handled the exception (handled errors don't reach it; nested cases vary by version) | throw outside any local Catch to fire it (§8) |
+| "Global handler infinite loop / runaway retries" | unconditional `result = Retry` | Gate `RetryCount`, filter `TypeName`, `Abort` on `BusinessRuleException` (§8) |
+| "Retry ran fewer times than expected" / "ran N, not N+1" | `NumberOfRetries` is TOTAL executions, not extra retries; `0` = no-op | Set N = total runs wanted; `1` = one run (§5) |
+| "RetryInterval waited days" | `3` parsed as 3 days | Use `00:00:05` (§5) |
+| "Duplicate rows / queue items after retry" | non-idempotent Action in Retry Scope | Existence check / idempotency key (§5) |
+| "BusinessRuleException caught as system error" | not thrown explicitly, Isolated invoke, or namespace ambiguity | Explicit `Throw New BusinessRuleException`, qualify `UiPath.Core`, avoid Isolated (§1) |
+| Empty `Catch` | silent failure, `ST-DBP-003` | Log at minimum (§3) |
+| `Throw New Exception(ex.Message)` to re-surface | resets stack, drops type | `Rethrow` (§4) |
+| Screenshot works attended, nothing unattended | no interactive session | Orchestrator recording + absolute path (§9) |
+| Same work runs many times / duplicate side effects | retries stacked at multiple layers (local × queue × job) | one retry owner per concern (§15); idempotency on writes (§13) |
+| Retry repeats the failure or corrupts data | action retried without resetting app/data state | recover to a known state first (§11) |
+| Secrets/PII in logs or screenshots | logging raw messages/bodies; unprotected screenshot store | redact; restricted storage (§14) |

package/skills/uipath-rpa/references/is-connector-xaml-guide.md

@@ -36,6 +36,19 @@ Three ingredients:
 2. **`ConnectionId`** — the IS connection's GUID (from `uip is connections list`).
 3. **`Configuration`** — an opaque base64 + gzip JSON blob encoding connector/operation identity. **Never hand-edit.** Always take the value from `activities get-default-xaml`.
 
+## IS activity types & how fields resolve
+
+`get-default-xaml` produces all four IS activity shapes from a `typeId` (+ a live connection). What *unlocks* an activity's fields differs by type — hand the tool the right selector and it returns the resolved `FieldObjects`:
+
+| Activity | What it is | How to resolve its fields |
+|---|---|---|
+| `ConnectorActivity` | A connector operation (create / get / update …) | `typeId` + connection. A **generic** operation needs `--object-name <obj>` (the record type); criteria fields fed back via `--field-values` expand the rest (Step 4). |
+| `ConnectorTriggerActivity` | Fires when a connector event occurs | Curated triggers resolve from `typeId` + connection; a **generic** trigger needs `--object-name <obj>` (the object whose changes it watches). |
+| `ConnectorPersistenceActivity` | Suspends the workflow until a connector event | Discover events with `uip is activities list <connector> --triggers`, then `--event-operation <op>` resolves the event's fields. A named event auto-resolves its single object; a generic/multi-object event also needs `--object-name <obj>` (Step 4). |
+| `ConnectorHttpActivity` | Generic HTTP-request escape hatch | Standard request fields (`method`, `url`, `headers`, `query`, `body`) — author them directly; they are the same for every connector. |
+
+Same principle throughout: **pass the selector the activity needs, get back its resolved schema.** A bare call (no selector) returns the correctly-typed activity with its baseline fields.
+
 ## Step-by-Step Flow
 
 ### Prereq: `uip login`
@@ -73,7 +86,7 @@ If `activityTypeId` is empty, the activity is a non-dynamic BAF/vendor activity
 
 **`activities find` is not exhaustive — be ready to iterate.** Results vary by connector: some expose 6+ typed operations with rich descriptions (Slack); others expose only 1-2 (Outlook). Try several query phrasings (`"send email"`, `"<connector> send"`, the literal operation name from `uip is activities list`). If no typeId surfaces:
 
-- The operation may only be reachable via the generic `ConnectorHttpActivity` typeId (suffix `...httpRequest...`). Use it as a fallback — the field schema is still read from `uip is resources describe`, but the HTTP method/path live in the Configuration blob's `InstanceParameters`.
+- The operation may only be reachable via the generic `ConnectorHttpActivity` typeId (suffix `...httpRequest...`). Use it as a fallback — see [Typed Operation vs Generic HTTP](#typed-operation-vs-generic-http) for its standard, connector-independent request fields.
 - Different connectors that share a schema (e.g. a mock connector + its real counterpart) often share typeIds. The same `fbdeec58-...` "Send Email" typeId works for both `uipath-mock-outlook` and `uipath-microsoft-outlook365` — the `ConnectionId` at runtime determines which backend receives the call. Don't be surprised if the discovered typeId's description mentions a different connector than the one you're targeting.
 
 ### Step 3 — Get the connection ID
@@ -99,11 +112,88 @@ uip rpa activities get-default-xaml \
 
 The response contains the complete `ConnectorActivity` element with:
 - A real `Configuration` blob for that specific connector+operation combo.
-- A complete `FieldObjects` list enumerating every input/output field name.
+- A `FieldObjects` list with one entry per field of the operation's resolved schema (older CLI versions emit only the curated/visible-by-default subset).
 - A real `ConnectionId` (uses the supplied one, or auto-resolves a tenant default).
 
 **Without `--activity-type-id`**, the default comes back essentially empty (`Configuration={x:Null}`, no fields). That generic default is not runnable.
 
+#### Pass field values with `--field-values`
+
+`get-default-xaml` accepts literal input-field values as repeatable `key=value` pairs (one `--field-values` per field). Two effects:
+
+1. **Values are pre-bound** as literals in the returned `FieldObjects` — no hand-editing of `InArgument`/`CSharpValue` for literal values (expressions still go through Step 6).
+2. **Schema expansion.** Many operations expose only a few "criteria" fields by default and reveal the rest of the schema only once those criteria have values. In Studio's designer the re-resolve fires when the user commits a criteria field in the canvas; headlessly, passing the criteria via `--field-values` triggers the same re-resolve, and the `Configuration` blob comes back with the **expanded** field set as new `FieldObjects`.
+
+**Run it twice — discover, then expand.** You won't know a connector's criteria fields ahead of time, so make two calls:
+
+1. **First call — no `--field-values`.** Whatever `FieldObjects` come back are the operation's prerequisite fields. **Those returned field names _are_ your criteria candidates** — there is no separate place to look them up; the curated baseline is the list.
+2. **Second call — feed those same field names back inline** with `--field-values`. The response now carries the expanded schema; author against it.
+
+```bash
+# 1. discover the criteria fields (curated baseline)
+uip rpa activities get-default-xaml --activity-type-id "<TYPE_ID>" --connection-id "<CONN>" --project-dir "<P>" --output json
+# 2. feed those field names back inline to expand the rest
+uip rpa activities get-default-xaml --activity-type-id "<TYPE_ID>" --connection-id "<CONN>" \
+    --field-values <fieldFromStep1>=<value> --project-dir "<P>" --output json
+```
+
+When you already know valid criteria values up front, the second call alone does both.
+
+> **Expansion requires a LIVE connection and real values — there is no offline path.** It is a design-time cloud round-trip to the connector. `--connection-id` must be an enabled connection that resolves on your current `uip login` (correct org + tenant), and each value must actually exist in that system. If the connection is dead / wrong-tenant, or a value is invalid, the call returns the **curated baseline unchanged, with no error and no new fields** — a silent no-op, not a visible failure. So when expansion "does nothing", suspect the connection or the values, never the flag; re-confirm the connection is live (Step 3) before concluding the activity has no more fields.
+
+**Field-name encoding.** Pass names **exactly as they appear in the returned `FieldObjects`** — copy them verbatim from the previous call's output. Don't hand-encode or invent names: the connector's encoding (nested paths, arrays — see § FieldObject Name Encoding Rules) is already applied in what it hands you. An unknown name fails fast with the list of available fields, so use that error as discovery rather than guessing.
+
+**Older CLI fallback:** if `--field-values` is not recognized, upgrade `uip`. Until then the expansion is not reachable headlessly — bind only fields present in the returned XAML and treat missing ones per § Hidden Secondary Fields.
+
+#### Resolve persistence event fields with `--event-operation`
+
+A `ConnectorPersistenceActivity` ("suspend until an event") exposes no event fields until an **event operation** is chosen — the headless equivalent of picking the event in the designer before its fields appear. The event operation is a connector-specific value (e.g. `TICKET_UPDATED`, never the prose "ticket updated"), so **discover it — do not guess it.**
+
+**Step A — list the connector's events** (the same catalog the designer's dropdown uses; no connection needed):
+
+```bash
+uip is activities list <connector-key> --triggers --output json
+```
+
+Each entry's **`Name`** is the value for `--event-operation`; its **`ObjectName`** tells you the kind:
+
+```
+Name            DisplayName      ObjectName   IsCurated
+TICKET_UPDATED  Ticket Updated   tickets      Yes        ← named event: object is built in
+CREATED         Record Created   N/A          No         ← generic op: choose an object too
+```
+
+- **Named event** (`ObjectName` populated, e.g. `TICKET_UPDATED`) — pass its `Name` to `--event-operation`; its single object auto-resolves, so no `--object-name` is needed.
+- **Generic op** (`CREATED` / `UPDATED` / `DELETED`, `ObjectName` is `N/A`) — also pass `--object-name <obj>`. List the objects it applies to with:
+  ```bash
+  uip is triggers objects <connector-key> CREATED --output json
+  ```
+
+**Step B — resolve the activity** with the chosen operation:
+
+```bash
+uip rpa activities get-default-xaml --activity-type-id "<TYPE_ID>" --connection-id "<CONN>" \
+    --event-operation "TICKET_UPDATED" --project-dir "<P>" --output json
+```
+
+The returned `Configuration` carries the resolved event fields as `FieldObjects`. Without `--event-operation` you get the bare activity (correct default, no event fields). It is the persistence analogue of `--field-values` criteria — a selector that unlocks the schema — and the resolution needs a live connection (same cloud round-trip and silent-no-op caveat as above). Combine with `--field-values` to also pre-bind values.
+
+#### Select the object for generic activities with `--object-name`
+
+A **generic** `ConnectorActivity` (Insert / Get / Delete a record) or a generic event has no object baked into its `typeId`, so `get-default-xaml` returns it bare until you name the object — the headless equivalent of the designer's object dropdown. Pass `--object-name <obj>`:
+
+```bash
+uip rpa activities get-default-xaml --activity-type-id "<TYPE_ID>" --connection-id "<CONN>" \
+    --object-name issue --project-dir "<P>" --output json
+```
+
+Discover valid object names (use the `Name` field, not the display name):
+
+- Generic activity → `uip is resources list <connector-key> --output json`
+- Generic event → `uip is triggers objects <connector-key> <EVENT> --output json`
+
+A named event auto-resolves its single object, so `--object-name` is only needed for generic operations and multi-object events. It is the same kind of selector as `--event-operation` (identity that unlocks the schema), needs a live connection, and combines with `--event-operation` and `--field-values`.
+
 ### Step 5 — Read the operation's field schema
 
 For each field you want to bind, you need its declared `name` and `dataType`. Read the schema from Integration Service:
@@ -123,6 +213,8 @@ Read that file directly for the full schema — `parameters`, `requestFields`, `
 
 ### Step 6 — Bind values using `InArgument` + `CSharpValue`
 
+Only needed for **expression** values or when editing an existing XAML — literal values are better passed via `--field-values` in Step 4, which pre-binds them in the returned XAML.
+
 For each field you want populated:
 
 ```xml
@@ -154,7 +246,7 @@ Schema field names from `describe` / the cached JSON (`message.toRecipients`, `s
 
 Apply rules in order; translate every segment for nested paths (`collaborator_ids[*]` → `collaborator_ids_array`).
 
-Default XAML reflects correct encoded names for fields it returns — **copy verbatim**. Default is **not exhaustive**: Secondary fields (arrays especially) are often absent — see [Hidden Secondary Fields](#hidden-secondary-fields).
+Default XAML reflects correct encoded names for fields it returns — **copy verbatim**. With current CLI versions the returned `FieldObjects` cover the blob schema exhaustively; a schema-documented field that is still absent is criteria-gated or a query parameter — see [Hidden Secondary Fields](#hidden-secondary-fields).
 
 #### Matching `x:TypeArguments` to the Field's Data Type
 
@@ -185,15 +277,15 @@ Example — boolean field:
 
 #### Hidden Secondary Fields
 
-Default `FieldObjects` is **not exhaustive**. Schema-defined Secondary fields — arrays especially (`tags[*]`, `collaborator_ids[*]`, `fields[*].id`) — appear in `requestFields` / `optionalFields` / `parameters` but not in the default. Validators all report clean while the connector silently drops the unbound field. Detect via live API result or Studio designer comparison.
+A field is only honored at runtime if it exists in the **`Configuration` blob's schema** — the blob, not the `FieldObjects` list, is the contract. A hand-added `FieldObject` whose field is missing from the blob's schema passes `validate` and `build` clean and is **silently dropped** by the connector at runtime — the API call goes out without it, typically surfacing later as a confusing connector/runtime error (a 4xx about missing or invalid fields) far from the XAML that caused it.
 
-When a requested field is absent from default `FieldObjects`:
+When a schema-documented field is absent from the returned `FieldObjects`:
 
-1. Read schema from `~/.uipath/cache/integrationservice/<connector>/_static/<operation>.Create.json` (or re-run `uip is resources describe`). Confirm field exists in `requestFields` / `optionalFields` / `parameters`.
-2. Read its `type` / `dataType` (includes `[*]` suffix for arrays).
-3. Translate schema name through every encoding rule in order: `.` → `_sub_`, `-` → `minus_sign`, `[*]` → `_array`. Example: `tags[*]` → `tags_array`, `fields[*].id` → `fields_array_sub_id`.
-4. Emit `<isactr:FieldObject Name="<encoded>" Type="FieldArgument">` with `x:TypeArguments` matching the schema `type`.
-5. Insert into `<isactr:ConnectorActivity.FieldObjects>` alongside default entries. Do not reorder or remove existing entries.
+1. **Criteria-gated field** (most common — body/custom fields revealed by prerequisite values): re-run `get-default-xaml` with `--field-values <criteria>=<value> ...` (Step 4) and author against the returned XAML — its blob carries the expanded schema and the field now has a `FieldObject`. Do **not** graft the field into the previous XAML; the old blob does not know it.
+2. **Query parameter**: check the schema's `queryParameters` — those never appear as `FieldObjects` and have no per-field XAML override (see Gotchas).
+3. **Older CLI without `--field-values`**: the expansion is not reachable headlessly. Have a developer commit the criteria fields once in Studio's designer and copy the resulting `Configuration` + `FieldObjects`, or upgrade `uip`.
+
+The name-encoding rules above apply to expanded fields too — reference them by the encoded name **exactly as the expanded XAML returns it**, both in `--field-values` and when binding expression values in Step 6.
 
 ### Step 7 — Validate and run
 
@@ -204,9 +296,17 @@ uip rpa run --file-path "<your-workflow>.xaml" --project-dir "<PROJECT_DIR>" --o
 
 If `HasErrors: true`, the `ErrorMessage` field carries the compile/runtime error.
 
+## Operation output is strongly typed
+
+The operation's result is exposed as an output FieldObject named `Jit_<operation>`, typed to a **generated record type** for that object — so downstream expressions that read its members (`record.id`, `records.First().name`) compile, and `uip rpa build` binds the consuming variable to the right type.
+
+That typed shape is generated from the **live connection's** schema while `get-default-xaml` resolves the activity; there is no flag for it — typing is automatic when resolution succeeds against a connection. If it cannot be generated — no usable connection at resolve time, or a connector schema that won't compile — the output **degrades to `System.Object`**: the activity stays valid, but typed member access no longer compiles. Re-resolve with a valid, enabled connection; treat a `System.Object` output as the signal that typing was skipped.
+
 ## Typed Operation vs Generic HTTP
 
-Every connector exposes a `ConnectorHttpActivity` with a typeId suffixed like `...httpRequest...` — a generic escape hatch for arbitrary HTTP calls. Prefer a **typed operation** (e.g. `send_message_to_channel_v2`) whenever one exists: it encodes the endpoint, method, and field schema for you. Only fall back to the HTTP activity when the connector lacks a modeled operation for what you need. For the generic one, the field names are NOT `method`/`path`/`body` — they're still connector-defined. Read the schema.
+Every connector exposes a `ConnectorHttpActivity` with a typeId suffixed like `...httpRequest...` — a generic escape hatch for arbitrary HTTP calls. Prefer a **typed operation** (e.g. `send_message_to_channel_v2`) whenever one exists: it encodes the endpoint, method, and field schema for you. Only fall back to the HTTP activity when the connector lacks a modeled operation for what you need.
+
+`get-default-xaml` for an HTTP typeId returns a correctly-typed `ConnectorHttpActivity` with a valid `Configuration`. Its fields are the **standard HTTP request fields** — `method`, `url`, `headers`, `query`, `body` (inputs), plus `out_body` / `out_headers` / `out_code` (outputs) — identical across connectors, so author the ones you need directly per Step 6 instead of reading a per-operation schema. The `ConnectionId` still scopes the call at runtime.
 
 ## Worked Example: Slack "Send Message to Channel"
 
@@ -268,6 +368,21 @@ Resulting `ConnectorActivity` body (truncated — preserve the full FieldObject
 </isactr:ConnectorActivity>
 ```
 
+## Worked Example: criteria-gated expansion
+
+Some "edit/update record" operations surface only their prerequisite fields by default (e.g. a record's project + type + key) and reveal the full body schema only once those criteria have values — the headless equivalent of committing those fields in the designer canvas:
+
+```bash
+# Criteria values trigger the schema expansion AND get pre-bound as literals in one call.
+uip rpa activities get-default-xaml \
+    --activity-type-id "<TYPE_ID>" \
+    --connection-id "<LIVE_CONNECTION_ID>" \
+    --field-values <criteria1>=<value> --field-values <criteria2>=<value> \
+    --project-dir "$P" --output json
+```
+
+The returned `Configuration` blob now carries the expanded schema, and the previously hidden body/custom fields appear in `FieldObjects`. Bind remaining values there directly in the same call (literal) or via Step 6 (expression). Authoring one of those expanded fields against the *unexpanded* blob is the silent-drop failure in § Hidden Secondary Fields. Needs a live connection and valid criteria values — see the silent-no-op note in Step 4.
+
 ## Gotchas
 
 1. **JIT OutArgument corruption** — When Studio's designer modifies an IS XAML, it can inject a `<OutArgument x:TypeArguments="uiascb:...<op>_Create" />` into the `Jit_<operation>` FieldObject that references a dynamically-compiled Studio-local assembly. Fresh loads (new Studio session, CI) can't resolve that type and fail to compile with `Unable to create activity builder`. **Strip the offending OutArgument back to `<isactr:FieldObject Name="Jit_<op>" Type="FieldArgument" />`** before shipping or running headlessly. Also remove the `xmlns:uiascb` namespace declaration from the root `<Activity>` element if nothing else references it. Tracked as PILOT-4812.
@@ -285,6 +400,7 @@ Resulting `ConnectorActivity` body (truncated — preserve the full FieldObject
 - **Do not** hand-edit the `Configuration` blob. It's base64 + gzip of an internal serialization — any edit triggers a `breaking change` runtime rejection.
 - **Do not** use `activities get-default-xaml` without `--activity-type-id` for IS activities — the generic default is empty and unusable.
 - **Do not** drop FieldObjects from the default. The full list is part of the schema contract.
+- **Do not** hand-add a `FieldObject` for a field absent from the returned XAML — it validates clean and is silently dropped at runtime. Re-run `get-default-xaml` with `--field-values` to expand the schema instead (§ Hidden Secondary Fields).
 - **Do not** put values in the `FieldObject Value=""` attribute — use `<FieldObject.Value><InArgument><CSharpValue>` elements.
 
 ## Related References

package/skills/uipath-rpa/references/reframework-guide.md

@@ -90,6 +90,8 @@ One execution, no transaction loop. Useful for scheduled jobs that just need REF
 
 ## Exception Handling Strategy
 
+REFramework owns the per-transaction retry/counter flow below. For error-handling patterns **outside** REFramework — Try/Catch discipline, Retry Scope, ContinueOnError, Throw/Rethrow, screenshot-on-error, and the Global Exception Handler — see [error-handling-guide.md](error-handling-guide.md). Do **not** add a Global Exception Handler to a REFramework project (it conflicts with the framework's per-state Try/Catch).
+
 | Exception | Class | Retry? | Counter behavior |
 |-----------|-------|--------|------------------|
 | Business Rule Exception | `UiPath.Core.BusinessRuleException` | No — data won't fix itself | `ConsecutiveSystemExceptions` resets to 0 |