@uipath/maestro-builder-sdk 6.46.3 → 6.46.5

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

@@ -491,6 +491,16 @@ export interface ActionField {
         label: string;
     }>;
 }
+/** The Action App an action task opens. */
+export interface ActionAppRef {
+    /** The app's deployment title, e.g. `SimpleApprovalApp`. */
+    name: string;
+    /**
+     * The app's deployment folder, e.g. `Shared/Approvals`, or `'solution_folder'`
+     * for an app built in this solution.
+     */
+    folder: string;
+}
 export interface ActionSpecData {
     title?: string;
     priority?: 'Low' | 'Medium' | 'High' | 'Critical';
@@ -500,7 +510,11 @@ export interface ActionSpecData {
     };
     /** Action Center labels (persisted as a single `data.labels` string). */
     labels?: string;
-    /** The Action Center action-app / catalog this task instantiates. */
+    /**
+     * An Action Center task catalog, resolved by name in the app's deployment
+     * folder. Not the app: a catalog only groups tasks. Omit it unless the catalog
+     * is known to exist there.
+     */
     actionCatalogName?: string;
     /** Read-only context fields the assignee sees (`data.inputs[]`). */
     inputs?: ActionField[];
@@ -544,6 +558,7 @@ export interface BuiltTask {
     /** Task key + display name (also the handle used by `selected-tasks-completed`). */
     name: string;
     kind: TaskKind;
+    /** The published resource the task binds: a reference task's process, agent, … or an action task's Action App. */
     ref?: TaskRef;
     /** business-rule task: the rule's decision-keyed result schema, when known. */
     businessRule?: BusinessRuleSpecData;
@@ -886,9 +901,13 @@ declare class TaskBuilder {
      * An Action Center human task. `recipient` may be an email (→ Type 2) or
      * `{ type, value }`. `inputs`/`outputs` declare the task's form fields — inputs
      * are read-only context the assignee sees, outputs are what they fill in.
-     * `labels` and `actionCatalogName` tag the task and name its action app.
+     * `app` names the Action App the task opens (`{ name, folder }`); compile
+     * binds it through an `app` name/folderPath pair keyed `<folder>.<name>`.
+     * `labels` tag the task. `actionCatalogName` names a task catalog, which is
+     * resolved in the app's deployment folder; it is not the app, and a name that
+     * folder does not hold fails the task when it opens.
      *
-     * @param spec - The human task: its `title`, `priority`, `recipient`, and the `inputs` / `outputs` its form shows and collects.
+     * @param spec - The human task: its `title`, `priority`, `recipient`, the Action `app`, and the `inputs` / `outputs` its form shows and collects.
      * @returns This builder, so calls chain.
      */
     action(spec?: {
@@ -899,6 +918,7 @@ declare class TaskBuilder {
             value: string;
         };
         labels?: string;
+        app?: ActionAppRef;
         actionCatalogName?: string;
         inputs?: ActionField[];
         outputs?: ActionField[];

package/dist/case/case-sdk.js

@@ -332,13 +332,22 @@ class TaskBuilder {
      * An Action Center human task. `recipient` may be an email (→ Type 2) or
      * `{ type, value }`. `inputs`/`outputs` declare the task's form fields — inputs
      * are read-only context the assignee sees, outputs are what they fill in.
-     * `labels` and `actionCatalogName` tag the task and name its action app.
+     * `app` names the Action App the task opens (`{ name, folder }`); compile
+     * binds it through an `app` name/folderPath pair keyed `<folder>.<name>`.
+     * `labels` tag the task. `actionCatalogName` names a task catalog, which is
+     * resolved in the app's deployment folder; it is not the app, and a name that
+     * folder does not hold fails the task when it opens.
      *
-     * @param spec - The human task: its `title`, `priority`, `recipient`, and the `inputs` / `outputs` its form shows and collects.
+     * @param spec - The human task: its `title`, `priority`, `recipient`, the Action `app`, and the `inputs` / `outputs` its form shows and collects.
      * @returns This builder, so calls chain.
      */
     action(spec = {}) {
         this.setKind('action');
+        // The app is the task's resource, carried as its `ref` like every other
+        // bound resource, so the resource-ref rules in check and the binding pair
+        // in serialize both see it.
+        if (spec.app)
+            this._ref = { name: spec.app.name, folderPath: spec.app.folder };
         const recipient = typeof spec.recipient === 'string' ? { type: 2, value: spec.recipient } : spec.recipient;
         this._action = {
             title: spec.title,

package/dist/case/check.js

@@ -5,6 +5,7 @@ import { caseJsonPreservation, caseJsonPreservationErrors } from './preserve.js'
 import { EQUALS_EXPR_DIALECT, checkBindingLabels, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, } from '../core/connector-checks.js';
 import { checkEventResolution } from '../core/event-checks.js';
 import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT } from './external.js';
+import { isResourceLabelRefusal, resolveResourceRef } from './resource-identity.js';
 const TYPE_NAMES = new Set(Object.values(types));
 // audit-case-coverage: rule-slot table start
 // This runtime table must equal the committed matrix's rejected cells. The audit
@@ -257,7 +258,7 @@ export function check(built, opts = {}) {
     // positive that blocks emit (this gate runs before serialization), so it must be
     // re-derived from the serializer rather than from remembered probe results.
     for (const stage of built.stages) {
-        checkStage(stage, diags, refStage, refPlacement);
+        checkStage(stage, diags, refStage, refPlacement, opts.bindings);
         stage.slaRules.forEach((s, i) => checkSla(s, `stage "${stage.label}" SLA #${i + 1}`, diags));
     }
     built.slaRules.forEach((s, i) => checkSla(s, `case SLA #${i + 1}`, diags));
@@ -394,7 +395,7 @@ function isNilOrEmpty(value) {
         return Object.keys(value).length === 0;
     return false;
 }
-function checkStage(stage, diags, refStage, refPlacement) {
+function checkStage(stage, diags, refStage, refPlacement, bindings) {
     const where = `stage "${stage.label}"`;
     if (stage.exception && stage.required !== false)
         diags.push({
@@ -484,16 +485,15 @@ function checkStage(stage, diags, refStage, refPlacement) {
                 where: t.name,
             });
         // The builder binds a resource task itself: it mints the name/folderPath
-        // binding pair from the literal name and folder. A `=bindings.<id>` string
-        // passed as either becomes part of the binding key, which then names no
-        // resource (`=bindings.f.=bindings.n`) and dangles at deploy.
-        if (t.ref && [t.ref.name, t.ref.folderPath].some((v) => v.trim().startsWith('=bindings.')))
-            diags.push({
-                level: 'error',
-                code: 'RESOURCE_REF_IS_BINDING',
-                message: `Task "${t.name}" passes a "=bindings.<id>" reference as its resource name or folder. Pass the resource's own name and its folder, e.g. .agent('Contract Analysis', { folder: 'Shared/Legal' }); compile writes the name/folderPath binding pair keyed '<folder>.<name>' and points the task at it.`,
-                where: t.name,
-            });
+        // binding pair from the literal name and folder. A `=bindings.<label>` name
+        // or folder is read through bindings.json first, the way a connector's
+        // `connection:` label is; one bindings.json cannot answer is refused with the
+        // same text serialize throws (`resolveResourceRef`).
+        if (t.ref) {
+            const resolved = resolveResourceRef(t.ref, bindings, `Task "${t.name}"`);
+            if (isResourceLabelRefusal(resolved))
+                diags.push({ level: 'error', code: resolved.code, message: resolved.message, where: t.name });
+        }
         if (t.kind === 'business-rule') {
             if (!t.ref || !t.ref.name.trim() || !t.ref.folderPath.trim())
                 diags.push({

package/dist/case/decompile.js

@@ -644,6 +644,7 @@ function emitTaskKind(task, refs, library) {
             ['priority', data.priority && data.priority !== 'Medium' ? tsLiteral(data.priority) : undefined],
             ['recipient', recipient],
             ['labels', data.labels !== undefined ? tsLiteral(data.labels) : undefined],
+            ['app', actionApp(data, refs, task)],
             ['actionCatalogName', data.actionCatalogName !== undefined ? tsLiteral(data.actionCatalogName) : undefined],
             ['inputs', actionFields(data.inputs)],
             ['outputs', actionFields(data.outputs)],
@@ -679,6 +680,21 @@ function emitTaskKind(task, refs, library) {
     });
     return `.__UNRESOLVED_TASK_KIND__(${tsLiteral(kind)}, ${tsLiteral(data)})`;
 }
+/**
+ * The `app: { name, folder }` of an action task bound to its Action App, or
+ * undefined for one with no app. Dropping it lost the app binding on every
+ * round trip of a Studio Web plan (#1240).
+ */
+function actionApp(data, refs, task) {
+    if (data.name === undefined && data.folderPath === undefined)
+        return undefined;
+    const owner = `action task "${task.displayName ?? task.id ?? '?'}"`;
+    const name = bindingDefault(data.name, refs, owner, 'name');
+    const folder = bindingFolder(data.folderPath, refs, owner);
+    if (typeof name !== 'string' || !name || typeof folder !== 'string')
+        throw new Error(`${owner} names its app by neither a binding nor a literal name and folder.`);
+    return opts([['name', tsLiteral(name)], ['folder', tsLiteral(folder)]]);
+}
 /** A business-rule task `.businessRule()` can rebuild: v3 only. */
 function isAuthorableBusinessRule(task) {
     return task.type === 'business-rule' && task.data?.version === 'v3';

package/dist/case/resource-identity.d.ts

@@ -23,6 +23,7 @@
  * `case-validate-service.ts` exempts that prefix from its key/folder agreement
  * check.
  */
+import { type BindingsView } from '../core/binding-messages.js';
 export declare const SOLUTION_FOLDER = "solution_folder";
 export interface ResourceIdentity {
     /** The `resourceKey` both rows of the name/folderPath binding pair carry. */
@@ -42,3 +43,47 @@ export interface ResourceIdentity {
 export declare function resourceIdentity(name: string, folder: string): ResourceIdentity;
 /** True for the key of a resource built inside the same solution. */
 export declare function isInSolutionKey(resourceKey: string): boolean;
+/**
+ * Why a resource task's `=bindings.<label>` name or folder cannot be resolved.
+ *
+ * - `RESOURCE_REF_IS_BINDING`: there is no bindings.json (or it declares nothing),
+ *   so the label names nothing compile can read.
+ * - `RESOURCE_BINDING_UNDECLARED`: bindings.json does not declare the label, or
+ *   declares it with no value.
+ */
+export interface ResourceLabelRefusal {
+    code: 'RESOURCE_REF_IS_BINDING' | 'RESOURCE_BINDING_UNDECLARED';
+    message: string;
+}
+/**
+ * The literal name and folder of a resource task, with any `=bindings.<label>`
+ * resolved through the project's bindings.json, the way a connector task's
+ * `connection:` label is.
+ *
+ *   bindings.json  { "name": "agentName",   "default": "Agent" }
+ *                  { "name": "agentFolder", "default": "Shared/Golden" }
+ *   .agent('=bindings.agentName', { folder: '=bindings.agentFolder' })
+ *     -> { name: 'Agent', folderPath: 'Shared/Golden' }
+ *
+ * The task then compiles exactly as `.agent('Agent', { folder: 'Shared/Golden' })`
+ * does: compile mints the name/folderPath binding pair keyed `<folder>.<name>`.
+ * Passing the label straight through instead keyed the pair
+ * `=bindings.f.=bindings.n`, which names no resource and dangles at deploy.
+ *
+ * @param ref - The authored name and folder.
+ * @param bindings - The project's bindings.json, if any.
+ * @param where - The task, as a diagnostic names it.
+ * @returns The literal pair, or the refusal.
+ */
+export declare function resolveResourceRef(ref: {
+    name: string;
+    folderPath: string;
+}, bindings: BindingsView | undefined, where: string): {
+    name: string;
+    folderPath: string;
+} | ResourceLabelRefusal;
+/** True when {@link resolveResourceRef} refused. */
+export declare function isResourceLabelRefusal(r: {
+    name: string;
+    folderPath: string;
+} | ResourceLabelRefusal): r is ResourceLabelRefusal;

package/dist/case/resource-identity.js

@@ -23,6 +23,7 @@
  * `case-validate-service.ts` exempts that prefix from its key/folder agreement
  * check.
  */
+import { GUID_RE } from '../core/binding-messages.js';
 export const SOLUTION_FOLDER = 'solution_folder';
 const SOLUTION_FOLDER_KEY_PREFIX = `${SOLUTION_FOLDER}.`;
 /**
@@ -43,3 +44,72 @@ export function resourceIdentity(name, folder) {
 export function isInSolutionKey(resourceKey) {
     return resourceKey.startsWith(SOLUTION_FOLDER_KEY_PREFIX);
 }
+/** How a resource task's name or folder spells a bindings.json label. */
+const BINDING_LABEL_PREFIX = '=bindings.';
+/** The literal value bindings.json declares for `label`, or `undefined`. */
+function declaredValue(bindings, label) {
+    const entry = bindings?.entry?.(label);
+    // `default` is the value a person reads (the resource's name, the folder
+    // path); `resourceKey` can be the resource's GUID. A map-form bindings.json
+    // puts the value in both. A GUID-shaped `resourceKey` is never a name or a
+    // folder: taking it would key the pair `<folder>.<guid>`, which dangles at
+    // deploy, so the label falls through to RESOURCE_BINDING_UNDECLARED.
+    const fallback = typeof entry?.resourceKey === 'string' && GUID_RE.test(entry.resourceKey.trim()) ? undefined : entry?.resourceKey;
+    const value = entry ? (entry.default ?? fallback) : bindings?.resolve(label);
+    return typeof value === 'string' && value.trim() && !value.trim().startsWith(BINDING_LABEL_PREFIX)
+        ? value
+        : undefined;
+}
+/**
+ * The literal name and folder of a resource task, with any `=bindings.<label>`
+ * resolved through the project's bindings.json, the way a connector task's
+ * `connection:` label is.
+ *
+ *   bindings.json  { "name": "agentName",   "default": "Agent" }
+ *                  { "name": "agentFolder", "default": "Shared/Golden" }
+ *   .agent('=bindings.agentName', { folder: '=bindings.agentFolder' })
+ *     -> { name: 'Agent', folderPath: 'Shared/Golden' }
+ *
+ * The task then compiles exactly as `.agent('Agent', { folder: 'Shared/Golden' })`
+ * does: compile mints the name/folderPath binding pair keyed `<folder>.<name>`.
+ * Passing the label straight through instead keyed the pair
+ * `=bindings.f.=bindings.n`, which names no resource and dangles at deploy.
+ *
+ * @param ref - The authored name and folder.
+ * @param bindings - The project's bindings.json, if any.
+ * @param where - The task, as a diagnostic names it.
+ * @returns The literal pair, or the refusal.
+ */
+export function resolveResourceRef(ref, bindings, where) {
+    const out = { name: ref.name, folderPath: ref.folderPath };
+    for (const attribute of ['name', 'folderPath']) {
+        const authored = ref[attribute].trim();
+        if (!authored.startsWith(BINDING_LABEL_PREFIX))
+            continue;
+        const label = authored.slice(BINDING_LABEL_PREFIX.length);
+        const what = attribute === 'name' ? 'resource name' : 'folder';
+        const literal = `e.g. .agent('Contract Analysis', { folder: 'Shared/Legal' })`;
+        const declared = bindings?.declared?.() ?? [];
+        if (declared.length === 0)
+            return {
+                code: 'RESOURCE_REF_IS_BINDING',
+                message: `${where} passes "${authored}" as its ${what}, and there is no bindings.json declaring "${label}". `
+                    + `Declare it in bindings.json ({ "name": "${label}", "default": "<the ${what}>" }), or pass the ${what} itself, ${literal}; `
+                    + `compile writes the name/folderPath binding pair keyed '<folder>.<name>' and points the task at it.`,
+            };
+        const value = declaredValue(bindings, label);
+        if (value === undefined)
+            return {
+                code: 'RESOURCE_BINDING_UNDECLARED',
+                message: `${where} passes "${authored}" as its ${what}, but bindings.json does not declare "${label}" with a value `
+                    + `(it declares: ${declared.join(', ')}). Use one of those labels, add "${label}" with its ${what} as "default", `
+                    + `or pass the ${what} itself, ${literal}.`,
+            };
+        out[attribute] = value;
+    }
+    return out;
+}
+/** True when {@link resolveResourceRef} refused. */
+export function isResourceLabelRefusal(r) {
+    return 'code' in r;
+}

package/dist/case/serialize.js

@@ -18,7 +18,7 @@ import { resolveEventWhere } from '../core/lookups.js';
 import { resolveCaseSubscription } from './subscription.js';
 import { externalDescriptorRefusal } from './external.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
-import { resourceIdentity } from './resource-identity.js';
+import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './resource-identity.js';
 import { ownEntry } from '../core/own-entry.js';
 import { resolveSchemaVersion } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors, } from './preserve.js';
@@ -914,7 +914,7 @@ function taskData(task, resolver, taskId, stageId, ids) {
             // never literals: `validate` refuses a literal (CASE_MGMT_RESOURCE_TASK_
             // LITERAL_BINDING), and deploy re-targets a resource only through its
             // binding (#1240).
-            const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids);
+            const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids, task.name);
             const data = { name: nameRef, folderPath: folderRef };
             const elementId = `${stageId}-${taskId}`;
             if (task.inputs?.length)
@@ -937,6 +937,13 @@ function taskData(task, resolver, taskId, stageId, ids) {
             }
             if (a.labels)
                 data.labels = a.labels;
+            // The Action App the task opens, bound like any resource: an `app`
+            // name/folderPath pair keyed `<deployment folder>.<app>` (#1240).
+            if (task.ref) {
+                const { nameRef, folderRef } = referenceBindings('action', task.ref, resolver, ids, task.name);
+                data.name = nameRef;
+                data.folderPath = folderRef;
+            }
             if (a.actionCatalogName)
                 data.actionCatalogName = a.actionCatalogName;
             // HITL form fields: inputs are read-only context the assignee sees, outputs
@@ -1268,11 +1275,20 @@ function resourceBinding(resolver, ids, binding, resourceKey, propertyAttribute,
     });
     return id;
 }
+/** The binding `resource` an action task's Action App is bound by (no subtype). */
+const ACTION_APP_RESOURCE = 'app';
 /** The `=bindings.<id>` name/folderPath references of a published-resource task. */
-function referenceBindings(kind, ref, resolver, ids) {
+function referenceBindings(kind, authored, resolver, ids, taskName) {
+    // A `=bindings.<label>` name or folder reads through bindings.json to its
+    // literal value, so the task binds exactly as the literal form does.
+    const ref = resolveResourceRef(authored, resolver.bindings, `Task "${taskName}"`);
+    if (isResourceLabelRefusal(ref))
+        throw new Error(`[${ref.code}] ${ref.message}`);
     const binding = kind === 'business-rule'
         ? { resource: BUSINESS_RULE_RESOURCE }
-        : ownEntry(REFERENCE_BINDING, kind);
+        : kind === 'action'
+            ? { resource: ACTION_APP_RESOURCE }
+            : ownEntry(REFERENCE_BINDING, kind);
     if (!binding)
         throw new Error(`task kind "${kind}" is not a published-resource task.`);
     // An in-solution resource (`folder: 'solution_folder'`) keeps the sentinel
@@ -1297,7 +1313,7 @@ function referenceBindings(kind, ref, resolver, ids) {
  *   (`=<Decision>.<column>`).
  */
 function businessRuleTaskData(task, resolver, elementId, ids) {
-    const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids);
+    const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids, task.name);
     const ownRow = (name, source, seed, extra = {}) => {
         const slot = ids.make('v', 8, `${elementId}:${seed}`);
         return { name, type: 'jsonSchema', id: slot, var: slot, value: slot, source, target: `=${slot}`, elementId, ...extra };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.46.3",
+  "version": "6.46.5",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "b763fc50a8d6430ce9a6e3e3e6b79b7c8645a4b1"
+  "gitref": "0edb50d70d9787a64a6c66ce37b5e1eed45d2a0d"
 }