@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-maestro-flow/references/author/plugins/data-fabric/impl.md

@@ -0,0 +1,427 @@
+# Data Fabric Entity Nodes — Implementation
+
+Four OOTB nodes that read and write records in a UiPath Data Fabric entity: `core.datafabric.read`, `core.datafabric.create`, `core.datafabric.update`, `core.datafabric.delete`. Each is a `bpmn:Task` host with no `serviceType`, and the BPMN engine does the actual work — but by two different mechanisms:
+
+- **Read** emits its compiled query as a `<uipath:input>`. The engine's **input preprocessor** resolves it *before* the task runs.
+- **Create / Update / Delete** emit a `<uipath:output>` carrying a `=datafabric...` target. The engine's **activity postprocessor** performs the write *after* the task runs.
+
+That split matters when reading generated BPMN: a Read node with no `<uipath:output>` action target is correct, not a serialization failure.
+
+Shared action-node boilerplate — skeleton, ports, add/edit mechanics — is in [shared/action-nodes.md](../../../shared/action-nodes.md), which these nodes diverge from in **two** ways, both recorded in its Exceptions note: they have no `error` port (see [No error port](#no-error-port)), and they carry no instance `outputs` block at all (see [JSON structure](#json-structure)). This file covers only what is specific to the entity nodes.
+
+## Registry validation
+
+Run `registry get` for each node type you intend to use:
+
+```bash
+uip maestro flow registry get core.datafabric.read --output json
+uip maestro flow registry get core.datafabric.create --output json
+uip maestro flow registry get core.datafabric.update --output json
+uip maestro flow registry get core.datafabric.delete --output json
+```
+
+Confirm on `Data.Node`:
+
+- `handleConfiguration` — input port `input`, output port `output`. All four share this shape, and none has an `error` handle.
+- `model.type` — `bpmn:Task` (**not** `bpmn:ServiceTask`; these nodes carry no `serviceType`).
+- `inputDefinition.properties.entityConfig` — the single input container.
+- `outputDefinition.output.source` — `=response`, with `type: "jsonSchema"`. **Delete has no `outputDefinition` at all** — that absence is the contract, not an omission.
+- `runtimeConstraints.exclude` — contains `api-function`.
+- `version` — copy it verbatim into the instance's `typeVersion`. The four are versioned independently; do not assume one version across the family.
+
+If `registry get` reports **"Node not found"**, the node is not available to you. Run `uip tools update`, then `uip maestro flow registry pull --force`, and retry. If it still fails, that node's tenant feature flag is off:
+
+| Node type | Flag to ask the admin about |
+| --- | --- |
+| `core.datafabric.read` | `canvas.nodes.read-entity` |
+| `core.datafabric.create` | `canvas.nodes.create-entity` |
+| `core.datafabric.update` | `canvas.nodes.update-entity` |
+| `core.datafabric.delete` | `canvas.nodes.delete-entity` |
+
+`registry search` is not a substitute for `registry get` here. A flag-gated node can still appear in search with `AvailableOnTenant: false` while `registry get` refuses it — and without `registry get` you cannot source the `definitions[]` entry, which must never be hand-written ([Author capability, rule 6](../../CAPABILITY.md#critical-rules)).
+
+**When the node is unavailable, switch to the connector and stop.** `AvailableOnTenant: false` is a decision, not an obstacle: build the flow with the `uipath-uipath-dataservice` activities ([connector/impl.md](../connector/impl.md)) and say in the final report that the native nodes were unavailable. Do not retry `registry get`, do not run `uip tools update` hoping for a newer manifest, and above all **do not hand-author a `definitions[]` entry from this doc's field list to stand in for the missing one** — a hand-written definition carries the wrong port schema, passes `flow validate`, and fails at runtime.
+
+## Add or edit the node
+
+These are OOTB nodes and therefore **user-owned**: author them with `Edit` / `Write` directly against the `.flow` file. `inputs.entityConfig` is a plain JSON object, not a `=jsonString:` envelope, so none of the CLI-owned node rules apply. See [Author capability — Node ownership](../../CAPABILITY.md#node-ownership--who-authors-the-node) and [editing-operations.md](../../editing-operations.md).
+
+Every node type still needs its `definitions[]` entry copied verbatim from `registry get`.
+
+## No error port
+
+These four nodes are the exception to the implicit-error-port rule in [shared/action-nodes.md](../../../shared/action-nodes.md). None of them declares `supportsErrorHandling`, so the canvas never injects an `error` handle and the properties panel offers no error-handling toggle.
+
+Do not set `inputs.errorHandlingEnabled`, and do not add an edge with `sourcePort: "error"`. Such an edge still serializes a boundary event — keyed purely on the handle name — but the node has no `outputDefinition.error` to map, so it emits with no error mapping and shows no handle the author can see or remove. Handle failure upstream (validate inputs before the node) or downstream (branch on the result), not with an error edge.
+
+## Resolving the entity, its scope, and its columns
+
+Entity and column names are **case-sensitive**, and an unmatched column is silently dropped rather than rejected — a wrong name yields a node that validates green and writes nothing. Resolve everything from the tenant before authoring.
+
+`uip df entities list` shows **tenant-level entities only** by default. A folder-scoped entity will not appear until you widen the scope:
+
+```bash
+# Tenant-level only (default)
+uip df entities list --output json
+
+# Tenant + every folder you can see
+uip df entities list --include-folders --output json
+
+# One folder (mutually exclusive with --include-folders)
+uip df entities list --folder-key <folder-uuid> --output json
+
+# Writable entities only — Create/Update/Delete need a native entity
+uip df entities list --native-only --include-folders --output json
+```
+
+Each listed entity carries its `folderId`. That value is both the `--folder-key` for follow-up commands and the `_folderKey` you put on a folder-scoped `entityConfig`.
+
+Column names and a live record follow the same scoping rule — a folder-scoped entity needs `--folder-key` on each:
+
+```bash
+uip df entities get <entity-id> [--folder-key <folder-uuid>] --output json
+uip df records list <entity-id> [--folder-key <folder-uuid>] --output json
+```
+
+`entities get` gives the exact column names for `_filters`, `fieldValues`, `fieldUpdates`, and `_selectedFieldNames`, plus each column's type, nullability, and whether it is a system field. Read a real record before writing a `byId` selector — an invented id matches nothing, and a read that matches nothing does not fault.
+
+## JSON structure
+
+Node instances carry `inputs` only. Do **not** hand-write an `outputs` block, a `model` block, or a `ui` block — `flow format` owns layout, the definition owns the BPMN model, and the manifest's `outputDefinition` plus the `variables.nodes[]` entry that `flow format` regenerates own the output contract ([Author capability, rules 13–15](../../CAPABILITY.md#critical-rules)).
+
+### Read — single record
+
+```json
+{
+  "id": "readOrder",
+  "type": "core.datafabric.read",
+  "typeVersion": "<from registry get>",
+  "display": { "label": "Read order" },
+  "inputs": {
+    "entityConfig": {
+      "entityName": "Orders",
+      "resultMode": "single",
+      "_filters": {
+        "logicalOperator": "AND",
+        "rows": [
+          { "field": "OrderNumber", "operator": "=", "value": "=js:$vars.start.output.orderNumber" }
+        ],
+        "groups": []
+      }
+    }
+  }
+}
+```
+
+A single-record read faults only on an **over**-match. Zero matches completes normally, leaving `$vars.readOrder.output` unresolved — so treat "not found" as a branch, not an error.
+
+### Read — multiple records
+
+```json
+{
+  "id": "listOpenOrders",
+  "type": "core.datafabric.read",
+  "typeVersion": "<from registry get>",
+  "display": { "label": "List open orders" },
+  "inputs": {
+    "entityConfig": {
+      "entityName": "Orders",
+      "resultMode": "multiple",
+      "_recordLimit": 100,
+      "_skip": 0,
+      "_sort": { "field": "CreateTime", "direction": "desc" },
+      "_selectedFieldNames": ["Id", "OrderNumber", "Status"],
+      "_filters": {
+        "logicalOperator": "AND",
+        "rows": [{ "field": "Status", "operator": "=", "value": "Open" }],
+        "groups": []
+      }
+    }
+  }
+}
+```
+
+The rows land at `$vars.listOpenOrders.output.results`, not `$vars.listOpenOrders.output`.
+
+The emitted query **always** carries an explicit `limit`: omitting `_recordLimit` resolves to **100**, and any value is clamped to 1–1000. 1000 is a hard ceiling, so the only way to cover a larger entity is to page with `_skip` — raising `_recordLimit` past 1000 silently truncates. Pair any limit with `_sort`, or the slice is arbitrary.
+
+`CreateTime` above is the real server-managed audit column. The audit columns are `Id`, `CreateTime`, `CreatedBy`, `UpdateTime`, `UpdatedBy` — there is no `CreatedAt`, and a sort on a non-existent column is not caught by `flow validate`.
+
+### Create
+
+```json
+{
+  "id": "createOrder",
+  "type": "core.datafabric.create",
+  "typeVersion": "<from registry get>",
+  "display": { "label": "Create order" },
+  "inputs": {
+    "entityConfig": {
+      "entityName": "Orders",
+      "fieldValues": [
+        { "field": "OrderNumber", "value": "=js:$vars.start.output.orderNumber" },
+        { "field": "Notes", "value": "Created by flow" }
+      ]
+    }
+  }
+}
+```
+
+At least one row must carry a non-blank `value`. A blank value is **omitted** from the insert so the column default applies — so an all-blank `fieldValues` serializes to an empty body, emits no output, and runs green having inserted nothing. The validator rejects that case; do not work around it by adding a placeholder value.
+
+### Update
+
+```json
+{
+  "id": "markShipped",
+  "type": "core.datafabric.update",
+  "typeVersion": "<from registry get>",
+  "display": { "label": "Mark shipped" },
+  "inputs": {
+    "entityConfig": {
+      "entityName": "Orders",
+      "recordSource": "fromRead",
+      "readEntityNodeId": "readOrder",
+      "fieldUpdates": [
+        { "field": "Notes", "value": "Shipped by flow" },
+        { "field": "ShippedAt", "value": "=js:$vars.start.output.shippedAt" }
+      ]
+    }
+  }
+}
+```
+
+`readEntityNodeId` must match the Read node's `id` exactly — see [Record selection](#record-selection) for what happens when it does not.
+
+Timestamps come in as ISO 8601 strings from a variable or an upstream [Script](../script/impl.md) node, as above. Do not reach for `new Date()` in a `=js:` value — the Jint runtime's `Date` support is limited ([variables-and-expressions.md](../../../shared/variables-and-expressions.md)), and here a value the serializer cannot coerce is rejected by Data Fabric and the rejection is swallowed, so the column simply stays unchanged.
+
+### Delete
+
+```json
+{
+  "id": "removeDraft",
+  "type": "core.datafabric.delete",
+  "typeVersion": "<from registry get>",
+  "display": { "label": "Remove draft" },
+  "inputs": {
+    "entityConfig": {
+      "entityName": "Orders",
+      "recordSource": "byId",
+      "recordId": "=js:$vars.start.output.orderId"
+    }
+  }
+}
+```
+
+## Write bodies
+
+Both write editors take `[{ field, value }]` rows, but what a value means differs by verb and by column type. The serializer coerces each value using the column's declared type from the `_outputSchema` snapshot; a value it cannot coerce is passed through as a string for the API to reject, **and that rejection is only logged** — it surfaces as an unchanged row, not a failed run.
+
+| Column kind | What the row's `value` must be |
+| --- | --- |
+| String | The text itself |
+| Integer / number | A clean numeric literal. `42.5` in an integer column is not coerced and is rejected |
+| Boolean | `true` or `false` |
+| **Choice set (single)** | The choice's numeric **`numberId`**, not its label — the column's SQL type is `INT` |
+| **Choice set (multi)** | A JSON array of those numeric ids, as a **string**: `{ "field": "Tags", "value": "[1,2]" }`. The column is `NVARCHAR`, so the text is written through uncoerced and Data Fabric parses the array itself — not a real JSON array in the `value` slot |
+| **System columns** | Never writable — see below |
+| **Attachment columns** | Never writable |
+
+**System columns are `Id`, `CreateTime`, `CreatedBy`, `UpdateTime`, `UpdatedBy`.** Data Fabric assigns them. The canvas hides them from both write editors, but the serializer has no guard: a hand-authored `{ field: "Id", … }` or `{ field: "UpdatedBy", … }` satisfies the validator's "at least one field" rule, ships in the body, and is rejected and swallowed.
+
+**Blank values differ by verb.** On Create a blank value is omitted, letting the column default apply. On Update a blank value writes an explicit `null`, which **a non-nullable column rejects** — so "clear the column" only works on a nullable one. Nullability is not carried in the node's snapshot, so check it with `uip df entities get`.
+
+## Schema snapshots
+
+The entity panels persist snapshots of the picked entity onto `entityConfig`: `_entityFields`, `_relatedFields`, `_outputSchema`, `_choiceSets`, `_entityDisplayName`. When editing a node the canvas created, **preserve every one you are not deliberately changing.**
+
+They are not decoration, and two of them are load-bearing when authoring from scratch:
+
+- **`_entityFields` is mandatory for any dotted related path.** A filter on `customer.Name` resolves its first segment against this snapshot; without it the path is unresolvable, and the serializer refuses **the whole query** — the node emits nothing and every downstream `$vars` reference breaks. Related paths are capped at 3 segments, and a 3-segment path's last segment must literally be `Id`.
+- **`_outputSchema` is the only input to write-body type coercion.** Without it nothing is coerced: `{ field: "Quantity", value: "5" }` serializes as the string `"5"` on an integer column, is rejected, and is swallowed.
+
+So a from-scratch node is safe with plain scalar filters and string columns, and needs these snapshots as soon as it touches a related path, a typed column, or a choice set. When you cannot produce them, keep the config to columns on the entity itself and let the canvas fill the rest in on first open.
+
+## Filters
+
+`_filters` uses a grouped query model:
+
+```json
+{
+  "logicalOperator": "AND",
+  "rows": [{ "field": "Status", "operator": "=", "value": "Open" }],
+  "groups": [
+    {
+      "logicalOperator": "OR",
+      "rows": [
+        { "field": "Priority", "operator": "=", "value": "High" },
+        { "field": "Amount", "operator": ">", "value": "1000" }
+      ]
+    }
+  ]
+}
+```
+
+Rows at the root and each group's rows join by that level's own `logicalOperator`. A bare array of rows is the legacy form and is still read, but author the grouped object.
+
+**Supported operators**, exactly as spelled in the file:
+
+`=` · `!=` · `>` · `>=` · `<` · `<=` · `contains` · `starts with` · `ends with` · `in`
+
+`in` takes a comma-separated `value` and is honoured **only** when `resultMode` is `"multiple"`. There is deliberately no `not in`, `not contains`, or null check — the serializer cannot emit them. `is any of` is the legacy spelling of `in` and is still read.
+
+A filter on a choice-set column compares against the numeric `numberId`, exactly as a write does — comparing against the label matches nothing.
+
+Filter values may be literals or `=js:` expressions. Two rules the serializer enforces by refusing the **entire** query — which leaves the node with no output and breaks every downstream reference:
+
+- **A filter value cannot reference `$self`,** and cannot use a value the engine's query bracket cannot carry. A query cannot wait on the record it is being run to fetch.
+- **An expression switched on and left blank is refused,** rather than dropped. Dropping it would silently widen the read past what was written.
+
+## Record selection
+
+Update and Delete name one record through `recordSource`:
+
+| `recordSource` | Required key | Resolves to |
+| --- | --- | --- |
+| `"byId"` | `recordId` | The record with that `Id`. A literal, or a `=js:` reference such as `=js:$vars.createOrder.output.Id` |
+| `"fromRead"` | `readEntityNodeId` | The record the named Read node's query identifies — the query is recompiled, with `Id` forced into the selected fields |
+
+Both selectors are validated as **non-blank after trimming**, because the serializer trims before deciding a selector is usable. A whitespace-only `recordId` is not "empty enough" to be an obvious mistake but is exactly as inert.
+
+> **An absent `recordSource` does not mean the node is inert.** The validator requires the key, but the *serializer* infers the mode from whichever selector field is populated — `readEntityNodeId` wins, otherwise a non-blank `recordId` means `byId`. So a legacy or hand-edited config carrying `{ entityName, recordId }` and no `recordSource` compiles a **real** delete or update. Never read a missing `recordSource` in an existing file as dead code; resolve it explicitly.
+
+A `fromRead` target fails **silently** in three ways, none of which any validation rule catches, because each makes the serializer emit a plain no-op task:
+
+1. `readEntityNodeId` names a node that does not exist (a typo, or a node id that changed).
+2. The named Read is `resultMode: "multiple"` — a multi-record read is refused as a write target.
+3. The named Read's filters do not all compile.
+
+And at runtime, if the read matches more than one record, the engine re-runs the query as a single-record fetch and **swallows** the resulting over-match — the write is skipped and the run goes green. (The same over-match faults an ordinary read; only the write path swallows it.) A `fromRead` target must therefore be a genuinely single-record read, verified by you rather than by the runtime.
+
+## Folder-scoped entities and bindings
+
+A **tenant-scoped** entity needs nothing beyond `entityName`; the target serializes as `=datafabric.<EntityName>`.
+
+A **folder-scoped** entity carries `_folderKey` (the entity's `folderId`). Its presence switches the emitted target to the folder-qualified form, and for the flow to survive export to another org the entity's name and folder must serialize as binding tokens rather than source-org literals. That requires:
+
+1. `_resourceKey` (preferred) or `_entityKey` on the `entityConfig`, and
+2. two top-level `bindings[]` rows for that key, with `resource: "Entity"` and `propertyAttribute` of `name` and `folderKey`.
+
+```json
+"bindings": [
+  {
+    "id": "bOrdersEntityName",
+    "name": "Orders",
+    "type": "string",
+    "resource": "Entity",
+    "resourceKey": "<resourceKey>",
+    "default": "Orders",
+    "propertyAttribute": "name"
+  },
+  {
+    "id": "bOrdersEntityFolder",
+    "name": "OrdersFolder",
+    "type": "string",
+    "resource": "Entity",
+    "resourceKey": "<resourceKey>",
+    "default": "<folder GUID>",
+    "propertyAttribute": "folderKey"
+  }
+]
+```
+
+**Where `_resourceKey` comes from.** It is the key the entity's reference is registered under in the solution, written by the canvas entity picker when it registers the entity (`_entityKey`, the Data Fabric entity id from `uip df entities list`, is the older fallback and is only used when `_resourceKey` is absent). A registered entity reference surfaces under `uip solution resources list --kind Entity --output json`, but there is no CLI that mints one for a flow you are hand-authoring. **If you cannot resolve a `_resourceKey`, do not hand-author the folder-scoped form** — keep the entity tenant-scoped, or add the node and let the picker write `_folderKey`, `_resourceKey` and both binding rows on first open. A half-authored folder scope is worse than none: it serializes, and it breaks on deploy.
+
+Two values are easy to get wrong, and both are things you type by hand:
+
+- **`resource` is the capitalized `"Entity"`.** The BPMN engine matches case-insensitively, but packaging requires the capital form; a lowercase row never becomes a binding resource, so the deploy side gets no override at all.
+- **`propertyAttribute` is `name` and `folderKey`** — never `folderPath`, and it is what the serializer matches on rather than the row's `name`.
+
+Entity bindings differ from the Orchestrator-resource form in several other ways — what `name` holds, the matching key, the absent `resourceSubType`. Those are tabulated once in [file-format.md — Bindings — Data Fabric entity bindings](../../../shared/file-format.md#bindings--data-fabric-entity-bindings); read it before hand-authoring a pair.
+
+When `_folderKey` is set but a binding is missing, serialization still succeeds — it falls back to a source-org literal and logs a warning. That partial state (name token + literal folder GUID) looks portable and breaks on cross-org deploy, so treat the warning as a defect rather than noise.
+
+The entity picker writes these bindings automatically. When hand-authoring a folder-scoped entity, add them yourself or leave the entity tenant-scoped.
+
+## Output wiring
+
+Reference the output through `=js:$vars.<nodeId>.output` per the canonical rule ([node-output-wiring.md](../../../shared/node-output-wiring.md)):
+
+```json
+{
+  "id": "end",
+  "type": "core.control.end",
+  "typeVersion": "<from registry get>",
+  "outputs": {
+    "status":   { "source": "=js:$vars.readOrder.output.Status" },
+    "orderId":  { "source": "=js:$vars.createOrder.output.Id" },
+    "openRows": { "source": "=js:$vars.listOpenOrders.output.results" }
+  }
+}
+```
+
+Run `uip maestro flow format <ProjectName>.flow` after adding nodes. Format regenerates `variables.nodes[]`, which is what makes `$vars.<nodeId>.output` resolve at runtime; skipping it produces a flow that validates but resolves the reference to `undefined` ([Author capability, rule 14](../../CAPABILITY.md#critical-rules)).
+
+Two wiring constraints unique to these nodes:
+
+- **Delete produces nothing.** There is no `$vars.<deleteNodeId>.output`.
+- **An Update node's output cannot feed a collection.** Each downstream reference is rewritten into its own re-read of the written record; [Loop](../loop/impl.md) and data-transform collections are excluded from that rewriting and have no snapshot to fall back on. Wire the Read node's output into the collection instead.
+
+## Validate
+
+```bash
+uip maestro flow validate <ProjectName>.flow --output json
+```
+
+The validator enforces the "green but inert" cases it can see structurally:
+
+| Message | Means |
+| --- | --- |
+| `An entity must be selected` | `entityName` missing or empty |
+| `Set a value for at least one field` | Create's `fieldValues` has no row with a non-blank value |
+| `Select a field to update` | Update's `fieldUpdates` has no row naming a field |
+| `A record ID is required` | `recordSource: "byId"` with a blank or whitespace-only `recordId` |
+| `Select a Read entity records node` | `recordSource: "fromRead"` with no `readEntityNodeId` |
+| `Choose how to identify the record` | Delete with `recordSource` missing or not one of `byId` / `fromRead` |
+
+A separate rule refuses a query whose filter value the engine cannot carry, or whose related path cannot resolve.
+
+What it does **not** check — every one of these validates clean and fails silently at runtime:
+
+- whether a column name exists, or is writable, or has the type the value implies;
+- whether the entity is native (writes) or federated (write is rejected and swallowed);
+- whether an **Update** names a `recordSource` — only Delete's is in the required list, so an Update without one validates clean and the serializer infers the mode from whichever selector is populated;
+- whether `readEntityNodeId` names a real node, or names a multi-record read;
+- whether a `byId` record id matches any record.
+
+Use `uip df entities get` and `uip df records list` to close that gap before shipping.
+
+## Debug
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `Node not found: core.datafabric.*` on `registry get` | Tenant flag off, or CLI predates the node | `uip tools update`, then `uip maestro flow registry pull --force`; then confirm that node's flag with the admin (see the table above) |
+| Node validates clean, runs green, nothing written | Most often a **selector** problem, not a binding one: `readEntityNodeId` names a missing node or a multi-record read, the read's filters do not compile, or the `fromRead` read matched more than one record at runtime | Check the Read node's `id` matches exactly and its `resultMode` is `single`; confirm the filter identifies exactly one record with `uip df records list` |
+| Write runs green, row unchanged | The body was rejected and the rejection swallowed — a federated entity, a system or attachment column, a choice-set label instead of its numeric id, an uncoercible value, or a null into a non-nullable column | Re-check the entity is native and each column against `uip df entities get` |
+| Downstream `$vars.<id>.output` is `undefined` | `variables.nodes[]` missing, or the read matched nothing | Run `uip maestro flow format`; if it persists, verify the filter matches a real record |
+| A Loop over a multi-record read iterates nothing | Wired `output` instead of `output.results` | Use `=js:$vars.<readId>.output.results` |
+| Multi-record read returns only some rows | The limit is always explicit and capped at 1000 | Page with `_skip`; raising `_recordLimit` past 1000 truncates silently |
+| `404 Entity <name> does not exist` | Folder-scoped entity queried without folder qualification, or a related-field join | Set `_folderKey` and its bindings. Joins across a folder-scoped entity are not supported — the join request carries a bare name with no folder qualifier |
+| Read returns every record | Filters compiled away — a blank expression row, or an `in` row in `single` mode | Check each row against [Filters](#filters) |
+| Console warning `… has no name/folderKey binding — serializing a non-portable literal` | Folder-scoped entity missing a `bindings[]` row | Add both rows — see [Folder-scoped entities and bindings](#folder-scoped-entities-and-bindings) |
+
+## What not to do
+
+- **Do not hand-write `definitions[]`** — copy verbatim from `registry get`. A flag-gated node you cannot `registry get` is a node you cannot author.
+- **Do not put a `model` block on the instance.** `bpmn:Task` and the debug runtime live in the definition.
+- **Do not add an instance `outputs` block.** The canvas writes none for these nodes; the manifest `outputDefinition` plus `flow format`'s `variables.nodes[]` carry the contract.
+- **Do not wire an `error` edge or set `errorHandlingEnabled`** — these four nodes have no error port. See [No error port](#no-error-port).
+- **Do not write to a federated entity.** Create, Update and Delete require a native entity; the rejection is swallowed, so the run looks successful.
+- **Do not write a system column** (`Id`, `CreateTime`, `CreatedBy`, `UpdateTime`, `UpdatedBy`) or an attachment column.
+- **Do not put a choice-set label in a value or a filter** — use the numeric `numberId`.
+- **Do not treat `AvailableOnTenant: false` as usable** because search returned the node.
+- **Do not use a Data Fabric node in an API workflow** — all four exclude the `api-function` runtime.
+- **Do not reference `$self` in a filter value,** and do not leave a filter expression blank — either refuses the whole query and strands every downstream reference.
+- **Do not add a placeholder value to satisfy Create's "at least one value" rule.** The rule exists because a blank-only insert writes nothing; a junk value writes junk.
+- **Do not strip `_entityFields` / `_outputSchema` / `_choiceSets` from an existing node** — related paths stop resolving and typed values stop coercing, both silently.
+- **Do not point `folderPath` at the folder token** for a folder-scoped entity — use `folderKey`.

package/skills/uipath-maestro-flow/references/author/plugins/data-fabric/planning.md

@@ -0,0 +1,185 @@
+# Data Fabric Entity Nodes — Planning
+
+The Data Fabric entity nodes read and write **records inside a UiPath Data Fabric entity** natively — no Integration Service connection, no HTTP call. They live in the **Data Fabric** section of the add-node panel. Four nodes cover the CRUD surface, and they share one entity picker, one filter grammar, and one `inputs.entityConfig` container.
+
+Use them whenever the flow's own data lives in Data Fabric: a case record, a lookup table, a status the flow advances, an audit row the flow appends.
+
+## Node Types
+
+| Node Type | Canvas label | Does |
+| --- | --- | --- |
+| `core.datafabric.read` | Read entity records | Read one record, or a filtered list of records |
+| `core.datafabric.create` | Create entity record | Insert one record and return the stored row |
+| `core.datafabric.update` | Update entity record | Patch named columns on one record |
+| `core.datafabric.delete` | Delete entity record | Delete one record (no output) |
+
+These are fixed OOTB node types — no registry suffix, no connector key. Each is gated by its own tenant feature flag, so a tenant can have Read without Create:
+
+| Node Type | Tenant flag |
+| --- | --- |
+| `core.datafabric.read` | `canvas.nodes.read-entity` |
+| `core.datafabric.create` | `canvas.nodes.create-entity` |
+| `core.datafabric.update` | `canvas.nodes.update-entity` |
+| `core.datafabric.delete` | `canvas.nodes.delete-entity` |
+
+A node whose flag is off is filtered out of the manifest entirely: `registry search` may still list it with `AvailableOnTenant: false`, but `registry get` answers **"Node not found"** and you cannot source its `definitions[]` entry. Confirm availability before planning around one — see [impl.md — Registry validation](impl.md#registry-validation).
+
+## Writes require a native entity
+
+Create, Update and Delete work only against **native** Data Fabric entities. A federated entity (one projecting an external system) can be read but never written through these nodes.
+
+Nothing enforces this outside the canvas: the three write panels filter their picker to native entities, but there is **no validation rule**. A hand-authored write against a federated entity passes `flow validate`, serializes, is rejected by Data Fabric, and the rejection is swallowed — a green run that changed nothing. Reads against the same entity keep working, which makes it read like a write bug rather than an entity-class one.
+
+Resolve the class up front with `uip df entities list --native-only --output json` and plan writes only against entities in that list.
+
+## When to Use
+
+Use these nodes when the record lives in **Data Fabric** and the flow itself is the thing reading or writing it.
+
+### Selection Heuristics
+
+| Situation | Use a Data Fabric entity node? |
+| --- | --- |
+| Look up a record by key to drive a decision or fill a downstream input | Yes — Read, `resultMode: "single"` |
+| Fetch a filtered set of rows to iterate over | Yes — Read, `resultMode: "multiple"`, then [Loop](../loop/planning.md) |
+| Advance a status, stamp a result, write back an outcome | Yes — Update (native entity) |
+| Append a new row (case, audit entry, request) | Yes — Create (native entity) |
+| Remove a row the flow has finished with | Yes — Delete (native entity) |
+| Write to a federated entity | No — these nodes cannot; use [connector](../connector/planning.md) or [http](../http/planning.md) |
+| React to a record being created/updated **elsewhere** | No — that is a trigger; use [connector-trigger](../connector-trigger/planning.md) (`uipath.connector.trigger.uipath-uipath-dataservice.record-created` / `record-updated`) |
+| Aggregate, group, or reshape rows already in memory | No — use [Transform](../transform/planning.md) |
+| Bulk-load a CSV into an entity | No — that is a data-loading job, not a flow step; use `uip df records import` out of band |
+| Read a record from a non-UiPath system | No — use [connector](../connector/planning.md) or [http](../http/planning.md) |
+
+### Native node vs Data Service connector — availability decides
+
+The `uipath-uipath-dataservice` Integration Service connector also exposes entity operations (`query-entity-records`, `create-entity-record`, `update-entity-record`, `get-entity-record-by-id`, `delete-entity-record`, …), and `registry search` surfaces both families.
+
+**Check availability before you choose — do not default to the native node.** All four tenant flags default to off, so the connector is the working path until `registry get core.datafabric.<op>` proves otherwise. On "Node not found" or `AvailableOnTenant: false`, build with the [connector](../connector/planning.md) and stop pursuing the native path — as you should when the entity is federated, since the native writes require a native entity.
+
+Where the tenant *does* have them, the native node is the better build, because it:
+
+- needs **no Integration Service connection** — nothing to create, bind, or keep healthy, and no `bindings[]` connection row;
+- is **user-owned** — author it with `Edit`/`Write` instead of the CLI's `node add` + `node configure` envelope (see [Author capability — Node ownership](../../CAPABILITY.md#node-ownership--who-authors-the-node));
+- gives downstream expressions the **record shape** (`$vars.readOrder.output.Status`) with autocomplete, because the picked entity's schema is merged into the node's output definition;
+- carries **portable entity bindings**, so a folder-scoped entity survives export to another org.
+
+Whichever way the check sends you, record it in **Open Questions** rather than leaving the reader to guess why the flow took that path.
+
+### Anti-Patterns
+
+- **Do not use Delete to "clear" a field.** Delete removes the whole record. To blank a column, use Update with an empty `value` — but see the nullability caveat in [impl.md — Write bodies](impl.md#write-bodies).
+- **Do not chain Read → Update by re-typing the record id.** Use `recordSource: "fromRead"` and point at the Read node; it reuses that node's query, so the two can never drift apart.
+- **Do not read a whole entity to find one row.** Push the constraint into `_filters` — a `resultMode: "multiple"` read with no filter returns the first 100 rows in arbitrary order, not "everything".
+- **Do not use these nodes inside an API workflow runtime.** All four declare `runtimeConstraints.exclude: ["api-function"]`; the read/write is dispatched by the BPMN engine, which no other runtime implements.
+- **Do not feed an Update node's output into a [Loop](../loop/planning.md) collection or a [Transform](../transform/planning.md).** That output is re-read per consumer, and collection consumers are excluded from the rewriting — see [Output Variables](#output-variables).
+
+## Ports
+
+| Node Type | Input | Output |
+| --- | --- | --- |
+| `core.datafabric.read` | `input` | `output` |
+| `core.datafabric.create` | `input` | `output` |
+| `core.datafabric.update` | `input` | `output` |
+| `core.datafabric.delete` | `input` | `output` |
+
+**These four nodes have no `error` port.** Unlike most action nodes, none of them declares `supportsErrorHandling`, so no error handle is ever injected and the properties panel offers no error-handling toggle. Do not set `inputs.errorHandlingEnabled` and do not add an edge with `sourcePort: "error"` — the serializer will still emit a boundary event for it, but with no error mapping, and the canvas shows no handle the author can see or remove. Plan failure handling upstream or downstream instead.
+
+Delete's `output` port exists for **sequencing only** — it carries no data (see below).
+
+## Output Variables
+
+| Node Type | `$vars.{nodeId}.output` |
+| --- | --- |
+| `core.datafabric.read` (`single`) | The record itself — address columns directly: `$vars.readOrder.output.Status` |
+| `core.datafabric.read` (`multiple`) | `{ results: [...] }` — the rows are under `output.results`, never `output` itself |
+| `core.datafabric.create` | The **stored** record, including the generated `Id` and server-applied defaults |
+| `core.datafabric.update` | The record **after** the write |
+| `core.datafabric.delete` | Nothing — the node declares no output definition |
+
+Three consequences worth planning around:
+
+- **A multi-record read is not an array.** `=js:$vars.listOpenOrders.output` is an object; the collection is `=js:$vars.listOpenOrders.output.results`. Wiring the former into a Loop iterates nothing.
+- **Update's output is a re-read, not the write's response.** The engine discards the write response; the serializer rewrites each downstream `$vars.<updateId>.output` reference into its own query for the record just written. That is why it cannot be consumed as a Loop or Transform collection — those are excluded from the rewriting and have no snapshot to fall back on.
+- **A read that matches nothing does not fault.** Only an *over*-match faults a single-record read. Zero matches completes normally and leaves `$vars.<readId>.output` unresolved, so a downstream Decision silently takes its falsy branch. If "not found" is a real business case, branch on it explicitly.
+
+Delete has no output at all, so plan any post-delete signalling (a count, a status) as a separate [Script](../script/planning.md) or End-node mapping.
+
+## Key Inputs
+
+Every node takes exactly one input object, `inputs.entityConfig`. Its contents differ per node.
+
+### Shared by all four
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `entityName` | Yes | The entity's technical name. Resolve it with `uip df entities list` — never invent it |
+| `_folderKey` | Folder-scoped entities only | The entity's `folderId`. Its presence switches the emitted target to the folder-qualified form and makes `bindings[]` entries necessary for portability — see [impl.md — Folder-scoped entities](impl.md#folder-scoped-entities-and-bindings) |
+| `_resourceKey` / `_entityKey` | With `_folderKey` | Key the entity's `bindings[]` rows are scoped to |
+
+The canvas also persists schema snapshots (`_entityFields`, `_relatedFields`, `_outputSchema`, `_choiceSets`). They are not decoration — see [impl.md — Schema snapshots](impl.md#schema-snapshots) for when authoring without them silently breaks.
+
+### `core.datafabric.read`
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `resultMode` | No | `"single"` (default) or `"multiple"` |
+| `_filters` | No | The query. Grouped filter model — see [impl.md — Filters](impl.md#filters) |
+| `_selectedFieldNames` | No | Columns to return. Omit for all |
+| `_recordLimit` | `multiple` only | Row cap, clamped 1–1000. Omitted resolves to **100** — the emitted query always carries an explicit limit |
+| `_skip` | `multiple` only | Rows to pass over first. The only way past the 1000-row ceiling |
+| `_sort` | `multiple` only | `{ field, direction: "asc" \| "desc" }`. A limit without an order returns an arbitrary slice |
+
+### `core.datafabric.create`
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `fieldValues` | Yes | `[{ field, value }]`. **At least one row must carry a non-blank `value`** — blank values are omitted so the column default applies, so an all-blank config inserts nothing and still runs green |
+
+### `core.datafabric.update`
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `recordSource` | Yes (not enforced) | `"byId"` or `"fromRead"`. **The validator does not require it on Update** (unlike Delete) — the serializer infers the mode from whichever selector is populated, so leaving it out is silent |
+| `recordId` | `byId` | The record's `Id` — a literal or a `=js:` reference |
+| `readEntityNodeId` | `fromRead` | The upstream Read node whose query identifies the record |
+| `fieldUpdates` | Yes | `[{ field, value }]`. An **empty `value` writes an explicit null**, which a non-nullable column rejects |
+
+### `core.datafabric.delete`
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `recordSource` | Yes | `"byId"` or `"fromRead"`. The validator requires it — but do not read its absence as "inert" ([impl.md — Record selection](impl.md#record-selection)) |
+| `recordId` | `byId` | The record's `Id` |
+| `readEntityNodeId` | `fromRead` | The upstream Read node identifying the record |
+
+## Record selection — `byId` vs `fromRead`
+
+Update and Delete both need to name exactly one record, and offer the same two ways:
+
+| Mode | Use when | Cost of getting it wrong |
+| --- | --- | --- |
+| `byId` | The id is already in hand — a trigger payload, a Create node's `output.Id`, a flow input | A blank or whitespace-only id resolves to nothing; the node runs green having written nothing |
+| `fromRead` | An upstream Read already located the record by business key | The write is **skipped silently** if the read matches more than one record, names a node that does not exist, or is itself multi-record |
+
+Prefer `fromRead` when a Read node is already there — it reuses that node's compiled query, so a later change to the filter automatically follows through to the write. But note the asymmetry: on the **read** path an over-match faults the element, while on the **write** path the engine swallows that same over-match and skips the write. A `fromRead` target must therefore be a genuinely single-record read; there is no runtime safety net telling you it was not.
+
+## Common Pattern — read, branch, write back
+
+```text
+Trigger -> Read entity records (single, filter by business key)
+        -> Decision (on a column)
+             -> true:  Update entity record (fromRead) -> End
+             -> false: Create entity record            -> End
+```
+
+The Decision is doing real work here: a read that matches nothing completes with an unresolved output, so the false branch is also the not-found branch.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- `datafabric: <verb> <EntityName> — <one-line purpose>`, naming the entity and, for a read, whether it is single or multiple.
+- Name the **selector** for every Update and Delete (`byId` from `<source>`, or `fromRead` from `<readNodeId>`). An unnamed selector is the single most common way these nodes ship silently doing nothing.
+- Record the entity's **class and scope** — native vs federated, tenant vs folder — because writes need native, and a folder-scoped entity needs `_folderKey` plus bindings.
+- Put the entity in **Open Questions** when the requirements name a business concept ("the order", "the case") but no entity is confirmed by `uip df entities list`. Do not guess an entity or column name — they are case-sensitive and unmatched names are dropped rather than rejected.

package/skills/uipath-maestro-flow/references/author/{references/plugins → plugins}/decision/impl.md

@@ -53,10 +53,15 @@ $vars.lookupUser.output.user !== null
 
 Output ports: `true` and `false`. Both branches must be wired. See [editing-operations.md](../../editing-operations.md) for edge add procedures.
 
+## Outputs
+
+A Decision has **no `.output`**. Downstream nodes read which branch ran as `$vars.<decisionId>.matchedCaseId` (`"true"` or `"false"`) or `$vars.<decisionId>.matchedCase` (the branch label) — e.g. `$vars.checkStatus.matchedCaseId === "true"`. `$vars.<decisionId>.output.matchedCaseId` is undefined and faults the reader at runtime (`[300501]`).
+
 ## Debug
 
 | Error | Cause | Fix |
 | --- | --- | --- |
 | Expression does not evaluate to boolean | Expression returns non-boolean value | Ensure expression uses comparison operators (`===`, `>`, etc.) |
 | `$vars.nodeId` is undefined | Upstream node not connected or wrong ID | Check edges and node IDs |
+| `[400302] Error evaluating outgoing flow expression from gateway` | `expression` reads a node that runs *after* the Decision (typical after moving the Decision earlier in the flow) | Point `expression` at a node that still runs before the Decision (e.g. the HTTP node's `$vars.<node>.output…`), not at the node the branches lead to |
 | Only one branch wired | Missing true or false edge | Add the missing edge — both branches are required |