@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-connector-builder/references/element-json.md

@@ -0,0 +1,148 @@
+# element.json Reference
+
+The core connector definition at `app/element/element.json`. Udon reads it to know how
+to authenticate, call vendor APIs, map parameters, and apply hooks.
+
+**How it's edited.** Use the orchestrator verbs — `init` (creates the shell; seeds the
+connector-level fields and `base.url`), `auth set` (the whole authentication block +
+config keys), `activity create` (`resources[]` + the SR), `auth system create` (system
+`resources[]` entries). Edit a long-tail field no verb exposes (`displayOrder`,
+`extended`, `typeOauth`, `cloneable`, a single param) surgically with `state patch`. The
+command map and workflows live in SKILL.md — don't re-derive them here.
+
+## Top-Level Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | string | Element key. For a design connector: `design-{org}-{slug}` (derived by `init` from `--name` + `--organization`). |
+| `name` / `description` | string | Catalog display values (`init --name` / `--description`). |
+| `hub` | string | Legacy/obsolete. Paths work with or without the hub prefix. Don't set on new connectors. |
+| `authentication` | object | `{ "type": "oauth2" }` — primary auth type. Multi-auth uses an `authentication.type` COMBO config with groupControl. Owned by `auth set`. |
+| `typeOauth` | boolean | `true` if primary auth is any OAuth/JWT variant. Set by `auth set`. |
+| `configuration` | array | Config entries (auth creds, base URL, pagination, events). See [configuration.md](configuration.md). |
+| `resources` | array | One entry per HTTP method per endpoint. |
+| `parameters` | array | Global parameters (headers, auth mappings). Same schema as resource parameters. Add a header with `init --header VendorName=value`; remove with `init header delete <VendorName>`. |
+| `hooks` | array | Global hooks applied to ALL requests (`activity hook create --global`). See [hooks.md](hooks.md). |
+| `paginatorVersion` | int/string | Paginator engine: `2` standard, `"V3"` newer. |
+| `publishStatus` | string | `"draft"` or `"published"`. |
+| `protocolType` | string | Almost always `"http"`. |
+| `cloneable` / `extended` / `transformationsEnabled` | boolean | Usually true / false / true. |
+| `elementMetadata` | object | Embedded object INSIDE element.json (`key`, `name`, `authenticationTypes[]`, `discovery`, `api`, `bulk`, `pollingResources`) — distinct from the separate `element-metadata.json` file, which holds catalog flags (`hasEvents`, `hasHttpRequest`, categories, and `latestVersion` — `init` seeds it to `"1.0.0"`). |
+
+## resources[]
+
+Each entry = ONE HTTP method for ONE endpoint. An "accounts" resource created with
+GET/GETBYID/POST/PATCH/DELETE has 5 entries (one `activity create` call writes them all).
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `method` | yes | Udon method: GET, GETBYID, POST, PATCH, PUT, DELETE. |
+| `path` | yes | Udon path / IS slug (e.g. `/accounts`). Hub prefix is legacy/optional. |
+| `vendorPath` | yes | Vendor API path. May differ from `path` (`--vendor-path`, per-method `--method-vendor-path`). |
+| `vendorMethod` | yes | Vendor HTTP method (usually same as `method`). |
+| `type` | yes | Resource type — see below (`--resource-type`). |
+| `standardResourceName` | no | Canonical link to the SR file. Absent on system resources. |
+| `rootKey` | no | JSON path to the list array (`--root-key`, e.g. `"value"`, `"data.items"`). |
+| `nextPageKey` | no | Non-standard next-page token location (`--next-page-key`). |
+| query-param vendor names | no | On a LIST GET, the CEQL filter + pagination query params default to vendor names `where`/`pageSize`. Override to the vendor's real names with `--filter-param` (e.g. `sysparm_query`), `--page-size-param` (e.g. `sysparm_limit`, `per_page`), and `--offset-param` (e.g. `sysparm_offset`, `page`) — the offset param is ADDED only when named. These set `vendorName` while the activity-input `name` stays canonical, and never apply to by-id reads. |
+| `parameters` | no | Per-resource parameter mappings (`activity param create`; see below). |
+| `hooks` | no | Hook refs for this resource+method (`activity hook create`). |
+| `expressions` | no | `requestBodyRoot` / `responseBodyRoot` for JSON-path wrap/unwrap. |
+
+For by-id methods (`GETBYID`/`PATCH`/`PUT`/`DELETE`) `activity create` auto-adds the
+`/{primaryKey}` path param — ALWAYS for `GETBYID`, and for the write methods only on a CRUD
+activity (one that also has `GET`/`GETBYID`); a write-only activity keeps its base path.
+Details in [standard-resources.md](standard-resources.md) §"by-id methods".
+
+### Resource types
+`api` (discoverable, in CRUD dropdowns), `apiNoDocumentation` (hidden but callable),
+`apiElementRequest` (routes back through Udon; still appears in CRUD unless `isHidden`),
+plus the 13 **system types** (no SR file) created via `auth system create`:
+`onProvision`, `onDelete`, `onRefresh`, `provisionAuthValidation`, `oauthOnAuthroizeUrl`
+(historical typo — keep it), `oauthOnTokenExchange`, `oauthOnTokenRefresh`,
+`oauthOnTokenRevoke`, `oauth1OnTokenRequest`, `oauth2ClientCredentials`,
+`onProvisionWebhook`, `onDeleteWebhook`, `onProvisionCacheVendorDataAsync`.
+[system-resources.md](system-resources.md) is the authoritative list with override paths.
+
+## parameters[] (global and per-resource)
+
+Same schema at both levels. element.json is the **source of truth** for contract fields
+(`name`, `vendorName`, `type`, `vendorType`, `dataType`, `vendorDataType`, `required`,
+`description`, `source`); linked SR params auto-reconcile on every write. SR-only UI
+fields (`displayName`, `requestCurated`, `sortOrder`, `design`) are preserved. Add with
+`activity param create --resource <name> --method <VERB> --name <p> --type <type>` (`--type`
+e.g. `path`/`query`/`header`/`body` — the full accepted enum is listed below).
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Udon-side name. For `type:"value"`, this IS the literal value. |
+| `vendorName` | yes | Vendor-side name. |
+| `type` | yes | WHERE the value comes from (source). |
+| `vendorType` | yes | WHERE it goes in the vendor request (destination). |
+| `dataType` / `source` / `required` / `design` | no | Hints, request/response, requiredness, UI. |
+
+`type`/`vendorType` values: `configuration`, `header`, `path`, `query`, `file`, `form`,
+`multipart`, `value`, `customValue`, `body`, `bodyField`, `prevBody`, `prevBodyField`,
+`bodyToken`, `no-op`.
+
+Common patterns:
+```json
+{"name": "application/json", "vendorName": "Accept", "type": "value", "vendorType": "header"}
+{"name": "id", "vendorName": "customerId", "type": "path", "vendorType": "path"}
+{"name": "oauth.user.token", "vendorName": "Authorization", "type": "configuration", "vendorType": "header"}
+{"name": "pageSize", "vendorName": "limit", "type": "query", "vendorType": "query"}
+```
+
+### Static / constant query parameters — use `type:"value"`, NOT a query string
+
+A **constant** query param the connector must always send (an API version, a fixed
+`format=json`, a feature flag) MUST be modelled as a `value` param whose `name` holds the
+literal value and whose `vendorType` is `query`:
+```json
+{"name": "2023-07-31", "vendorName": "api-version", "type": "value", "vendorType": "query"}
+```
+This sends `?api-version=2023-07-31` exactly as written and never prompts the connection
+user. **Do NOT leave the constant in the vendor path as a query string** (e.g.
+`vendorPath: "/info?api-version=2023-07-31"`): on import the server parses that `?k=v`
+into a `type:"query"` param that is *required user input with no value*, so every runtime
+call (and `provisionAuthValidation` / connection test) fails with "value for 'api-version'
+not passed". This applies everywhere a vendor path is set — activity resources AND the
+auth-validation path (`auth set --validation-vendor-path`). The CLI `activity`/`auth`
+verbs now auto-extract a trailing `?k=v` into a `value` param for you, so prefer passing a
+clean base path; if you ever hand-edit `element.json`, follow the rule yourself. A `value`
+param is stored in **plaintext** — only for non-secret constants; a secret belongs in an
+encrypted `configuration` entry referenced via `type:"configuration"`, never a literal.
+
+### Value interpolation (`${...}`)
+For `type:"value"` params, Udon substitutes `${<namespace>.<key>}` in the `name` field at
+request time. Namespaces: `configuration`, `header`, `body`. Special tokens (no prefix):
+`${webhookCallbackUrl}`, `${elementWebhookCallbackUrl}`, `${encodedId}`, `${date}`,
+`${date:FORMAT}` / `${gmtDate:FORMAT}` / `${dateTimeZone:TZ:FORMAT}` (event-poller only — see [events.md](events.md)).
+This is how a prefix like `Bearer <token>` is applied without a hook:
+```json
+{"name": "Bearer ${configuration.oauth.user.token}", "vendorName": "Authorization", "type": "value", "vendorType": "header"}
+```
+Unresolved tokens are left verbatim (silent failure) — validate spellings against
+`configuration[]`. No escape for a literal `{`. Prefer `type:"configuration"` for a 1:1
+map; use `type:"value"` + interpolation when you need a prefix/suffix/composition.
+
+## Editing surgically with `state patch`
+The no-merge round-trip rule (query → edit → patch the COMPLETE object back) is SKILL.md
+Rule 5. element.json-specific pointer detail: resource pointers URL-encode the path
+(`/contacts` → `%2Fcontacts`, e.g. `element.json/resources/GET/%2Fcontacts`);
+`element-metadata.json` has no addressable sub-paths (round-trip the whole file); `--op remove`
+deletes one addressed item (e.g. a parameter by index); `state query --help` prints the grammar.
+
+## Hook execution order
+Global hooks wrap resource hooks around the vendor call. Canonical order, context vars,
+naming, and the token-derived base-URL pattern: [hooks.md](hooks.md).
+
+## Expressions
+`requestBodyRoot` wraps the body (`"contact"` → `{"contact": ...}`); `responseBodyRoot`
+unwraps the response (`"data.items"`). Both are real element.json fields but have NO builder
+flag — author them by `state patch` of the whole resource entry (`"expressions": {...}`), then
+`validate`. For a plain list unwrap prefer `rootKey` (`--root-key`), which the CLI does expose.
+
+## See also
+- [configuration.md](configuration.md), [standard-resources.md](standard-resources.md),
+  [hooks.md](hooks.md), [system-resources.md](system-resources.md), [auth.md](auth.md)

