@uipath/maestro-builder-sdk 6.15.4 → 6.15.6

package/dist/bpmn/bpmn-sdk.d.ts

@@ -20,7 +20,7 @@
  * separate "tidy" step lays it out. See serialize.ts.
  */
 import type { TypeDesc } from '../core/expr.js';
-import { type ConnectorOpts } from '../core/actions.js';
+import { type ConnectorOpts, type EventFilter } from '../core/actions.js';
 import type { ConnectorDescriptor } from '../core/connectors.js';
 import type { RegistryTypeSpec, TypedContextRow, TypedInputRow, TypedOutputRow } from './typed-node.js';
 import { type DataServiceOperation } from './data-service.js';
@@ -230,6 +230,8 @@ export type BpmnNode = {
     /** The `where` scope and extra event parameters, when the operation declares any. */
     filter?: Record<string, unknown>;
     parameters?: Record<string, unknown>;
+    /** Payload conditions — see {@link ConnectorEventOpts.filters}. */
+    filters?: EventFilter[];
     outputVar?: string;
     outputs?: Record<string, string>;
     skipCondition?: string;
@@ -841,9 +843,20 @@ export interface ScriptTaskOpts extends ActivityOpts {
     /** Display name the designer shows on the task. */
     name?: string;
     /**
-     * The script body (Jint JavaScript). Each `inputs` key is available as a
-     * top-level identifier (for example `inputs: { amount: '=vars.amount' }`
-     * makes the script read `amount`, not `args.amount`).
+     * The script body (Jint JavaScript).
+     *
+     * @remarks
+     * **Read process data as `vars.<id>`, never as a bare identifier.** The runtime
+     * injects the product's fixed envelope into the script's scope — `vars` (every
+     * variable in scope, by id), `metadata`, and `iterator` inside a loop body — and
+     * nothing else. A script written `return amount * 2` with
+     * `inputs: { amount: '=vars.amount' }` passes `check`, `compile` and
+     * `uip maestro bpmn validate` and then faults on the platform with
+     * `amount is not defined`; the same script written `return vars.amount * 2`
+     * runs. `check` reports the first shape as `SCRIPT_BARE_INPUT_REF`.
+     *
+     * The serializer writes the envelope for you (see {@link ScriptTaskOpts.inputs}), so
+     * a script task that reads `vars.<id>` needs no `inputs` at all.
      */
     script: string;
     /** The script language marker. Defaults to `'JavaScript'` (Jint). */
@@ -862,7 +875,20 @@ export interface ScriptTaskOpts extends ActivityOpts {
      * `v3`, spelling an absent element as `'v1'`.
      */
     scriptVersion?: string;
-    /** `uipath:input` rows: field name → `=`-expression read into the script. */
+    /**
+     * Extra keys for the `args` input, after the envelope: key → `=`-expression.
+     *
+     * @remarks
+     * The emitted `<uipath:input name="args" target="bodyField">` is always
+     * `{"vars":"=vars","metadata":"=metadata", …inputs}` — the shape every Studio Web
+     * export carries and the only one the platform runtime honours. The runtime does
+     * NOT make an `inputs` key readable as a bare identifier (see
+     * {@link ScriptTaskOpts.script}), so for ordinary authoring leave this off and read
+     * `vars.<id>` in the script. It exists for imports — the designer writes
+     * `"iterator[0]":"=iterator[0]"` to scope a loop body — and for a key the author
+     * knows the runtime reads. `vars` and `metadata` given here override the envelope's
+     * values, which is never useful but keeps a round trip byte-faithful.
+     */
     inputs?: Record<string, string>;
     /**
      * `uipath:output` rows: variable id → `=`-expression.
@@ -891,7 +917,14 @@ export interface ScriptTaskOpts extends ActivityOpts {
     outputRows?: TypedOutputRow[];
     /**
      * The `uipath:inputSchema` body inside the mapping's `uipath:context` — a JSON
-     * Schema for the `args` the script receives. Real script tasks all carry one.
+     * Schema for the `args` the script receives.
+     *
+     * @remarks
+     * Real script tasks all carry one, so when this is absent the serializer writes the
+     * product's: `{"type":"object","properties":{"vars":{"type":"object"},"metadata":{"type":"object"}}}`,
+     * plus an untyped property per extra `inputs` key. Set it only on an import whose
+     * schema differs (the designer's carries `$schema`); `bpmn-decompile` drops the
+     * default and keeps anything else verbatim.
      */
     inputSchema?: unknown;
     /**
@@ -1103,10 +1136,57 @@ export interface HttpOpts extends ActivityOpts {
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
     /** Request headers — serialized to the node's json context field. */
     headers?: Record<string, unknown>;
-    /** Query parameters — serialized to the node's json context field. */
+    /**
+     * Query parameters — serialized to the node's json context field. In connector mode
+     * (see {@link HttpOpts.connection}) they are appended to the URL, so the URL must be
+     * a literal there.
+     */
     parameters?: Record<string, unknown>;
-    /** Request body — serialized to the node's json context field. */
+    /**
+     * Request body — serialized to the node's json context field.
+     *
+     * @remarks
+     * Leave it off for a request that has none: the row is written as `{}`, which the
+     * runtime accepts. The registry declares the default as the text `null`, and the
+     * runtime refuses that (`IntSvcUnifiedHttpRequestArgs`: `Body cannot be null`,
+     * incident 102018) — every GET this SDK emitted before flow-v2-run-12 faulted on it.
+     */
     body?: unknown;
+    /**
+     * Symbolic binding name of an Integration Service **connection** to send the
+     * request through — which switches the node to CONNECTOR mode.
+     *
+     * @remarks
+     * Without it the node is `Intsvc.UnifiedHttpRequest` in `mode="manual"`: the
+     * process owns the URL, headers and auth, and nothing on the tenant is involved.
+     * With it the node is the connector activity the v1 skill calls "connector HTTP" —
+     * `Intsvc.ActivityExecution` on the generic HTTP connector (`uipath-uipath-http`,
+     * object `http-request`), whose `body` carries the request
+     * (`{"authentication":"connector","targetConnector":…,"connection":"=bindings.…","method":"GET","url":…,"path":…,"headers":…,"body":…}`)
+     * and whose auth is the connection's. That is the shape for "call an endpoint the
+     * connector catalog has no activity for, through an existing connection" — the
+     * non-catalog HTTP fallback — and it was not expressible before: in flow-v2-run-12
+     * both fallback cards (non-catalog-http-fallback, slack-http-fallback) authored a
+     * connectionless node because this option did not exist, and the grader found
+     * `connectorKey values seen: []`.
+     *
+     * Pair it with {@link HttpOpts.folder}; both resolve as `.dataService()`'s do — an
+     * existing binding by id, else `<id>_connection` / `<id>_folder` declared for you
+     * with the symbolic name as the default, which `bindings.json` fills with the real
+     * connection and folder ids.
+     * `connectorKey` names a connection of another connector type when the endpoint
+     * belongs to one (see {@link HttpOpts.connectorKey}).
+     */
+    connection?: string;
+    /** Symbolic binding name of the connection's folder — connector mode only. */
+    folder?: string;
+    /**
+     * The connector the connection belongs to, connector mode only. Defaults to
+     * `uipath-uipath-http`, the generic HTTP connector. Set it when the connection is a
+     * specific connector's (a Slack connection calling a Slack endpoint the catalog does
+     * not expose); the body's `targetConnector` follows it.
+     */
+    connectorKey?: string;
     /**
      * EXTRA output rows: variable id → `=`-expression read against the node's own result,
      * e.g. `{ runStatus: '=Status' }`.
@@ -1136,14 +1216,48 @@ export interface HttpOpts extends ActivityOpts {
 export interface OrchestratorOpts extends ActivityOpts {
     /** Display name the designer shows on the node. */
     name?: string;
-    /** The Orchestrator process to start, by name. */
+    /**
+     * The Orchestrator process to start, by name.
+     *
+     * @remarks
+     * **How the runtime finds the process depends on the `uipath:type` version the node
+     * carries, and the SDK picks it from what you pass.** With `process` (+ `folder`) and no
+     * `releaseKey`, the node is emitted at `version="v2"`: the engine's v2 branch
+     * (`OrchestratorRpaActivities`, `ExecuteApiWorkflowArgs`, `HermesJobActivities`) reads
+     * the `name` and `folderPath` context and resolves the release itself. With
+     * `releaseKey`, the node is emitted at `version="v1"`, whose branch reads `releaseKey`
+     * and `folderKey` and ignores the name.
+     *
+     * Measured on flow-v2-run-12: a `v1` node carrying only `name`/`folderPath` — what this
+     * SDK used to emit for every job start — passed `check`, `compile` and `validate` and
+     * faulted on the cloud with `170009 Could not get value for key:ReleaseKey from context
+     * in input`; the local engine resolves by name whatever the version says, so it ran
+     * there. See docs/BPMN_EVAL_RUN12_FINDINGS.md §4 P0-3.
+     */
     process: string;
     /** Folder path the process lives in. Omit for the personal/default folder. */
     folder?: string;
     /** Input arguments — serialized as the node's `JobArguments` body. */
     input?: Record<string, unknown>;
-    /** The release key, when a binding supplies it (`=bindings.<id>`). */
+    /**
+     * Address the release by KEY instead of by name — the deployed resource's `Key` from
+     * `uip or processes list --folder-path <path> --output json`, or `=bindings.<id>` for a
+     * `process` binding whose `propertyAttribute` is `Key`. Switches the node to
+     * `version="v1"` (see {@link OrchestratorOpts.process}); a literal is turned into such
+     * a binding for you. Pair it with {@link OrchestratorOpts.folderKey} — the v1 branch
+     * does not read `folder`. For imports and for a release the tenant cannot resolve by
+     * name; ordinary authoring passes `process` and `folder` and leaves this off.
+     */
     releaseKey?: string;
+    /**
+     * The folder's `FolderKey` GUID (the same `uip or processes list` row carries it), for
+     * a node addressed by {@link OrchestratorOpts.releaseKey}. The v1 branch reads this and
+     * not `folderPath`: `Orchestrator.ExecuteApiWorkflowAsync` with a key and no
+     * `folderKey` faults with `Could not get value for key:FolderKey from context in
+     * input`, which `check` reports ahead of time as JOB_FOLDER_KEY_MISSING. Ignored when
+     * the node is addressed by name.
+     */
+    folderKey?: string;
     /**
      * EXTRA output rows: variable id → `=`-expression read against the node's own result,
      * e.g. `{ runStatus: '=Status' }`.
@@ -1330,12 +1444,37 @@ export interface ConnectorEventOpts extends ActivityOpts {
      */
     object?: string;
     /**
-     * The `where` scope narrowing the subscription, when the operation declares
-     * parameters. `Library.eventParameterFields()` is the authority on which names an
-     * operation accepts — and note that "declares none" is a real answer for some
-     * operations (HTTP Webhook scopes by the connection), not a lookup failure.
+     * The subscription's SCOPE — the operation's own event parameters, by equality
+     * (`{ parentFolderId: '<mail folder id>' }` for Outlook `email-received`).
+     * `Library.eventParameterFields()` is the authority on which names an operation
+     * accepts — and "declares none" is a real answer for some (HTTP Webhook scopes by
+     * the connection), not a lookup failure.
+     *
+     * @remarks
+     * Emitted into the node's `body` row as both `queryParams` and the leading
+     * `(k == 'v')` clauses of `filters.expression` — the one place the platform reads a
+     * subscription filter (`PO.BpmnEngine` `GetEventFilters`). A payload field that is
+     * not an event parameter (`subject`) does not belong here; it goes in
+     * {@link ConnectorEventOpts.filters}, and `check` reports it here as
+     * `EVENT_UNKNOWN_PARAM`.
      */
     filter?: Record<string, unknown>;
+    /**
+     * Conditions on the event PAYLOAD, AND-joined after the scope:
+     * `[{ field: 'subject', contains: 'TestWaitFor' }]`. The same grammar and the same
+     * lowering as the Flow builder's `waitForEvent`/`onEvent` — `contains(f,'v')`,
+     * `f=='v'`, `starts_with(f,'v')`, a date compared through `to_number(...)` — written
+     * into `body.filters.expression` behind the scope's clauses.
+     *
+     * @remarks
+     * On flow-v2-run-12 this surface did not exist, so an author who needed
+     * `contains(subject, 'TestWaitFor')` had nowhere to put it but `filter`, where it was
+     * emitted as an untargeted input no handler reads; the wait validated and matched every
+     * mail in the folder (outlook-waitfor-email 1.00 → 0.43). See {@link EventFilter} for
+     * the operator set; `check` refuses a leaf with no operator or two, and warns on a
+     * field the connector does not expose.
+     */
+    filters?: EventFilter[];
     /** Extra event parameters, for operations that declare them. */
     parameters?: Record<string, unknown>;
     /** Variable the event payload lands in. Defaults to `<id>_result`. */
@@ -2258,6 +2397,14 @@ declare abstract class ScopeBuilder {
      * @returns This builder, so calls chain.
      */
     http(id: string, opts: HttpOpts, body?: ActivityBodyFn): this;
+    /**
+     * @internal Connector-mode `.http()`: the request through an Integration Service
+     * connection, as `Intsvc.ActivityExecution` on the generic HTTP connector's
+     * `http-request` object — the shape the v1 arm wrote by hand on flow-v2-run-12
+     * (non-catalog-http-fallback) and the live run completed. The connection and folder
+     * resolve exactly as `.dataService()`'s do.
+     */
+    private connectorHttp;
     /**
      * A UiPath **Data Fabric** (Data Service) record or file operation — create,
      * update, get, query, delete a record, or download / upload / delete a record's
@@ -2358,12 +2505,17 @@ declare abstract class ScopeBuilder {
      */
     startCaseProcess(id: string, opts: OrchestratorAsyncOpts, body?: ActivityBodyFn): this;
     /**
-     * Execute an **API workflow**, fire-and-forget
-     * (`Orchestrator.ExecuteApiWorkflowAsync`).
+     * Execute an **API workflow** and wait for it (`Orchestrator.ExecuteApiWorkflowAsync`).
      *
      * @remarks
-     * The registry offers only the async form, so there is nothing to wait on: the
-     * node maps back an error and nothing else.
+     * The type's name says async and its designer label says `Start and wait for API
+     * workflow`; the label is right. The registry offers only this one type for invoking
+     * a published API workflow, it waits for completion, and the result is available to
+     * later nodes. There is no fire-and-forget variant to model.
+     *
+     * Address it by `process` + `folder` (emitted at `uipath:type version="v2"`), or by
+     * `releaseKey` + `folderKey` (v1) — see {@link OrchestratorOpts.process} for why the
+     * version matters and what a v1 node without a key does on the platform.
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which workflow, folder, and input arguments.

package/dist/bpmn/bpmn-sdk.js

@@ -980,6 +980,12 @@ class ScopeBuilder {
      */
     http(id, opts, body) {
         const { name, url, method, headers, parameters, body: requestBody, outputs, outputVar, skipCondition, retry, loop, errorMapping } = opts;
+        if (opts.connection !== undefined)
+            return this.connectorHttp(id, opts, body);
+        if (opts.folder !== undefined || opts.connectorKey !== undefined) {
+            throw new Error(`http "${id}": \`folder\` and \`connectorKey\` belong to connector mode, which \`connection\` selects — ` +
+                `pass the connection's binding name too, or drop them for a connectionless request.`);
+        }
         return this.pushActivity({
             kind: 'typed',
             id,
@@ -1006,6 +1012,89 @@ class ScopeBuilder {
             errorMapping,
         }, body);
     }
+    /**
+     * @internal Connector-mode `.http()`: the request through an Integration Service
+     * connection, as `Intsvc.ActivityExecution` on the generic HTTP connector's
+     * `http-request` object — the shape the v1 arm wrote by hand on flow-v2-run-12
+     * (non-catalog-http-fallback) and the live run completed. The connection and folder
+     * resolve exactly as `.dataService()`'s do.
+     */
+    connectorHttp(id, opts, body) {
+        const connectorKey = opts.connectorKey ?? 'uipath-uipath-http';
+        const connection = this.dataServiceBinding(id, 'connection', opts.connection, 'ConnectionId', `${connectorKey} connection`);
+        const folder = opts.folder !== undefined
+            ? this.dataServiceBinding(id, 'folder', opts.folder, 'folderKey', `${connectorKey} folder`, connection.key)
+            : undefined;
+        // The request's own URL, with `parameters` folded into its query string — the
+        // connector body has no separate parameters slot — and its path for the `path`
+        // field, which the v1 artifact carries beside the URL.
+        let url = opts.url;
+        let path;
+        if (!url.startsWith('=')) {
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                throw new Error(`http "${id}": connector mode needs an absolute URL (got ${JSON.stringify(url)}).`);
+            }
+            for (const [k, v] of Object.entries(opts.parameters ?? {}))
+                parsed.searchParams.set(k, String(v));
+            url = parsed.toString();
+            path = parsed.pathname;
+        }
+        else if (opts.parameters !== undefined) {
+            throw new Error(`http "${id}": connector mode appends \`parameters\` to the URL, so the URL cannot be an expression when they are given — ` +
+                `write them into the expression instead.`);
+        }
+        const responseVar = opts.outputVar ?? `${id}_response`;
+        return this.pushActivity({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type: 'Intsvc.ActivityExecution',
+            context: {
+                activity: 'Create',
+                connectorKey,
+                connection: connection.ref,
+                ...(folder ? { folderKey: folder.ref } : {}),
+                operation: 'Create',
+                objectName: 'http-request',
+                method: 'POST',
+                path: '/http-request',
+                activityConfigurationVersion: 'v1',
+                metadata: {},
+            },
+            inputs: {},
+            inputRows: [
+                {
+                    name: 'body',
+                    type: 'json',
+                    target: 'body',
+                    body: {
+                        authentication: 'connector',
+                        targetConnector: connectorKey,
+                        connection: connection.ref,
+                        method: opts.method ?? 'GET',
+                        url,
+                        ...(path !== undefined ? { path } : {}),
+                        headers: opts.headers ?? {},
+                        body: opts.body ?? null,
+                    },
+                },
+            ],
+            outputRows: [
+                { name: 'response', type: 'jsonSchema', source: '=response', var: responseVar },
+                { name: 'Error', type: 'jsonSchema', source: '=Error', var: `${id}_Error`, schema: errorSchema },
+            ],
+            outputs: opts.outputs,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        }, body);
+    }
     /**
      * A UiPath **Data Fabric** (Data Service) record or file operation — create,
      * update, get, query, delete a record, or download / upload / delete a record's
@@ -1137,15 +1226,37 @@ class ScopeBuilder {
     }
     /** @internal Shared body of the Orchestrator process-invocation methods. */
     orchestratorNode(id, type, opts, body) {
+        // The `uipath:type` version selects the engine's addressing branch — see
+        // OrchestratorOpts.process. By name → v2 (`name` + `folderPath`); by key → v1
+        // (`releaseKey` + `folderKey`). A literal release key becomes a `process`/`Key`
+        // binding, which is the shape the registry's `bindingInfo` for the field describes
+        // and the one `validate` wants; an `=` expression is the author's own binding.
+        const byKey = opts.releaseKey !== undefined;
+        let releaseKey = opts.releaseKey;
+        if (releaseKey !== undefined && !releaseKey.startsWith('=')) {
+            const bindingId = `${id}_releaseKey`;
+            this._bindingRegistry.declare({
+                id: bindingId,
+                name: opts.process,
+                resource: 'process',
+                propertyAttribute: 'Key',
+                resourceSubType: REGISTRY_GAPS[type]?.resourceSubType,
+                default: releaseKey,
+                resourceKey: releaseKey,
+            });
+            releaseKey = `=bindings.${bindingId}`;
+        }
         return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
             type,
+            typeVersion: byKey ? 'v1' : 'v2',
             context: this.bindRequiredContext(id, type, {
                 name: opts.process,
                 ...(opts.folder !== undefined ? { folderPath: opts.folder } : {}),
-                ...(opts.releaseKey !== undefined ? { releaseKey: opts.releaseKey } : {}),
+                ...(releaseKey !== undefined ? { releaseKey } : {}),
+                ...(byKey && opts.folderKey !== undefined ? { folderKey: opts.folderKey } : {}),
             }),
             inputs: opts.input ?? {},
             outputs: opts.outputs,
@@ -1215,12 +1326,17 @@ class ScopeBuilder {
         return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartCaseMgmtProcessAsync' : 'Orchestrator.StartCaseMgmtProcess', opts, body);
     }
     /**
-     * Execute an **API workflow**, fire-and-forget
-     * (`Orchestrator.ExecuteApiWorkflowAsync`).
+     * Execute an **API workflow** and wait for it (`Orchestrator.ExecuteApiWorkflowAsync`).
      *
      * @remarks
-     * The registry offers only the async form, so there is nothing to wait on: the
-     * node maps back an error and nothing else.
+     * The type's name says async and its designer label says `Start and wait for API
+     * workflow`; the label is right. The registry offers only this one type for invoking
+     * a published API workflow, it waits for completion, and the result is available to
+     * later nodes. There is no fire-and-forget variant to model.
+     *
+     * Address it by `process` + `folder` (emitted at `uipath:type version="v2"`), or by
+     * `releaseKey` + `folderKey` (v1) — see {@link OrchestratorOpts.process} for why the
+     * version matters and what a v1 node without a key does on the platform.
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which workflow, folder, and input arguments.
@@ -1518,6 +1634,7 @@ class ScopeBuilder {
             folder: opts.folder,
             folderPath: opts.folderPath,
             filter: opts.filter,
+            filters: opts.filters,
             parameters: opts.parameters,
             outputVar: opts.outputVar,
             outputs: opts.outputs,
@@ -1564,6 +1681,7 @@ class ScopeBuilder {
             folder: opts.folder,
             folderPath: opts.folderPath,
             filter: opts.filter,
+            filters: opts.filters,
             parameters: opts.parameters,
             outputVar: opts.outputVar,
             outputs: opts.outputs,

package/dist/bpmn/check-cli.js

@@ -11,7 +11,7 @@
  * leaving it, implied edges marked — see graph.ts.
  */
 import { existsSync } from 'node:fs';
-import { reportDiagnostics, reportResult } from '../cli-result.js';
+import { printResult, reportDiagnostics, reportResult } from '../cli-result.js';
 import { resolveBpmnFile, loadBuiltBpmn } from './load.js';
 import { check } from './check.js';
 import { graphModel, renderGraph } from './graph.js';
@@ -49,8 +49,9 @@ export async function run(argv) {
     reportDiagnostics(diags);
     if (graph) {
         // The graph goes to stdout and the diagnostics to stderr, so a reviewer can
-        // diff the printed wiring on its own.
-        process.stdout.write(renderGraph(built));
+        // diff the printed wiring on its own. Under `--json` the graph is the
+        // object's `graph` field instead, not printed a second time (#901).
+        printResult(renderGraph(built).trimEnd());
         reportResult({ graph: graphModel(built) });
     }
     for (const d of diags)

package/dist/bpmn/check.js

@@ -21,6 +21,20 @@ import { KNOWN_METHOD_SET } from './known-methods.js';
 import { EQUALS_EXPR_DIALECT, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, checkBindingLabels, } from '../core/connector-checks.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from '../core/event-checks.js';
 import { bindingRequiredFields, missingRequiredContext, missingRequiredInputs, registryType, REGISTRY_GAPS, unsatisfiableRequiredInputs, } from './typed-node.js';
+/**
+ * The job-start family — the types whose engine handler switches addressing on the
+ * `uipath:type` version: v2 reads `name`/`folderPath`, v1 reads `releaseKey`/`folderKey`.
+ */
+const JOB_START_TYPES = new Set([
+    'Orchestrator.StartJob',
+    'Orchestrator.StartAgentJob',
+    'Orchestrator.ExecuteApiWorkflowAsync',
+    'Orchestrator.StartAgenticProcess',
+    'Orchestrator.StartAgenticProcessAsync',
+    'Orchestrator.StartCaseMgmtProcess',
+    'Orchestrator.StartCaseMgmtProcessAsync',
+    'Orchestrator.BusinessRules',
+]);
 /**
  * Service types the platform expects to name a concrete Orchestrator resource.
  *
@@ -109,12 +123,13 @@ function checkConnectors(built, opts, diags) {
  * object, version, connection }` — so the adapter is naming: BPMN calls the
  * connector `key`, the event `eventName`, and the subscription scope `filter`.
  *
- * `filters` is deliberately absent. Payload filtering is a Flow surface; a BPMN
- * connector event carries none, so the `EVENT_FILTER_*` family never fires here.
- * The rules that do are the ones about the SUBSCRIPTION — whether it resolves at
- * all, whether a generic event named its object, and whether its scope names
- * parameters the operation actually declares. `skill-bpmn-outlook-waitfor-email`
- * in `flow-v2-run-8` failed on that last one.
+ * `filters` is passed through as of flow-v2-run-12: a BPMN connector event carries
+ * payload conditions in `body.filters.expression` exactly as a Flow subscription does,
+ * so the `EVENT_FILTER_*` family fires here too. The subscription rules are the rest —
+ * whether it resolves at all, whether a generic event named its object, and whether
+ * its scope names parameters the operation actually declares.
+ * `skill-bpmn-outlook-waitfor-email` in `flow-v2-run-8` failed on that last one, and
+ * in run 12 on having no `filters` surface at all.
  */
 function checkConnectorEvents(built, opts, diags) {
     for (const n of allNodes(built.nodes)) {
@@ -127,6 +142,7 @@ function checkConnectorEvents(built, opts, diags) {
             ...(n.version !== undefined ? { version: n.version } : {}),
             ...(n.object !== undefined ? { object: n.object } : {}),
             ...(n.filter !== undefined ? { where: n.filter } : {}),
+            ...(n.filters !== undefined ? { filters: n.filters } : {}),
             ...(n.connection !== undefined ? { connection: n.connection } : {}),
         };
         const at = (level) => (code, message) => {
@@ -563,6 +579,21 @@ function isRuntimeDuration(v) {
     // "validates, then no runtime can parse it" trap the timer eval card exists for.
     return RUNTIME_DURATION.test(v) && /\d/.test(v);
 }
+/** The `args` keys the platform itself writes and injects — not an author's inputs. */
+const SCRIPT_ENVELOPE_KEYS = new Set(['vars', 'metadata', 'iterator']);
+/**
+ * Whether a script body mentions `name` as a bare identifier — not after `.` (a property
+ * read such as `vars.amount`), not inside a string or comment. The body is otherwise not
+ * parsed: this is the one question about it the platform contract makes answerable.
+ */
+function readsBareIdentifier(script, name) {
+    const stripped = script
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/\/\/[^\n]*/g, ' ')
+        .replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`/g, '""');
+    const re = new RegExp(`(?<![\\w$.])${name.replace(/\$/g, '\\$')}(?![\\w$])(?!\\s*:)`);
+    return re.test(stripped);
+}
 /** Retry and loop options, checked per activity. */
 function checkActivityFields(n, diags) {
     // A script task whose body is missing or blank. The wire form of a script task IS its
@@ -584,6 +615,29 @@ function checkActivityFields(n, diags) {
                 `Pass the Jint JavaScript as \`script\` (\`.scriptTask('${n.id}', { script: 'return { … };' })\`).`,
             where: n.id,
         });
+    // A script that reads an `inputs` key as a bare identifier. The platform injects only
+    // the `args` envelope — `vars`, `metadata`, `iterator` — into the script's scope, so
+    // `amount` with `inputs: { amount: '=vars.amount' }` is a ReferenceError at runtime
+    // (`amount is not defined`, incident 300501) that `validate` cannot see and the local
+    // engine used to hide. Measured on flow-v2-run-12: 3 of 3 cloud-executed script tasks
+    // written this way faulted; 0 that read `vars.<id>` did.
+    //
+    // A warning, not an error, because a brownfield `.bpmn` whose untouched script task
+    // carries the shape must still merge — refusing it would be the SDK refusing what
+    // `validate` accepts, on a node the edit did not target.
+    if (n.kind === 'scriptTask' && n.script) {
+        const bare = Object.keys(n.inputs).filter((k) => !SCRIPT_ENVELOPE_KEYS.has(k) && /^[A-Za-z_$][\w$]*$/.test(k) && readsBareIdentifier(n.script, k));
+        if (bare.length > 0)
+            diags.push({
+                level: 'warning',
+                code: 'SCRIPT_BARE_INPUT_REF',
+                message: `Script task "${n.id}" reads ${bare.map((k) => `\`${k}\``).join(', ')} as a bare identifier, but the platform ` +
+                    `injects only \`vars\`, \`metadata\` and \`iterator\` into a script's scope — on the cloud this faults with ` +
+                    `\`${bare[0]} is not defined\` after check, compile and validate have all passed. ` +
+                    `Read the variable as \`vars.<id>\` (${bare.map((k) => `\`${n.inputs[k].replace(/^=/, '')}\``).join(', ')}) and drop the \`inputs\` entry.`,
+                where: n.id,
+            });
+    }
     if (!('retry' in n) && !('loop' in n))
         return;
     const retry = 'retry' in n ? n.retry : undefined;
@@ -931,6 +985,25 @@ inEventSubProcess = false) {
             const contextView = { ...n.context };
             for (const row of n.contextRows ?? [])
                 contextView[row.name] = row.value ?? row.body ?? '';
+            // A job start addressed by key (`uipath:type version="v1"`) with no `folderKey`. The
+            // engine's v1 branch reads `releaseKey` and `folderKey`, not `folderPath`:
+            // `Orchestrator.ExecuteApiWorkflowAsync` so written faults with `Could not get value
+            // for key:FolderKey from context in input` (v1 skill, verified live). A node by NAME
+            // is emitted at v2 and never reaches that branch — see OrchestratorOpts.process.
+            if (JOB_START_TYPES.has(n.type) &&
+                (n.typeVersion ?? 'v1') === 'v1' &&
+                contextView['releaseKey'] !== undefined &&
+                contextView['folderKey'] === undefined)
+                diags.push({
+                    level: 'warning',
+                    code: 'JOB_FOLDER_KEY_MISSING',
+                    message: `"${n.id}" (${n.type}) is addressed by releaseKey (uipath:type version="v1") but carries no folderKey; ` +
+                        `the runtime's v1 branch reads folderKey, not folderPath, and faults with ` +
+                        `\`Could not get value for key:FolderKey from context in input\`. Pass \`folderKey\` (the folder's FolderKey ` +
+                        `GUID from \`uip or processes list --folder-path <path> --output json\`), or drop \`releaseKey\` and address the ` +
+                        `process by name, which the SDK emits at version="v2".`,
+                    where: n.id,
+                });
             for (const field of bindingRequiredFields(n.type, n.spec)) {
                 const value = contextView[field.name];
                 if (typeof value === 'string' && value.startsWith('=bindings.'))

package/dist/bpmn/connector.js

@@ -1,7 +1,7 @@
 import { connectorOutputVars } from './bpmn-sdk.js';
 import { transportHttpMethod } from '../config.js';
 import { EQUALS_EXPR_DIALECT } from '../core/connector-checks.js';
-import { buildConnectorInputs } from '../core/connector-inputs.js';
+import { buildConnectorInputs, nestConnectorBody } from '../core/connector-inputs.js';
 export function createConnectorTask(ctx, n) {
     const { m } = ctx;
     if (!ctx.library)
@@ -83,7 +83,10 @@ export function createConnectorTask(ctx, n) {
         if (part.value !== undefined)
             paramRows.push(paramInput(m, part.name, 'multipart', part.value));
     }
-    const body = slots.bodyParameters ?? {};
+    // Nested, not the flat dotted map Flow emits: the BPMN runtime sends `body` as written
+    // (see `nestConnectorBody`) — a flat `fields.project.key` reached Jira as a literal
+    // property and drew a 400 on flow-v2-run-12.
+    const body = nestConnectorBody(slots.bodyParameters ?? {});
     // ── outputs — response schema + standard Error ──
     const responseSchema = rc.entry.outputSchema
         ? schemaFromFields(rc.entry.outputSchema.fields ?? [])

package/dist/bpmn/data-service.d.ts

@@ -70,9 +70,17 @@ export type DataServiceOperation = {
     start?: number;
     /** Page size. Defaults to `100`. */
     limit?: number;
-    /** Field to sort by. */
+    /**
+     * Field to sort by. Emitted as the body's `_sortFieldName` — the name the curated
+     * operation's `RequestFields` declare and the only place the connector reads it; a
+     * `sortBy` query parameter is ignored and the records come back in default order.
+     */
     sortBy?: string;
-    /** Sort direction, when `sortBy` is set. */
+    /**
+     * Sort direction, when `sortBy` is set. Emitted as the `isAscending` query parameter.
+     * Set it explicitly: omitted, the query sorts ascending whatever the connector's
+     * default says.
+     */
     ascending?: boolean;
     /** How many levels of related records to expand into each result. */
     expansionLevel?: number;