@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/author/plugins/connector/impl-inline.md

@@ -0,0 +1,120 @@
+# Connector Activity Nodes — Non-catalog (inline) activities
+
+Use this walkthrough for a node whose type is `uipath.connector.custom.<connector-key>.<slug>`: an activity Integration Service does **not** carry, generated from the vendor's API docs by [/uipath:uipath-platform — activity-generation.md](../../../../../uipath-platform/references/integration-service/activity-generation.md). The node carries the whole activity — its metadata and its scripts — and the CLI builds the `definitions[]` entry from that metadata instead of fetching it from the registry.
+
+Everything **not** listed here is identical to [impl.md](impl.md): follow its Configuration workflow and substitute only the steps below. The ownership rules do not change — `definitions[]` and `inputs.detail` are still CLI-written; you never hand-author either.
+
+## When this applies
+
+- Tier 2 of the [decision order](planning.md#decision-order): the connector exists, lacks the curated activity, and reports `V4Compatible: true`.
+- The activity is **already generated** — you have `<Name>.json` (the compiled activity metadata) and one `<scriptRef>.js` per action and lookup. If you do not, invoke the `uipath-platform` skill's activity generation ([activity-generation.md](../../../../../uipath-platform/references/integration-service/activity-generation.md)) to produce them, then resume here with the artifacts. This is a sanctioned exception to [SKILL.md rule #4](../../../../SKILL.md#critical-rules-universal): no user prompt is needed once the connector gap is confirmed and `V4Compatible` is `true`. Follow the sibling's guide end to end (vendor-docs grounding, `metadata generate`, `script update`, script validation) — do not reproduce its commands from memory. Only if that skill is unavailable in the session do you fall back to Managed HTTP connector mode ([http/impl-connector.md](../http/impl-connector.md)) and report the downgrade.
+
+## Inputs
+
+| Artifact | Produced by | Used for |
+|---|---|---|
+| `$WORK/<Name>.json` | `uip is activities metadata generate` | `--metadata`; becomes the definition and `inputs.inlineActivityConfiguration.metadata` |
+| `$WORK/<Name>.js`, `$WORK/<Lookup>.js` | `uip is activities script update` | `--scripts $WORK`; one `<scriptRef>.js` for the main action and for **every** `reference.scriptRef` in the metadata |
+
+Keep `$WORK` until the node is added. The flow carries copies of the scripts; the files are what you re-add from if the metadata changes.
+
+## Node type
+
+`uipath.connector.custom.<connector-key>.<slug>`
+
+- `<connector-key>` must equal the metadata's `elementKey` (`uipath-salesforce-slack`); `node add` refuses a mismatch.
+- `<slug>` is the activity's display name in kebab case: `Add Users to Usergroup` → `add-users-to-usergroup`.
+- A flow holds **one definition per type**. Two nodes with the same type share it, so the same slug must mean the same metadata; a different activity needs a different slug. `node add` refuses a second node whose metadata differs from the embedded definition.
+
+The `custom` segment is what marks a non-catalog activity. Do not confuse it with a `custom-*` **connector key** (a Connector Builder connector, see [connectors.md — Connector Disambiguation](../../../../../uipath-platform/references/integration-service/connectors.md#connector-disambiguation)); the key here is the catalog connector's.
+
+## Step 1 — Fetch and bind a connection
+
+Unchanged: [impl.md — Step 1](impl.md#step-1--fetch-and-bind-a-connection).
+
+## Step 2 — Read the metadata (replaces `registry get` and `describe`)
+
+There is nothing to fetch. `$WORK/<Name>.json` **is** the metadata, and it has one verb slot:
+
+| You need | Read |
+|---|---|
+| `method`, `endpoint` | `metadata.method.<VERB>.method`, `metadata.method.<VERB>.path` (the vendor path, e.g. `/usergroups.users.update`) |
+| operation, main script | `metadata.method.<VERB>.operation`, `metadata.method.<VERB>.scriptRef` |
+| `queryParameters`, `pathParameters` | `metadata.method.<VERB>.parameters[]` by `type` (`query` / `path`); `required` on each |
+| `bodyParameters` | `fields.<name>` whose `method.<VERB>.request` is `true`; `required` on that entry |
+| reference fields | `reference.scriptRef` on a parameter or a field (the lookup script's base name) |
+
+The activity's `objectName` is the metadata's top-level `name` (`AddUsersToUsergroup`). You never pass it — the CLI reads it from the definition it built. As with any connector node: **write only parameter names the metadata lists, in the bucket it lists them under.**
+
+## Step 3 — Add the node
+
+```bash
+uip maestro flow node add <file>.flow \
+  uipath.connector.custom.<connector-key>.<slug> \
+  --label "<Label>" \
+  --metadata $WORK/<Name>.json --scripts $WORK --output json
+```
+
+Expect `Code: NodeAddSuccess`, `Data.DefinitionAdded: true` (`false` when a node of this type already exists and the metadata matches), and `Data.InlineActivity: { ScriptRef, Scripts[] }` listing every embedded script.
+
+What it writes, and what you leave alone:
+
+- `definitions[]` — the node manifest, built from the metadata at `version: "4.0.0"`. Its `connectorDetail.uiPathActivityTypeId` is a **placeholder random UUID**: Studio's TypeCache assigns the real one for catalog activities, and nothing assigns one for a non-catalog activity yet.
+- `inputs.inlineActivityConfiguration` — `{ metadata, scriptRef, scripts }`: the metadata verbatim, the main action's `scriptRef`, and every script's source by ref.
+
+Failures are all `Result: Failure`, exit `1`, and name the fix: a script missing from `--scripts` (the message lists every missing `<scriptRef>.js`), `--metadata` without `--scripts` or the reverse, a `custom` type added without them, a type whose connector key is not the metadata's `elementKey`, or a same-type node with different metadata.
+
+## Step 4 — Resolve reference fields with the local lookup script
+
+The lookup scripts are not published, so `--script-ref` cannot find them. Run the local file instead — a plain path ending in `.js`, no `@` prefix:
+
+```bash
+uip is resources run script --connection-id "<id>" \
+  --inline-script $WORK/<lookupRef>.js --body '{}' --output json
+```
+
+Read the rows in `Data.Body` (an array), match `lookupNames`, take `lookupValue`. Every other rule of [impl.md — Step 4](impl.md#step-4--resolve-reference-fields) applies unchanged: connection-scoped IDs, resolve freshly before configure, zero-match and failed-call handling.
+
+## Step 5 / 5b — Required fields and upstream wiring
+
+Unchanged: [impl.md — Step 5](impl.md#step-5--validate-required-fields), [Step 5b](impl.md#step-5b--wire-upstream-outputs). Required fields come from the metadata entries in Step 2.
+
+## Step 6 — Configure the node
+
+Same `--detail` keys as any connector node. `method` and `endpoint` come from the verb slot. Do **not** pass `objectName`, `activityContext`, `scripts` or anything from the metadata — the CLI derives those.
+
+```bash
+uip maestro flow node configure <file>.flow <nodeId> --detail "$(cat /tmp/detail.json)" --output json
+```
+
+with, for example:
+
+```json
+{ "connectionId": "<id>", "folderKey": "<key>",
+  "method": "POST", "endpoint": "/usergroups.users.update",
+  "bodyParameters": { "usergroup": "<resolved id>", "users": "=js:$vars.pickUsers.output.ids" } }
+```
+
+What `node configure` does differently for an inline node:
+
+- reads the metadata from `inputs.inlineActivityConfiguration` — no Integration Service request;
+- writes `inputs.detail.activityContext` as `{ "version": "4.0.0", "source": "inline", "scriptRef": "<main scriptRef>" }` — `source: "inline"` is how the runtime knows to run the embedded activity, and `scriptRef` is the main action, not the `objectName`;
+- builds `configuration` (`essentialConfiguration`) with `objectName` = the metadata's `name`, `path` = the vendor path, `operation` = the verb slot's operation lowercased, and `instanceParameters.activitySource: "inline"` — the design-time marker that the activity package reads metadata and scripts from the node, not the catalog;
+- copies `uiPathActivityTypeId` from the definition, so re-running configure never changes it;
+- keeps `inputs.inlineActivityConfiguration` across re-runs. Re-configure with the complete intended `--detail`, exactly as for any connector node.
+
+## Validate
+
+`uip maestro flow validate` runs the usual connector checks plus, for this node, offline:
+
+- a `uipath.connector.custom.*` node must carry `inputs.inlineActivityConfiguration`, and a node carrying it must have that type;
+- the main `scriptRef` and every lookup `reference.scriptRef` in the metadata must have a source under `scripts`;
+- once configured, `activityContext.source` must be `"inline"` and `activityContext.scriptRef` must equal the embedded `scriptRef`.
+
+Fix a script gap by `uip maestro flow node remove` and re-adding with a complete `--scripts` directory; fix an `activityContext` mismatch by re-running `node configure`. A missing `uiPathActivityTypeId` is a defect in the definition — re-add the node, never paste one.
+
+## Limits
+
+- The `uiPathActivityTypeId` is a placeholder until TypeCache, or a published formula, supplies real ids for non-catalog activities.
+- Running the flow needs a runtime that understands `activityContext.source: "inline"`. `flow validate` cannot tell you whether the tenant has it.
+- `node add` echoes the node, embedded scripts included. Use `--output-filter "Data.InlineActivity"` when the scripts are large.

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

@@ -0,0 +1,463 @@
+# Connector Activity Nodes — Implementation
+
+Configure connector activity nodes after the generic node-add operation in [editing-operations.md](../../editing-operations.md). Configuration covers connection binding, metadata, object and operation discovery, references, custom fields, filters, input wiring, and debugging.
+
+`uip maestro flow node configure` authors top-level `bindings[]` and `inputs.detail`. `bindings_v2.json` is regenerated from `bindings[]` at debug/pack time; never hand-edit it.
+
+| Node type | Walkthrough |
+| --- | --- |
+| `uipath.connector.<connector-key>.<activity>` — a catalog activity the registry carries | this file |
+| `uipath.connector.custom.<connector-key>.<slug>` — a non-catalog activity generated from vendor docs (Tier 2 of [planning.md](planning.md#decision-order)) | [impl-inline.md](impl-inline.md); it lists only what differs from this file |
+
+## Requirements and data model
+
+Every connector node requires an Integration Service connection in top-level `bindings[]`. Run `registry get` with `--connection-id`; otherwise custom fields, dynamic enums, and reference metadata are absent. `registry get` accepts only `--connection-id` and `--local` — no `--activity-version` (it reads the node's own `configuration.version` and self-routes `4.0.0` activities; anything else fails `error: unknown option`). For `4.0.0` nodes `--connection-id` adds nothing (metadata not connection-scoped — see [§ 4.0.0 Activities](#400-activities)).
+
+Connector configuration is stored in `inputs.detail`:
+
+- `connectionId`: bound IS connection UUID.
+- `connectionFolderKey`: Orchestrator folder key in the authored `.flow`; `--detail folderKey` serializes as `connectionFolderKey`.
+- `method`: IS method label from metadata.
+- `endpoint`: API path from `connectorMethodInfo.path` or `availableOperations[].path`.
+- `objectName`: required for generic activities.
+- `bodyParameters`: values keyed by `inputDefinition.fields[].name` or `requestFields[].name`.
+- `queryParameters`: parameters whose `type` is `query`.
+- `pathParameters`: parameters whose `type` is `path`.
+- `filter`: structured FilterBuilder tree.
+- `customFieldsRequestDetails`: design-time cache for supported api-type ObjectActions; keys are camelCase and `parameterValues` is an array of `[key, value]` tuples.
+- `multipartParameters`: derived from IS parameters where `type === "multipart"`; entries are `{name, dataType, value?}`.
+- `inputMetadata`: derived multipart or list metadata.
+
+For multipart parameters, pass file values through `--detail.bodyParameters.<name>`; `node configure` moves file-typed values into matching `multipartParameters[i].value`. Keep string entries, including the body aggregator named by `inputMetadata.multipart.bodyFieldName`, in `bodyParameters`. When multipart parameters exist, `inputMetadata` is `{type: "multipart", multipart: {bodyFieldName}}`; for list operations it is `{operation: "list", pagination: {maxPageSize}}`.
+
+Concrete activities encode object and operation in the node type; their `inputDefinition.fields[]`, method, and endpoint are normally populated. Generic activities encode only the operation; `inputDefinition` is `{}` and require `objectName`, method, and endpoint from resource metadata.
+
+Classify the activity from `Node.form.sections[0].fields[0].componentProps.connectorDetail.configuration` returned by `registry get`, parsing it as JSON and checking `activityType`. For `"Generic"`, run Step 2a and capture its `operation` for Step 3's `--operation`; otherwise skip Step 2a.
+
+Definitions in `definitions[]` are CLI-owned. `uip maestro flow node add` copies them from the registry; never hand-write or hand-edit them. If configuration reports `No instanceParameters found in definition`, run `uip maestro flow registry pull --force`, delete the stale `definitions[]` entry, and run `uip maestro flow node add <file> <node-type>` again. Do not paste `form` by hand.
+
+## 4.0.0 Activities
+
+An activity is `4.0.0` when its `configuration` JSON reports `"version":"4.0.0"`. Author it through the Configuration workflow below like any other connector activity; `describe`/version mechanics are in [/uipath:uipath-platform — resources.md § `--activity-version`](../../../../../uipath-platform/references/integration-service/resources.md#--activity-version). Four deltas:
+
+1. **`objectName` source** — read the definition's `configuration` `objectName` (the `model.context[]` `objectName` entry is declared with no value). It is the `describe` positional, but do NOT pass it in `--detail` — `node configure` reads it from the definition itself. If configuration carries no `objectName`, the registry copy is stale: run `uip maestro flow registry pull --force`, delete the `definitions[]` entry, and re-add the node.
+2. **`method` / `endpoint`** — from `connectorMethodInfo` (`registry get`) or `availableOperations[]` (`is resources describe <connector-key> <object-name> --activity-version 4.0.0`).
+3. **Operation label ≠ HTTP verb** — a semantic operation (e.g. `Update`) pairs with any verb (e.g. `POST /usergroups.users.update`). `flow validate` accepts it; do not "fix" the method to match the label.
+4. **Not connection-scoped** — `--connection-id` on `registry get` adds no custom fields.
+5. **Reference fields are script-backed** — `reference` carries `scriptRef` (e.g. `list_usergroups`) and no `objectName`. Resolve with `uip is resources run script --connection-id <id> --connector-key <connector-key> --script-ref <scriptRef> --output json`, never `run list`. `registry get` strips `scriptRef` — read it from the Step 3 `describe` (`--activity-version 4.0.0 --operation <method>`). Response parsing and matching rules: [/uipath:uipath-platform — reference-resolution.md § 4.0.0 Activities — Script References](../../../../../uipath-platform/references/integration-service/reference-resolution.md#400-activities--script-references-scriptref).
+
+## No-Live-Tenant / Planned Configuration
+
+If `node configure` cannot run:
+
+1. Run `uip maestro flow registry search <keyword>` and `registry get <node-type>` to confirm the operation; see [cli-commands.md — registry](../../../shared/cli-commands.md#uip-maestro-flow-registry).
+2. Run `uip maestro flow node add <file> <node-type> --output json`; inside a loop body, add `--parent <LOOP_NODE_ID>` as described in [loop/impl.md](../loop/impl.md).
+3. Write the planned `--detail` payload, including placeholder connection and folder UUIDs, to a separate file such as `<nodeId>.detail.json`. Do not put partial `inputs.detail` on the node.
+4. Author any filter as a tree under that payload's `filter` key, shaped per [Step 6a](#step-6a--filterbuilder-parameters) step 3. The step-1 `registry get` names the FilterBuilder parameter; if the activity has none, pass no `filter` and filter downstream. Never write compiled query text under the parameter name, such as `"queryParameters": { "where": "displayName='active'" }`; offline, the tree is the filter's only reviewable form.
+5. Report under **Missing connections** or **Open questions** that the node will not pass `flow validate` until real `node configure` runs.
+
+Do not replace a registered connector node with `core.logic.mock`. Use mocks only for genuinely unknown, unpublished, or not-yet-built non-connector resources. Preserve the registered connector key.
+
+When parsing `--output json`, do not merge stderr into stdout. Use `2>/dev/null` for parse-only probes or capture stderr separately.
+
+## Configuration workflow
+
+### Step 1 — Fetch and bind a connection
+
+Extract `<connector-key>` from `uipath.connector.<connector-key>.<activity-name>`. Before any `uip is connections ...` call, read [/uipath:uipath-platform — connections.md](../../../../../uipath-platform/references/integration-service/connections.md), which is authoritative for auto-selection, personal workspace, BYOA filtering, empty-result recovery, and ping verification.
+
+Run:
+
+```bash
+uip is connections list "<connector-key>" --all-folders --output json
+```
+
+`Data` is a flat array. Read `Data[i].Id` and `Data[i].FolderKey`; do not parse `Data.Connections` or `Data.Items`. Use `Data[i].Id` for `--connection-id` and `Data[i].FolderKey` for `folderKey`. End with a healthy connection ID and folder key for Steps 2 and 6.
+
+### Step 2 — Fetch enriched metadata
+
+Run:
+
+```bash
+uip maestro flow registry get <node-type> --connection-id <connection-id> --output json
+```
+
+Read enriched `inputDefinition.fields` and `outputDefinition.fields`, including type, required, description, enum, and `reference`. For concrete activities, save `connectorMethodInfo.method` and `connectorMethodInfo.path`. For generic activities, `connectorMethodInfo` is empty; use Step 3.
+
+### Step 2a — Discover the object for generic activities
+
+Run this only for `activityType: "Generic"`:
+
+```bash
+uip is resources list "<connector-key>" --connection-id "<connection-id>" --output json \
+  --output-filter "[?contains(DisplayName,'<search>')].{Name:Name,Path:Path,Custom:Custom}"
+```
+
+Use case-sensitive `Name` as `objectName`, never `DisplayName`. `Path` is the endpoint suffix and `Custom` indicates tenant-defined objects.
+
+### Step 3 — Describe the resource and read the cache
+
+Read `<objectName>` from the node definition copied into `definitions[]`, never from the node-type suffix or by case conversion. Read `model.context[]` `{name:"objectName", value:"…"}` or `objectName` inside the `configuration` `=jsonString:` blob. Example: node type `…google-gmail.send-email` has objectName `SendEmail` (not `send_email`); `…teams.send-bot-direct-message` has objectName `bot_direct_messages` (not `send-bot-direct-message`). kebab→snake and kebab→Pascal are both guesses that 404.
+
+Sequence dependent calls; do not parallelize `node add`, `registry get`, and `describe`. If describe returns 404, reread `objectName` and retry; do not skip describe.
+
+Run:
+
+```bash
+uip is resources describe "<connector-key>" "<objectName>" \
+  --connection-id "<id>" --operation Create --output json
+```
+
+Then run `cat <metadataFile path from response>` and read the full cached metadata. Pass `--operation` as the node definition's `model.context[].method` verbatim. E.g. Jira `curated_get_issue` → `GETBYID`; Data Service `QueryEntityRecordsCurated` → `POST`. Do not use `connectorMethodInfo.operation` or `connectorMethodInfo.method` as the describe lookup key.
+
+> **`4.0.0` activities** — positional is the `objectName`, `--activity-version 4.0.0` is mandatory, `--operation` takes the verb from `model.context[].method` (never a guessed semantic label), and `--connection-id` is ignored: `uip is resources describe "<connector-key>" "<objectName>" --activity-version 4.0.0 --operation <method> --output json`. See [§ 4.0.0 Activities](#400-activities).
+
+Read `availableOperations[].method` and `availableOperations[].path` for method and endpoint; `parameters[]` for query/path parameters and `reference` objects; `requestFields[]` for body names, types, required status, descriptions, and `reference` objects; and `responseFields[]` for the response schema.
+
+> **Write only parameter names that `describe` listed, in the bucket it listed them under.** Never guess a key. Slack `send_message_to_channel_v2`: `send_as` is a required query parameter, not a body field; `username` is the bot display name, not a send-as switch.
+
+### Step 3a — Resolve parent-field-driven custom fields
+
+Run this whenever metadata contains an api-type ObjectAction in top-level `objectActions[]` or `connectorMethodInfo.design.actions[]`. This applies to every operation whose schema depends on parent fields, including Create/Edit/Update inputs and Get/Retrieve/Query response fields.
+
+Run the matching action with `-f, --field` before Step 5 and reuse the same values in Step 6c. Follow [/uipath:uipath-platform — resources.md > Parent-Field-Driven Custom Fields (api-type ObjectActions)](../../../../../uipath-platform/references/integration-service/resources.md#parent-field-driven-custom-fields-api-type-objectactions) for procedure, flags, merge semantics, and recovery.
+
+Do not skip this for Get/Retrieve: runtime may succeed while Studio Web lacks the design-time schema and downstream `$vars.<thisNode>.output.<custom-field>` resolves to undefined. `flow validate` does not catch this.
+
+### Step 4 — Resolve reference fields
+
+Check **BOTH `requestFields` AND `parameters`** from the metadata for entries with a `reference` object — these require ID lookup from the connector's live data. Use `uip is resources run list` to resolve them:
+
+> **`4.0.0` activities use `run script`, not `run list`.** Their `reference` blocks carry `scriptRef` instead of `objectName`. Run `uip is resources run script --connection-id "<id>" --connector-key "<connector-key>" --script-ref "<reference.scriptRef>" --output json`, read the rows in `Data.Body` (an array), and match `lookupNames` → take `lookupValue`. The zero-match, multiple-match, failed-call, and connection-scoping rules below apply unchanged. See [§ 4.0.0 Activities](#400-activities) and [reference-resolution.md — 4.0.0 Activities — Script References](../../../../../uipath-platform/references/integration-service/reference-resolution.md#400-activities--script-references-scriptref).
+
+> **References are NOT body-field-only.** Query and path parameters carry `reference` objects too, and on some connectors the activity's PRIMARY input is a required **path parameter** whose `reference` is the design-time lookup behind a Studio Web dropdown. Scanning only `requestFields` misses it — the node then configures and passes `flow validate` with an unverified value and 404s at runtime. The same `reference` blocks appear on `connectorMethodInfo.parameters[]` in `registry get` output (with or without `--connection-id`) — when projecting parameter metadata for inspection, always include the `reference` key, not just `name`/`required`/`design.component`.
+
+> **A field with a `reference` takes a value a live lookup returned, never a value you typed.** Resolve it per [reference-resolution.md — Reference Fields](../../../../../uipath-platform/references/integration-service/reference-resolution.md#reference-fields-critical). A plain word is right only when the lookup returns it (Slack `send_as` → `user` or `bot`). Jira `fields.reporter.id` wants the looked-up `accountId`, not `jane.doe@acmecorp.com`.
+
+> **Resolve every reference field freshly, against the current `--connection-id`, immediately before `node configure` (Step 6)** — even if you think you already know the ID from a previous flow. Reference IDs are connection-scoped and reused values fault silently at runtime. See [Reference IDs Are Connection-Scoped (CRITICAL)](../../../../../uipath-platform/references/integration-service/reference-resolution.md#reference-ids-are-connection-scoped-critical) for the full mechanism and failure mode, and the top-level Anti-Patterns in [SKILL.md](../../../../SKILL.md).
+
+```bash
+# Example: resolve Slack channel "#test-slack" to its ID
+uip is resources run list "uipath-salesforce-slack" "curated_channels?types=public_channel,private_channel" \
+  --connection-id "<id>" --output json
+# -> { "id": "C1234567890", "name": "test-slack" }
+```
+
+The `<id>` in `--connection-id "<id>"` MUST be the connection bound to **this** flow (the one picked in Step 1), not any other connection you've used in another flow. Use the resolved IDs (not display names) — from this very `run list` call — in the flow's node `inputs`. When multiple matches exist, ask the user, with one option per match plus **"Something else"** as the last option (see the dropdown question rule in [SKILL.md](../../../../SKILL.md)).
+
+> **Zero matches on a user-supplied value** — if the completed lookup (`Data.Pagination.HasMore` is `"false"`) finds no entry matching a value the user provided, do NOT configure the node with it silently. **Re-run the lookup against every other `State: Enabled` connection for this key first**, applying the two rules above per connection — `filterPattern` where the reference declares one, otherwise paginate, short-circuiting on the first match. The value is absent only once every Enabled connection has been searched to `HasMore: "false"`. If one resolves it, use that connection for this node and record the switch. If none do, ask the user, presenting the closest candidates as options plus **"Something else"** as the last option (see the dropdown question rule in [SKILL.md](../../../../SKILL.md)). Their answer is another search term, not a value to write: re-run the lookup with it. If nothing resolves the field, stop and report it — writing an unresolved display name or a placeholder passes `flow validate` and faults at runtime.
+
+> **The lookup call itself failed** — a 403/401 on an expired or revoked grant, or a 5xx, means you have no ID and no candidate list to offer. Do NOT configure the node with the display name, a vendor well-known alias, or an ID from memory; each passes `flow validate` and faults at runtime. Stop and report the failed resolve, naming the connection and the vendor error. See [reference-resolution.md — When the Lookup Call Fails](../../../../../uipath-platform/references/integration-service/reference-resolution.md#when-the-lookup-call-fails-critical).
+
+> **Filter server-side before paginating.** If the field's `reference` carries a `filterPattern` (e.g. Teams `userId`: `"$filter=startswith(userPrincipalName,'{filter}')"`), substitute the search term for `{filter}` and pass the result as `--query` — one targeted call instead of walking a large directory. `filterPattern` appears only in `is resources describe` output; the flow `registry get` reference object strips it (keeps only `objectName`/`lookupValue`/`lookupNames`/`path`/`childPath`), so read it from the Step 3 describe metadata. Guessed params (`searchTerm=`/`where=`/`filter=`) are silently ignored. See [reference-resolution.md — Search References (filterPattern)](../../../../../uipath-platform/references/integration-service/reference-resolution.md#search-references-filterpattern).
+
+> **Narrow before you page, and walk the narrowing ladder rather than reaching for the loop.** A by-key resource beside the collection (Slack `users_lookupByEmail`) beats a `filterPattern`, which beats the referenced resource's own `--query` keys, which beats paging. Read those keys from a `uip is resources describe "<key>" "<referenced-resource>" --operation List` — the collection the `reference` names, NOT the Step 3 describe of the activity you are configuring, whose `parameters` never carry the collection's filters. Chain the pages into one call rather than a turn per page. A filtered page returning `Data: []` means "not on this page", not "absent". Full ladder, the stalled-token case, and what each ending obliges you to do: [resources.md — Narrow before you page](../../../../../uipath-platform/references/integration-service/resources.md#narrow-before-you-page). See [resources.md — Narrow before you page](../../../../../uipath-platform/references/integration-service/resources.md#narrow-before-you-page) and [resources.md#pagination](../../../../../uipath-platform/references/integration-service/resources.md#pagination).
+
+**Read [/uipath:uipath-platform — Integration Service — resources.md](../../../../../uipath-platform/references/integration-service/resources.md) for the full reference-resolution workflow** (pagination, describe failures, fallbacks).
+
+### Step 5 — Validate required fields
+
+Check every `required: true` field in both `requestFields` and `parameters`. Use `defaultValue` for required query/path parameters when the user supplied no value:
+
+1. Collect required fields from both metadata sections.
+2. Match each against user-provided values.
+3. Ask before building for every missing field without a default, showing `displayName` and expected value type. Use free-form input for open-ended values and dropdown options for finite choices, following [SKILL.md](../../../../SKILL.md).
+4. Do not guess or skip a required field.
+
+Run Step 3a first for api-type ObjectActions because base describe may omit custom required fields.
+
+### Step 5b — Wire upstream outputs
+
+Use this form inside `bodyParameters`, `queryParameters`, and `pathParameters`:
+
+```text
+"=js:$vars.<sourceNodeId>.output.<field>"
+```
+
+The `=js:` prefix is mandatory for every `$vars`, `$metadata`, and `$self` reference. There is no `nodes.X.output.Y` syntax. See [node-output-wiring.md](../../../shared/node-output-wiring.md).
+
+### Step 6 — Configure the node
+
+Run `is resources describe` first. `node configure` rebuilds `inputs.detail` and the essential-configuration blob from supplied `--detail`; it does not merge prior values. On every reconfiguration, pass the complete intended shape: connection plumbing, all parameter buckets, filter, and `customFieldsRequestDetails`.
+
+Omitting `bodyParameters`, `queryParameters`, or `pathParameters` removes prior values. Omitting `filter` removes `savedFilterTrees` and filter derivation. Omitting `customFieldsRequestDetails` resets it to `null`.
+
+#### Step 6a — FilterBuilder parameters
+
+A filter is authored as a tree under the `filter` key of `--detail`. The CLI compiles the tree; you never write the query text. Five steps:
+
+1. **Find the filter parameter and the path slots** — read them from the registry, never guess:
+
+   ```bash
+   uip maestro flow registry get <node-type> --output json \
+     --output-filter "Node.{filterParams:connectorMethodInfo.parameters[?design.component=='FilterBuilder'].name,path:connectorMethodInfo.path,pathParams:connectorMethodInfo.parameters[?type=='path'].name}"
+   ```
+
+   Data Service `query-entity-records` returns `filterParams: ["queryExpression"]`, `path: "/v2/{entityName}/qer"`, `pathParams: ["entityName"]`. FilterBuilder parameters are not limited to list operations. If `filterParams` is empty, pass no `filter` and filter downstream.
+
+2. **Read exact field names** — `uip df entities list --output json`, then `uip df entities get <ENTITY_ID> --output json`. Names are case-sensitive; a leaf whose `id` matches no field is dropped without an error.
+
+3. **Write the `--detail` JSON to a file** with a quoted heredoc. The value of `filter` IS the tree — `groupOperator`, `filters[]`, `groups[]` at its top level. Do not nest it under the parameter name; the CLI applies the tree to the FilterBuilder parameter it found in step 1 (the first one, if there are several). A runtime value is a leaf operand with `"isLiteral": false`:
+
+   ```json
+   {
+     "connectionId": "<CONNECTION_ID>", "folderKey": "<FOLDER_KEY>",
+     "pathParameters": { "entityName": "<ENTITY_NAME>" },
+     "filter": {
+       "groupOperator": 0,
+       "filters": [
+         { "id": "accountNumber", "operator": "Equals",
+           "value": { "value": "=js:$vars.<node>.output.<field>", "isLiteral": false } }
+       ],
+       "groups": []
+     }
+   }
+   ```
+
+   Tree shape and operator tokens: [uipath-platform — Filter Trees (CEQL)](../../../../../uipath-platform/references/integration-service/activities.md#filter-trees-ceql).
+
+4. **Configure** — `uip maestro flow node configure <ProjectName>.flow <NODE_ID> --detail "$(cat /tmp/detail.json)" --output json` (Step 6b).
+
+5. **Verify the compile** — read the node back. `queryParameters.<name>` must hold the compiled query with a placeholder, `accountNumber = '{var_<hash>}'`, and `filterVariables` must have that `var_<hash>` key. The CLI also writes `configuration.essentialConfiguration.savedFilterTrees.<name>`. An **empty** `queryParameters.<name>` means the tree was mis-shaped (step 3): the CLI found no `filters` at the top level and compiled an empty query with no error, so the flow would fetch the whole entity.
+
+Never:
+
+- pass a CEQL string under `queryParameters.<name>` — the CLI rejects it or leaves Studio Web's tree undefined;
+- write the query as a whole-value `=js:` string — `flow validate` cannot read it (it reads only a plain concatenation) and the CLI warns on it; replace any you find with a tree;
+- hand-type `endpoint` or `pathParameters` names — take them from step 1.
+
+#### Step 6b — Run configure
+
+Run:
+
+```bash
+uip maestro flow node configure <file> <nodeId> \
+  --detail '<complete-detail-json>' \
+  --output json
+```
+
+For generic nodes include `objectName`; concrete nodes ignore it if supplied. Use `method` and `endpoint` from `registry get` for concrete activities, or `availableOperations[].method` and `availableOperations[].path` from describe for both kinds. For generic activities, describe is the only source. Copy IS labels such as `GETBYID` verbatim; the CLI normalizes them. Validate that method agrees with the node operation.
+
+Supply endpoint placeholders through `pathParameters` and resolve their IDs with `uip is resources run list` using the current connection. Body names come from `inputDefinition.fields[].name` or `requestFields[].name`.
+
+For array fields, strip trailing `[*]` from the authored key and use a `=js:` expression returning the array; literal JSON arrays do not bind. Names containing `[*].` are not authorable. This applies to body, query, and path buckets; `customFieldsRequestDetails.parameterValues` uses `_array` encoding. The expression may return the whole array or wrap one element — wrap a literal array in parentheses, `"fields.labels": "=js:(['shield', 'p0'])"`; pass a whole array from a variable as `"=js:$vars.allTags"`; wrap a single element as `"=js:([$vars.priorityTag])"`.
+
+Derive connector output shape from `connectorMethodInfo.operation`, not vendor intuition or `outputDefinition.output.type`: `list` returns a bare array; other operations return one object. Use `=js:$vars.<node>.output` for list collections and `=js:$vars.<node>.output.<field>` otherwise. Activities tagged `API.File.Download` are the exception: configure rewrites their output type to `file`, and `=js:$vars.<node>.output` is the whole attachment — feed that to an IxP node's `fileRef`, see [ixp/impl.md — Wiring `fileRef` — connector download node](../ixp/impl.md#wiring-fileref--connector-download-node).
+
+`node configure` populates `inputs.detail` and top-level `bindings[]`. The serialized folder field is `connectionFolderKey`; never hand-edit it. Do not use `filterExpression`, which belongs to trigger/JMESPath filtering; see [connector-trigger/impl.md](../connector-trigger/impl.md#filter-trees).
+
+For complex JSON, write a temporary file and run:
+
+```bash
+uip maestro flow node configure <file> <nodeId> --detail "$(cat /tmp/detail.json)" --output json
+```
+
+#### Step 6c — Populate api-type custom fields
+
+Inspect both `objectActions[]` and `connectorMethodInfo.design.actions[]`. Supported actions use top-level `ActionType: "Api"` or nested `actionType: "api"`. If no applicable api action exists, omit `customFieldsRequestDetails`; the CLI emits `null`.
+
+Illustrative supported activities (confirm against `registry get` for the specific connector/object/activity — the set evolves):
+
+| Connector key | Object | Activity / Action | HTTP | Source |
+|---|---|---|---|---|
+| `uipath-microsoft-azureapplicationinsights` | `executeQuery` | `generateSchema` | — | field |
+| `uipath-salesforce-sfdc` | `curated_soqlQuery` | `generateSchema` | — | field |
+| `uipath-workday-workdayrest` | `wql` | `generateSchema` | — | field |
+| `uipath-oracle-netsuite` | `executeSuiteQL` | `generateSchema` | — | field |
+| `uipath-snowflake-snowflake` | `executeQuery` | `generateSchema` | — | field |
+| `uipath-atlassian-jira` | `curated_create_issue` | Create Issue | POST | method |
+| `uipath-atlassian-jira` | `curated_edit_issue` | Update Issue | PUT | method |
+| `uipath-atlassian-jira` | `curated_get_issue` | Get Issue | GETBYID | method |
+| `uipath-uipath-dataservice` | `CreateEntityRecordCurated` | Create Entity Record | POST | method |
+| `uipath-uipath-dataservice` | `QueryEntityRecordsCurated` | Query Entity Records | POST | method |
+| `uipath-mailchimp-mailchimp` | `list_members_curated_dynamic::members` | Add Subscriber | POST | method |
+| `uipath-microsoft-onedrive` | `AddListItem` | Add List Item | POST | method |
+| `uipath-sap-s4hanacloud` | `Entity` | Create Entity | POST | method |
+| `uipath-google-bigquery` | `projects::table` | List All Records | GET | method |
+
+> **Data Fabric record CRUD has native nodes — they are the default; everything else on this connector is not.** `core.datafabric.read` / `create` / `update` / `delete` ([data-fabric/planning.md](../data-fabric/planning.md)) need no Integration Service connection and are authored with `Edit`/`Write` instead of `node configure`, so for those four operations go native: confirm with `uip maestro flow registry get core.datafabric.read`, and on `NodeGetSuccess` leave this doc. Stay here when **any** of these hold — and they are common:
+>
+> - the operation is **not** one of those four (attachments, file-field downloads, entity metadata, bulk work) — no native node exists, so these activities are the only path, not a fallback; **these activities target the tenant scope only — folder-scoped entities are not supported, so require a tenant-scoped entity**;
+> - the **user asked for the connector by name** — an explicit request outranks the native default, so build it here as long as the activity exists;
+> - `registry get` ends at "Node not found" after [data-fabric/impl.md — Registry validation](../data-fabric/impl.md#registry-validation).
+
+Run Step 3a and use the matched action's `name` and `apiConfiguration.{url,body}` tokens. Match `source: field` or `source: method` according to metadata; for operation-scoped lookup use the node definition's `model.context[].method`.
+
+Encode tokens longest-first: `:::` → `_sub_`; `[*]` → `_array`; `::` → `_sub_`; `.` → `_sub_`. Examples: `fields.project.key` → `fields_sub_project_sub_key`; `items[*]` → `items_array`; `tenantEntityName` → `tenantEntityName` (unchanged). Use camelCase keys and include every token from `apiConfiguration.url` and `body`:
+
+```json
+"customFieldsRequestDetails": {
+  "objectActionName": "<ObjectActionName>",
+  "parameterValues": [
+    ["<encoded-token>", "<value>"],
+    ["<unset-token>", null]
+  ]
+}
+```
+
+`customFieldsRequestDetails` complements runtime parameters: put raw parent values in `bodyParameters`, `queryParameters`, or `pathParameters`, and encoded values in the design-time cache. Values are strings or `null`; `parameterValues` is never an object map. The cache is embedded in `essentialConfiguration.customFieldsRequestDetails`, not set as a top-level `inputs.detail` field. Pass runtime values and the cache in the same configure call — omitting the runtime bucket is the most common mistake; the design-time cache alone does not feed the connector at runtime. Concrete (Jira Create Issue): `bodyParameters.fields.project.key = "<PROJECT_KEY>"` AND `parameterValues = [["fields_sub_project_sub_key", "<PROJECT_KEY>"]]`. Dropping the runtime-input copy manifests as `DAP-DT-_2003 refField with name <X> not found` at activity load. The CLI does not validate action existence or token coverage, so Step 3a is mandatory.
+
+**Worked `--detail` payloads** — each passes BOTH the runtime bucket and the design-time cache in one call.
+
+Jira Create Issue — `source: method` (raw `fields.project.key` in body + encoded `fields_sub_project_sub_key` in cache):
+
+```bash
+uip maestro flow node configure <file> <nodeId> --detail "$(cat <<'JSON'
+{
+  "connectionId": "<id>",
+  "folderKey": "<key>",
+  "method": "POST",
+  "endpoint": "/curated_create_issue",
+  "bodyParameters": {
+    "fields.project.key": "<PROJECT_KEY>",
+    "fields.issuetype.id": "3",
+    "fields.summary": "Created from Maestro"
+  },
+  "customFieldsRequestDetails": {
+    "objectActionName": "GenerateSchema",
+    "parameterValues": [
+      ["fields_sub_project_sub_key", "<PROJECT_KEY>"],
+      ["fields_sub_issuetype_sub_id", "3"]
+    ]
+  }
+}
+JSON
+)" --output json
+```
+
+Snowflake Execute Query — `source: field` (SQL string is the parent field; `query` unchanged, no dots):
+
+```bash
+uip maestro flow node configure <file> <nodeId> --detail "$(cat <<'JSON'
+{
+  "connectionId": "<id>",
+  "folderKey": "<key>",
+  "method": "POST",
+  "endpoint": "/executeQuery",
+  "bodyParameters": {
+    "query": "SELECT id, name FROM customers WHERE active = TRUE"
+  },
+  "customFieldsRequestDetails": {
+    "objectActionName": "generateSchema",
+    "parameterValues": [
+      ["query", "SELECT id, name FROM customers WHERE active = TRUE"]
+    ]
+  }
+}
+JSON
+)" --output json
+```
+
+Dataservice V3 Query Entity Records — `source: method` (`tenantEntityName` unchanged, no dots):
+
+```bash
+uip maestro flow node configure <file> <nodeId> --detail "$(cat <<'JSON'
+{
+  "connectionId": "<id>",
+  "folderKey": "<key>",
+  "method": "POST",
+  "endpoint": "/v3/QueryEntityRecords/query",
+  "queryParameters": {
+    "entityScope": "tenant",
+    "tenantEntityName": "\"my-entity\""
+  },
+  "customFieldsRequestDetails": {
+    "objectActionName": "FetchObjectMetadataTenant",
+    "parameterValues": [
+      ["tenantEntityName", "\"my-entity\""]
+    ]
+  }
+}
+JSON
+)" --output json
+```
+
+## IS CLI commands
+
+```bash
+uip is connections list "<connector-key>" --all-folders --output json
+uip is connections ping "<connection-id>" --output json
+uip is connections create "<connector-key>"
+uip maestro flow registry get <node-type> --connection-id <connection-id> --output json
+uip is resources describe "<connector-key>" "<objectName>" \
+  --connection-id "<id>" --operation Create --output json
+uip is resources run list "<connector-key>" "<resource>" \
+  --connection-id "<id>" --output json
+uip is connectors list --output json
+```
+
+Run `uip is connections --help` or `uip is resources --help` for all options.
+
+## Bindings
+
+Bindings belong in flow top-level `bindings[]`, alongside `nodes`, `edges`, and `definitions`. At debug/pack time the CLI regenerates `content/bindings_v2.json`; never edit that generated file.
+
+Leave the registry definition's `model.context[]` unchanged. Connector definitions typically contain `<bindings.<connector-key> connection>` and `<bindings.FolderKey>` placeholders. Do not author `model.context[]` on the node instance. Connector binding matching is name-only within `resource: "Connection"` because `model.bindings.resourceKey` is typically unset. Resource nodes instead match `(name, resourceKey)`.
+
+`node configure` claims the empty connection stub created by `node add` and adds the folder row. For each unique connection it emits two entries:
+
+```json
+{
+  "id": "<unique-id>",
+  "name": "<connector-key> connection",
+  "type": "string",
+  "resource": "Connection",
+  "resourceKey": "<connection-uuid>",
+  "default": "<connection-uuid>",
+  "propertyAttribute": "ConnectionId"
+}
+```
+
+and:
+
+```json
+{
+  "id": "<unique-id>",
+  "name": "FolderKey",
+  "type": "string",
+  "resource": "Connection",
+  "resourceKey": "<connection-uuid>",
+  "default": "<folder-key>",
+  "propertyAttribute": "FolderKey"
+}
+```
+
+The connection binding `name` is fetched from IS by `node configure` and must match the definition placeholder. Both entries use the same UUID. `resource` is capitalized `"Connection"`; `propertyAttribute` is exactly `"ConnectionId"` or `"FolderKey"`. Reuse the same pair for nodes sharing a connection; do not add duplicates.
+
+An empty `resourceKey` on a configured `ConnectionId` row is a defect and causes `Value cannot be null. (Parameter 'Connection')`. Do not remove or repair bindings by hand. The only legitimate empty stub is a deliberately planned, unconfigured node. An empty stub after successful configure or node removal is a CLI bug to report.
+
+Never hardcode connection IDs; fetch them from IS at authoring time. Connector-trigger flows may additionally emit `EventTrigger` and `Property` resources; see [connector-trigger/impl.md](../connector-trigger/impl.md). Queue and time-trigger resources follow their relevant plugins.
+
+## Debug and common errors
+
+- **No connection found:** top-level `bindings[]` is missing or mismatched. Run Step 1 and verify `ConnectionId` and `FolderKey` entries.
+- **Connection ping failed:** re-authenticate the connection in IS.
+- **Missing `inputs.detail`:** run `node configure`.
+- **Display name instead of reference ID:** resolve with `uip is resources run list`.
+- **Resource not found after clean validate/debug:** resolve the reference again with the current connection; IDs are connection-scoped. Reconfigure and re-debug.
+- **Required field missing:** inspect every `required: true` entry in cached `requestFields` and `parameters`.
+- **`No api-type ObjectAction matched for fields [...]`:** pass the node definition's `model.context[].method` verbatim as `--operation`; do not use `connectorMethodInfo.operation` or `connectorMethodInfo.method`.
+- **IxP extraction fails `[430002] … missing the required 'ID' field` downstream of a download activity:** read the download node's `definitions[]` entry before assigning a cause. `outputDefinition.output.type` still `"object"` means configure never ran and the output is plain JSON, not an attachment — configure it, required file parameter included, and re-debug. Already `"file"` means configure ran, so inspect the download's own inputs and result instead. See [ixp/impl.md — Wiring `fileRef` — connector download node](../ixp/impl.md#wiring-fileref--connector-download-node).
+- **Unresolvable `$vars`:** verify graph edges and upstream output paths.
+- **Missing method/path:** rerun `registry get` with `--connection-id` or use describe for generic activities.
+- **Malformed or stale `bindings_v2.json`:** never edit it; rerun `node configure` and debug/pack.
+- **Connector key not found:** run `uip is connectors list --output json`; keys are often prefixed with `uipath-`.
+- **FilterBuilder UI is `undefined`:** configure a structured tree under the `filter` key of `--detail`, not a raw `queryParameters` string.
+- **FilterBuilder configure rejection:** move the value into the `filter` key of `--detail` as a structured tree.
+- **Data Service filter returns every record or malformed CEQL ending in `AND`:** compare tree field IDs case-sensitively with `uip df entities get <entity-id> --output json`; unmatched leaves are dropped.
+- **CEQL `[102003]` field-name error, or `[102001]`:** the query was hand-written as a string. Delete it and configure a filter tree under the `filter` key of `--detail` (Step 6a); put runtime values in a leaf operand with `"isLiteral": false`.
+- **`parameterValues` object-map error:** use `[key, value]` tuples.
+- **`[400300] Error evaluating expression … Invalid or unexpected token`, or the command itself dies with a shell parse error (`zsh: parse error`, `bash: syntax error near unexpected token`):** the `=js:` expression was hand-escaped through nested shell quotes inside `--detail '<json>'`. Write the detail JSON to a file with a quoted heredoc and pass `--detail "$(cat /tmp/detail.json)"`. See [editing-operations-cli.md — Configure a connector node](../../editing-operations-cli.md#configure-a-connector-node).
+- **Custom-field token unresolved:** reread `apiConfiguration.url` and `body` and add every encoded token.
+- **Unknown `ObjectActionName` or `ParameterValues`:** use camelCase `objectActionName` and `parameterValues`.
+- **Array field rejected as unknown:** strip trailing `[*]`, use a `=js:` array expression, and reconfigure. Names containing `[*].` are not authorable.
+- **Array field round-trips empty:** replace the literal JSON array with a `=js:` expression returning the array.
+
+## Final checks
+
+1. Inspect top-level `bindings[]`; do not treat `bindings_v2.json` as ground truth.
+2. Compare every input with the cached metadata file.
+3. Remember that `flow validate` checks JSON schema and graph structure, not missing connector inputs, wrong reference IDs, or expired connections; run `flow debug`.
+4. Check both `requestFields` and `parameters`.
+5. Confirm `node configure` was run with the complete intended detail on every reconfiguration.
+6. If planning-only, record the planned sidecar `<nodeId>.detail.json`, do not author `bindings[]` directly, and report that validation requires real configuration.