package/skills/uipath-connector-builder/references/events.md

@@ -0,0 +1,132 @@
+# Events Reference
+
+Events detect vendor-side changes (CREATED / UPDATED / DELETED). Two mechanisms:
+**polling** (periodic API calls) and **webhooks** (vendor pushes notifications). An event
+source is always an existing activity — wire it AFTER the activity exists.
+
+## How events are configured NOW
+
+`uip is connectors builder trigger create` is the single entry point, and it **authors a
+polling trigger** — it always wires the polling loop and always writes a polling-shaped SR
+`metadata.events` (`eventMode: ["polling"]`), regardless of `--event-kind`. One call seeds the
+event config bundle, writes the per-resource poller config, sets the SR `metadata.events`, and
+flips `hasEvents`. The activity must already exist — `trigger create` HARD-FAILS if its SR is
+missing. Runnable workflow: SKILL.md → "Add a polling trigger".
+
+**Webhook caveat.** `--event-kind webhook | all` only adds the webhook CONFIG KEYS (below) to
+the bundle; it does NOT implement webhook delivery and does NOT change the polling-shaped SR
+metadata. A working webhook still needs `onProvisionWebhook`/`onDeleteWebhook` system resources
+plus a post hook (see [system-resources.md](system-resources.md), [hooks.md](hooks.md)). And
+`--updated-date-field` is REQUIRED even for `webhook`/`all`.
+
+Key flags (`trigger create`):
+- `--resource-name <name>` — existing activity/standard-resource to wire (required).
+- `--event-kind polling | webhook | all` — which config bundle to seed (default `polling`).
+- `--updated-date-field <field>` — vendor last-modified field, e.g. `LastModifiedDate` (REQUIRED for every `--event-kind`).
+- `--created-date-field <field>` — defaults to `--updated-date-field`.
+- `--id-field <field>` — primary key (defaults to `Id`).
+- `--date-format <mask>` / `--created-date-format <mask>` — timestamp mask (created defaults to updated).
+- `--event-types <csv>` — defaults to `CREATED,UPDATED,DELETED`.
+- `--polling-url <url>` — explicit; auto-generated from the GET path when omitted.
+- `--date-timezone <tz>` — default `GMT`.
+- `--polling-resource-label <label>` — label in `elementMetadata.pollingResources`.
+- `--override <key>=<value>` — per-entry defaultValue override for the event preset (repeatable).
+
+These are the flags with non-obvious defaults/semantics; `trigger create --help` is the
+always-current full list.
+
+## What gets written
+
+1. `element-metadata.json → hasEvents: true` (without it, events never fire).
+2. `element.json → configuration[]` — the event config keys (the preset bundle).
+3. `standard-resources/<name>.json → metadata.events` — per-resource event metadata.
+4. `element.json/configuration/event.poller.configuration` — the polling JSON blob below.
+
+## Polling config keys (the bundle)
+
+`event.notification.enabled` (master switch), `event.vendor.type` (`polling` / `webhook`),
+`event.poller.refresh_interval` (minutes, default 15), `event.poller.configuration`
+(JSON blob below), `event.notification.callback.url`, `event.raw.enabled`.
+
+## event.poller.configuration JSON
+
+Each resource is keyed by its **normalized resource name** — `trigger create` derives the key
+as `resourceName` with `/` and `::` replaced by `_` (so `accounts` → `accounts`, `crm/leads`
+→ `crm_leads`). It is NEVER literally `"events"`.
+```json
+{
+  "accounts": {
+    "url": "/accounts?where=LastModifiedDate>'${gmtDate:yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}'",
+    "idField": "Id",
+    "datesConfiguration": {
+      "updatedDateField": "LastModifiedDate",
+      "updatedDateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSSZ",
+      "updatedDateTimezone": "GMT",
+      "createdDateField": "CreatedDate",
+      "createdDateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
+    },
+    "createdCheckTolerance": 10
+  }
+}
+```
+Per-resource fields: `url` (required — IS slug path with the generated `${gmtDate:FORMAT}` /
+`${dateTimeZone:TZ:FORMAT}` poll-time placeholder; see the placeholder note below),
+`idField` (required — unique key), `datesConfiguration` (required),
+`createdCheckTolerance` (sec, default 10), `filterByUpdatedDate`, `filterByCurrentDate`,
+`pageSize`, `pollDelay`, `batchSize`, `postHooks`, `postHookPipelines`, `useLastPollDate`,
+`useHydrationBeforePostHooks`, `objectName`, `parameters`.
+
+`datesConfiguration`: `updatedDateField`, `updatedDateFormat` (Java SimpleDateFormat),
+`updatedDateTimezone` (default GMT), `createdDateField`, `createdDateFormat`
+(defaults to updated), `createdDateTimezone`.
+
+`trigger create` GENERATES the poll-time placeholder from `--date-timezone`: the default `GMT`
+yields `${gmtDate:FORMAT}`; any other timezone yields `${dateTimeZone:<TZ>:FORMAT}`. (`${date:FORMAT}`,
+local time, is also a valid runtime token if you hand-author a URL.) Each is replaced at runtime
+with the last poll time; the FORMAT must match what the vendor accepts (e.g. Salesforce
+`yyyy-MM-dd'T'HH:mm:ss.SSSZ`, most REST `yyyy-MM-dd'T'HH:mm:ss'Z'`, ISO `yyyy-MM-dd'T'HH:mm:ssXXX`,
+or epoch millis).
+
+To tweak one key after `trigger create`, `state query` the entry then `state patch` the
+complete object back (patch REPLACES — see [debugging.md](debugging.md)).
+
+## Webhook config keys (`--event-kind webhook` or `all`)
+
+`event.notification.callback.headers`, `event.notification.signature.key` (HMAC),
+`event.notification.basic.username`, `event.notification.basic.password`,
+`event.notification.instance.finder`. Webhooks usually need `onProvisionWebhook` /
+`onDeleteWebhook` system resources + a post hook (see
+[system-resources.md](system-resources.md), [hooks.md](hooks.md)).
+
+## SR-level event metadata (`metadata.events`)
+
+`trigger create` writes this — DON'T hand-author it. The shape periodic requires (a flat
+`{type:"polling", …}` is silently IGNORED — `event-operations` comes back empty and the trigger
+never fires):
+
+```json
+"events": {
+  "eventMode": ["polling"],
+  "polling": {
+    "configuration": {
+      "datesConfiguration": { "updatedDateField": "...", "updatedDateFormat": "...",
+        "updatedDateTimezone": "GMT", "createdDateField": "...", "createdDateFormat": "..." },
+      "idField": "id",
+      "url": "/tickets?where=modifiedTime>'${gmtDate:...}'",
+      "useLastPollDate": true
+    },
+    "eventTypes": [
+      { "operation": "CREATED", "displayName": "Record Created", "description": "..." },
+      { "operation": "UPDATED", "displayName": "Record Updated", "description": "..." }
+    ]
+  }
+}
+```
+
+Each `eventTypes[]` entry: `operation` (CREATED / UPDATED / DELETED / a curated op like
+TICKET_CLOSED), `displayName`, `description`, optional `objectName`. Top-level `eventMode` is the
+array `["polling"]` (or `["webhooks"]` / `["fps"]`). Confirm a published trigger surfaced with
+`uip is connectors event-operations <custom-key>` — a non-empty list means it's wired.
+
+## See also
+- [configuration.md](configuration.md), [debugging.md](debugging.md), [standard-resources.md](standard-resources.md)

package/skills/uipath-connector-builder/references/hooks.md

@@ -0,0 +1,198 @@
+# Hooks Reference
+
+Hooks are JavaScript files that transform requests before they hit the vendor
+(`preRequest`) or transform responses before returning to the caller (`postRequest`).
+
+## Decide first: hook or built-in?
+
+A hook is JS you maintain forever, run in a sandboxed JS engine. **Reach for one only when no
+declarative feature does the job** — across shipped connectors the largest category of hooks
+(static headers, constant query params, one-line response unwraps) is avoidable. Check this
+table first:
+
+| You want to… | Use this built-in (NO hook) | Write a hook ONLY when… |
+|---|---|---|
+| Add a constant/credential header (`Authorization: Bearer`, `Accept`) | `type:"value"` param + `${configuration.<key>}`, or `type:"configuration"` for a 1:1 map — [element-json.md](element-json.md) §"Value interpolation" | the value is *computed* (a signature, JWT-derived id, conditional on input) |
+| Send a constant query param (`api-version`, `format=json`) | `type:"value"` query param — [element-json.md](element-json.md) §"Static / constant query parameters" | the param's presence/value depends on input |
+| Per-connection host / region / instance in a URL | `{placeholder}` in the URL + auto-seeded config — [configuration.md](configuration.md) §"Templated (per-instance / per-region / per-workspace) hosts" | the host must be *derived* from a token/response and validated |
+| Return the inner list from a wrapper (`{data:[…]}`, `{value:[…]}`) | `rootKey` (`activity create --root-key`) — [element-json.md](element-json.md) §resources[] | the reshape flattens, computes, or joins fields |
+| Wrap the request body (`{…}` → `{"contact":…}`) | `requestBodyRoot` — no builder flag; see [element-json.md](element-json.md) §Expressions | the body is restructured by input value |
+| Rename a list/filter/page param (or any param) to the vendor's name | `--filter-param` / `--page-size-param` / `--offset-param` (generated list params), else `activity param create --vendor-name` — [element-json.md](element-json.md) §resources[] | the value must be transformed, not just renamed |
+| Standard offset / cursor / page pagination | pagination preset ([configuration.md](configuration.md) §"Pagination keys") + `activity create --pagination-type` / `--next-page-key` (`paginatorVersion` is top-level — [element-json.md](element-json.md)) | the cursor is derived from the payload with stateful logic |
+| Verify credentials at connect time | `provisionAuthValidation` system resource — [system-resources.md](system-resources.md) §provisionAuthValidation | only to ADD a postRequest hook for a *computed* `connection_identity` or a custom vendor-error message — never to replace the check |
+| Show a connection's display name from a plain response/config field | `connection.identity.lookup.key` config = the field's path (in the base preset; add via `state patch` if absent) — no hook | the identity must be *computed/combined* from several values |
+
+If the third column applies — or your need is in the next list — a hook is the correct tool.
+
+## Hooks that earn their keep
+
+These genuinely need JS — no declarative feature expresses them (request-side → `preRequest`,
+response-side → `postRequest`). Each is a real shipped pattern:
+
+- **Delimited-string ↔ JSON** — CSV recipients → `[{emailAddress}]`, `name:value;` pairs → arrays, a comma list → a typed object (often with input validation).
+- **Query-language assembly** — build JQL / SOQL / CEQL / OData `$filter` (or dialect SQL) from several typed params.
+- **Conditional body reshape by value** — enum label → vendor code, `field` → `field@odata.bind`, flat fields → nested arrays.
+- **Multipart / upload-session / MIME assembly** — create-upload-session then hand off the URL; file-vs-`urlSource` dual mode.
+- **Multi-call orchestration** — a secondary call via `require('axios')`, a thread→run→poll state machine, read-modify-write. Chains via `request_previous_response`.
+- **Object-discovery metadata synthesis** — vendor field schema → typed UiPath field metadata (`type`/`format`/`mask`/`enum`) at runtime.
+- **Connection facts derived from a token/response** — instance/base URL, org/cloud/tenant id (JWT decode), validated and persisted. Recipe below.
+- **`connection_identity` (computed)** — `done({connection_identity: name})` when the display name must be built/combined; a plain field uses the `connection.identity.lookup.key` config (no hook).
+- **Context-dependent error rewriting** — a raw 4xx → actionable guidance ("wrong region — verify .com/.in/.eu"), or eventual-consistency → retry. (NOT a bare pass-through.)
+- **Conditional status-code mapping** — 304→empty 200, 409→200, a 202 async callback.
+- **Stateful polling cursors** — per-entity token maps, delta-link self-healing, last-id cursors. Beyond the pagination preset.
+- **Vendor quirks no flag covers** — empty-body / strip `Content-Type`, path `decodeURIComponent`, custom date formats, dynamic signatures (RS256 JWT), deeply-nested array→object hoist (find-by-attribute), chunked/streamed response reassembly.
+
+## Recognizing an avoidable hook
+
+Patterns shipped connectors hand-wrote when a built-in (table above) would do — delete or never add:
+
+- **Anything in the decision table's left column** — plain response unwrap (`response_body.value`/`.data`, the biggest cluster), static/credential header, constant query param, host templating, body wrap, param rename.
+- **Constant body fields** (`enableAutoReply:false`) → a `type:"value"` param with `vendorType:"bodyField"`.
+- **Bare error pass-through** (`if(response_iserror){done();return;}` with nothing after) — delete it; the runtime already surfaces vendor errors.
+- **The same response transform copied across resources** (e.g. de-prefixing Graph `@odata.*` keys — itself hook-only: the builder has no declarative response-key rename) — make it one `--global` hook (see §Naming).
+
+## Authoring a hook
+
+Use `uip is connectors builder activity hook create` (NOT a standalone `hook create`). It writes
+the `.js` under `hooks/` and registers it in element.json unless `--no-auto-register`.
+
+**You write the hook body; the CLI just places and registers it** — there are no per-shape
+scaffold flags. Author the `.js` (the decision table above + `activity hook create --help`, which
+lists the in-scope vars and the `done()` contract, give you everything), then attach it:
+
+```bash
+# resource hook from an agent-written JS file
+uip is connectors builder activity hook create --resource-name accounts --method GET \
+  --hook-type postRequest --custom-code-file ./accounts-postRequest.js
+
+# global hook
+uip is connectors builder activity hook create --hook-type preRequest --global \
+  --custom-code-file ./global-pre.js
+```
+Scope with `--resource-name` + `--method`, or `--global`; `--hook-type preRequest|postRequest`;
+supply the body with `--custom-code-file <path>` (or `--custom-code <js>`). With no body it writes
+a minimal editable stub. Run `activity hook create --help` for the rest (`--context-params`, `--no-auto-register`).
+
+## Where they live
+
+Files in `app/element/hooks/*.js`; registered in element.json `resources[].hooks[]`
+(resource-level) or the top-level `hooks[]` (`--global`).
+
+## Execution order
+
+1. Global preRequest → 2. Resource preRequest → [vendor call] → 3. Resource postRequest
+→ 4. Global postRequest. Global hooks always run, even when resource hooks exist.
+
+## Hook reference object
+
+```json
+{"mimeType": "application/javascript", "type": "preRequest", "bodyOrRef": true, "ref": "resource-accounts-GET-preRequest.js", "contextParams": "request_vendor_body,configuration"}
+```
+`mimeType` (always `application/javascript`), `type` (`preRequest` / `postRequest`),
+`bodyOrRef` (always `true` — the hook body lives in the referenced file, not inline), `ref`
+(filename in `hooks/` — the canonical link), `contextParams` (comma-separated context vars).
+
+**`contextParams` is the runtime binding allow-list** — a variable is injected only if it is listed,
+so a wrong list means the vars your code reads come back `undefined` (a silent break). **You don't
+manage it:** `activity hook create` derives it from your hook body, binding exactly the variables the
+code references. Pass `--context-params` only as an escape hatch — to add `multipart_hook_context_items`
+(opt-in; never auto-injected) or to deliberately override the derived set.
+
+## Naming
+
+`activity hook create` derives the filename. Resource:
+`resource-{Resource}-{METHOD}-{preRequest|postRequest}.js`; global:
+`global-preRequest.js` / `global-postRequest.js`. Each resource+method+phase maps to its own
+file — you cannot point two resources at one shared file, so when two resources need the same
+logic you copy it. When ONE transform should apply to every request/response (and is safe to run
+on all of them — else guard it inside the hook), write it once as a `--global` hook instead of copying.
+
+## JS engine (Denali)
+
+Hooks run in Udon's **Denali** engine, which supports modern JS — shipped hooks freely use
+optional chaining (`?.`), nullish coalescing (`??`), `async`/`await`, and `require()` for a small
+module set: `axios` (secondary HTTP calls — the basis of multi-call orchestration), `crypto`, `url`,
+`querystring`, `util`, `buffer`, `zlib`, `lodash`, `jmespath`, `moment` (the full menu prints in
+`activity hook create --help`). Match the surrounding connector's style. **Every code path MUST end
+with an explicit `done()`** (or `done({...})`) — a hook returns through that call, not via `return`.
+
+## Context vars (what's in scope)
+
+A hook reads a fixed set of variables and returns via `done({...})` — never `return`, on **every**
+path. *read* = readable input; *read/write* = readable AND returnable via `done()`; *done()-only* =
+NOT injected (you can't read it; it only has meaning when returned, and needs no `contextParams`
+entry). The full per-variable contract is in `activity hook create --help`; the commonly used set:
+
+**preRequest**
+
+| var | use | notes |
+|---|---|---|
+| `request_body_map` | read | the curated request body **as a map** — read fields directly (`request_body_map.group`), no `input[0]` wrapper |
+| `request_parameters`, `request_headers`, `request_path_variables` | read | the incoming call |
+| `request_expression` | read | CEQL `where` → `[{attribute,value,operator}]` |
+| `request_previous_response` | read | predecessor's response in a chained resource |
+| `configuration` | read | instance config map — **read-only in preRequest** |
+| `request_vendor_body` | read/write | what's sent to the vendor (string on read; list\|map\|string on write) |
+| `request_vendor_parameters`, `request_vendor_headers`, `request_vendor_method` | read/write | what's sent to the vendor |
+| `request_vendor_path` | read/write | what's sent; **a value starting with `http` becomes the full request URL** |
+| `request_root_key`, `multipart_hook_context_items` | read/write | nest the body / multipart items |
+| `continue: false` | done()-only | skip the vendor call — **the postRequest hook still runs** |
+| `response_body` / `response_status_code` / `response_error_message` | done()-only | short-circuit a response without calling the vendor |
+
+**postRequest**
+
+| var | use | notes |
+|---|---|---|
+| `response_body` | read/write | the parsed vendor response — **read it here**, and return it to reshape |
+| `response_iserror` | read | `true` unless HTTP **200–207**; read-only (returning it does nothing) |
+| `response_body_raw`, `response_headers`, `response_status_code`, `response_root_key` | read/write | |
+| `request_*`, `request_previous_response` | read | values as sent to the vendor |
+| `configuration` | read/write | **writable here** — persist derived per-connection values (recipe below) |
+| `multipart_hook_context_items` | read/write | |
+| `response_error_message` | done()-only | converts the call to an error (status from `response_status_code`, else 400) |
+| `connection_identity` | done()-only | set the connection's display name (honored in **both** phases) |
+| `metadata_merge` / `merge_objects` | done()-only | object-discovery resources only |
+
+`configuration` is the one var whose write-ability differs by phase (read-only pre, writable post): a
+preRequest `configuration` write has no effect — persist derived per-connection values in a
+postRequest hook (recipe below).
+
+## Pattern: base URL (or any per-connection value) derived from a token response
+
+Some vendors return the instance/base URL only in the token response (Salesforce
+`instance_url`). There is NO vendor-specific base-url flag — `init --base-url` is static.
+The default OAuth exchange isn't directly hookable, so author a system resource to hang the
+hook on (`auth system create`): an `oauthOnTokenExchange` override (for a field in the token
+response) or an `onProvision` resource (for a value fetched by a follow-up authenticated call) —
+see [system-resources.md](system-resources.md). Its postRequest hook reads the value, VALIDATES
+it (https + allowlisted host), then persists it into THIS connection's config with
+`done({ configuration: {…} })` — the write-back shipped connectors use for tokens. Do **NOT**
+`state patch` it: that edits the connector's static default at authoring time and bakes one
+org's URL into every connection. NEVER log the token.
+
+```javascript
+// postRequest on the token exchange — extract + validate instance_url, never log response_body (holds the token)
+var url = response_body && response_body.instance_url;
+var ok = false;
+if (typeof url === 'string' && url.indexOf('https://') === 0) {  // require https
+    var host = url.replace('https://', '').split('/')[0].split(':')[0].toLowerCase();
+    var allowed = ['.my.salesforce.com', '.force.com'];          // SUFFIX allowlist
+    for (var i = 0; i < allowed.length; i++) {
+        // anchor to the END of the host so 'my.salesforce.com.evil.com' can't pass
+        if (host.length > allowed[i].length &&
+            host.lastIndexOf(allowed[i]) === host.length - allowed[i].length) { ok = true; break; }
+    }
+}
+if (!ok) { done({ response_status_code: 400, response_error_message: 'invalid instance_url' }); return; }
+done({ configuration: { 'base.url': url } });               // persists to THIS connection only
+```
+Keep secrets out of logs, output, and example commands (SKILL.md Rule 9).
+
+## Hook hygiene
+
+- **No `console.log`** — Denali has no logger and stray output leaks into responses. Remove it before validating.
+- **No dead hooks** — delete 0-byte / no-op hook files; an unused `ref` is a `validate` and review smell.
+- **No time-bomb logic** — never hard-code an expiring credential or a "remove in 3 weeks" branch; fix the auth config instead.
+
+## See also
+- [element-json.md](element-json.md), [debugging.md](debugging.md), [system-resources.md](system-resources.md)

package/skills/uipath-connector-builder/references/overview.md

@@ -0,0 +1,78 @@
+# Connector Overview — the mental model
+
+A connector wraps a vendor's REST API into UiPath Studio activities and triggers.
+**Udon** (the Integration Service runtime) sits between Studio and the vendor API,
+standardising pagination, authentication, parameter mapping, and error handling.
+For the commands that build all of this, see [SKILL.md](../SKILL.md) — this file is
+depth only (no command map, no workflows).
+
+**Glossary** (used throughout these references): **Udon** = the runtime executor that
+renders the connection form, runs the auth flow, calls the vendor, and applies hooks at
+request time. **periodic** = the build/template tooling that validates and packages the
+connector on disk. **IS** = Integration Service (the UiPath product); an **IS slug** is the
+IS-side resource path `/<object>` (vs the vendor path). When a doc says "the server", read it
+as Udon at runtime. The CLI noun for an endpoint is **activity** (an element.json resource
+entry + its standard-resource file).
+
+## The 5 CRUD activities + curated + HTTP Request
+
+Every connector automatically gets 5 CRUD activities, each a dropdown listing every
+standard resource that implements that method:
+
+| Activity | Method   | Description                              |
+|----------|----------|------------------------------------------|
+| List     | GET      | Filtered list. Supports CEQL query.      |
+| Get      | GETBYID  | Retrieve a single record by ID.          |
+| Create   | POST     | Insert a new record.                     |
+| Update   | PATCH/PUT| Modify an existing record.               |
+| Delete   | DELETE   | Remove a record by ID.                   |
+
+A **curated activity** is a standalone activity shown alongside the 5 CRUDs (e.g.
+"Get Support Request"), produced from a `metadata.method.{METHOD}.curated` block in the
+SR file. `activity create` auto-curates every method by default. Field visibility
+(`requestCurated`/`responseCurated`) and `design.position`:
+[standard-resources.md](standard-resources.md). Every connector also gets a free
+**HTTP Request** activity (hide it via `hasHttpRequest` in element-metadata.json).
+
+## File layout (periodic-{elementKey}/)
+
+```text
+app/element/
+├── element.json              # Core definition: auth, configuration[], resources[], parameters[], hooks[]
+├── element-metadata.json     # Catalog entry: name, categories, capability flags, latestVersion
+├── image.svg                 # Icon
+├── hooks/*.js                # JS pre/post request transformers (extracted from element.json by scripts/build)
+├── standard-resources/*.json # Per-object metadata: fields, methods, curated, events
+└── event-hook/               # Event/polling hook definitions
+```
+
+## How the files link
+
+element.json tells Udon HOW to call the vendor (vendorPath, parameters, hooks).
+Standard resources tell Udon WHAT the data looks like (fields, types, method config).
+
+1. **resource entry → SR file**: `standardResourceName` is the canonical link
+   (`"accounts"` → `standard-resources/accounts.json`). Linkage rule + the older path-match
+   fallback: [standard-resources.md](standard-resources.md).
+2. **resource entry → hook files**: each `resources[].hooks[].ref` names a file in `hooks/`.
+3. **global hooks**: top-level `hooks[]`, same `ref` field; always run for every request.
+4. **system resources**: element.json resource entries with NO SR file and no
+   `standardResourceName` → never appear as activities. Internal only (onProvision,
+   oauthOnTokenRefresh, provisionAuthValidation). Override a built-in by matching its path.
+
+## Connector key format
+
+- Official UiPath: `uipath-{vendor}-{product}` (e.g. `uipath-salesforce-sfdc`).
+- Custom / design: `design-{org}-{slug}` — `init --organization <ORG>` derives it from the
+  org slug + `--name`. Repo name = `periodic-` + key (e.g. `periodic-design-myorg-acme`).
+
+## Scope
+
+In scope: RESTful JSON APIs, a single base URL, polling/webhook triggers, JS hooks. Out of
+scope: GraphQL, SOAP/XML, SDKs, multiple base URLs. The builder authors connectors by hand
+from the vendor's API docs; it has no OpenAPI/Postman import command.
+
+## See also
+- [element-json.md](element-json.md) — element.json internals
+- [configuration.md](configuration.md) — config + auth keys
+- [standard-resources.md](standard-resources.md) — SR / field shape