@uipath/maestro-builder-sdk 6.55.0 → 6.56.0

package/dist/bpmn/human-task-form.js

@@ -0,0 +1,321 @@
+import { FORM_FIELD_TYPES, formFieldJsonSchema, formFieldOptionsProblem, formFieldOptionsWhy, formFieldSettingProblems, formFieldSettingsWire, formFieldTypeHint, liftFormFieldSettings, validFormFieldTypesText, wireFormFieldType, } from '../core/form-field-type.js';
+import { outcomeIdOf } from '../core/hitl-routing.js';
+import { schemaId as stableSchemaId } from '../core/stable-id.js';
+/** The `uipath:type` version both the converter and Studio Web write for `Actions.HITL`. */
+const QUICK_TYPE_VERSION = 'v2';
+/** The response row the app variant derives from the registry; the quick form keeps it. */
+const RESPONSE_ROW = 'Process response';
+const DRAFT_07 = 'http://json-schema.org/draft-07/schema#';
+/**
+ * A field id has to be a plain, unreserved identifier, for two reasons.
+ *
+ * An answer is read back as the bare expression `=<id>`, and `=review-note` is a
+ * subtraction. And the local evaluator makes every key of the response a PARAMETER of
+ * one `new Function(...keys, body)`, so a single key that cannot be a parameter name —
+ * `review-note`, `default`, `true` — throws for every output row of the task, the
+ * outcome mapping included, and `applyOutputs` writes `undefined` for all of them.
+ */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** Words a parameter cannot be named: ECMAScript's reserved words, strict-mode ones, and the literal-like globals. */
+const RESERVED_WORDS = new Set([
+    'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else',
+    'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
+    'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with',
+    'yield', 'let', 'static', 'implements', 'interface', 'package', 'private', 'protected', 'public',
+    'arguments', 'eval', 'undefined', 'NaN', 'Infinity',
+]);
+/** The response's own key for the outcome picked — an answer cannot claim it. */
+const OUTCOME_KEY = 'Action';
+/** Whether a field is shown to the reviewer (its value is sent). */
+function isShown(f) {
+    return f.direction === 'input' || f.direction === 'inOut';
+}
+/** Whether a field comes back as an answer. */
+function isAnswer(f) {
+    return f.direction === 'output' || f.direction === 'inOut';
+}
+/**
+ * A shown value as the form schema's `binding`: the variable PATH the designer reads
+ * (`vars.amount`), when the expression is one; otherwise the expression as written.
+ */
+function bindingOf(value) {
+    const path = /^=(?:js:)?(vars\.[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)$/.exec(value);
+    return path ? path[1] : value;
+}
+/** An output row's type for a field: its JSON Schema type, with structures as `json`. */
+function rowTypeOf(type) {
+    const json = formFieldJsonSchema(type)?.type ?? 'string';
+    return json === 'object' || json === 'array' ? 'json' : json;
+}
+/**
+ * Refuse a form the engine could not render, at the call that wrote it.
+ *
+ * @throws Error naming the task and what is wrong.
+ */
+function validate(id, input) {
+    const { form } = input;
+    const where = `humanTask "${id}"`;
+    if (!Array.isArray(form.fields))
+        throw new Error(`${where}: form.fields must be an array.`);
+    if (!Array.isArray(form.outcomes) || form.outcomes.length === 0) {
+        throw new Error(`${where}: the form needs at least one outcome, e.g. outcomes: ['Approve', 'Reject'].`);
+    }
+    const ids = new Set();
+    for (const f of form.fields) {
+        if (typeof f.id !== 'string' || f.id === '')
+            throw new Error(`${where}: every form field needs an id.`);
+        if (ids.has(f.id))
+            throw new Error(`${where}: form field id "${f.id}" is used twice.`);
+        ids.add(f.id);
+        if (f.id === OUTCOME_KEY) {
+            throw new Error(`${where}: form field "${OUTCOME_KEY}" collides with the response's own "${OUTCOME_KEY}" — the outcome picked. Rename it, e.g. id: '${OUTCOME_KEY}Value'.`);
+        }
+        if (!IDENTIFIER.test(f.id)) {
+            throw new Error(`${where}: form field "${f.id}" (${f.direction}) is not a name the runtime can read back as =${f.id}. ` +
+                `Use an identifier (letters, digits, _ or $), e.g. id: '${f.id.replace(/\W+(\w)?/g, (_m, c) => (c ?? '').toUpperCase())}'.`);
+        }
+        if (RESERVED_WORDS.has(f.id)) {
+            throw new Error(`${where}: form field "${f.id}" is a reserved word, which the runtime cannot bind as a name — it would lose every answer and the outcome. Rename it, e.g. id: '${f.id}Value'.`);
+        }
+        // The SDK's own spellings only. The product also resolves platform aliases such as
+        // `System.String`, but those are not `FormFieldType`s: accepting one here would let a
+        // decompile lift write source that does not type-check, so such an import stays verbatim.
+        if (!FORM_FIELD_TYPES.includes(String(f.type))) {
+            throw new Error(`${where}: form field "${f.id}" has type "${String(f.type)}". Valid: ${validFormFieldTypesText()}. ${formFieldTypeHint(f.type)}`.trimEnd());
+        }
+        // The checks Flow's form checker reports as errors: a picker the reviewer cannot
+        // pick from, and a setting the platform's schema refuses. (Options on a field that
+        // renders no picker is a warning there, and is not refused here.)
+        if (formFieldOptionsProblem(f) === 'missing') {
+            throw new Error(`${where}: form field "${f.id}" ${formFieldOptionsWhy('missing', f.type)}. Add options: [{ id: 'o1', value: 'a', label: 'A' }, …].`);
+        }
+        const settings = formFieldSettingProblems(f);
+        if (settings.length)
+            throw new Error(`${where}: form field "${f.id}" sets ${settings.join('; ')}.`);
+        if (isShown(f) && (typeof f.value !== 'string' || !f.value.startsWith('='))) {
+            throw new Error(`${where}: form field "${f.id}" (${f.direction}) needs a value — a =-expression such as '=vars.${f.id}' — or the form shows it empty.`);
+        }
+    }
+    // One variable, one writer. Two answers landing in one variable, or an `outputs`
+    // mapping onto an answer's variable, both evaluate and the LAST row wins, so an answer
+    // is lost with no signal (`outputs: { decision: '=Action' }` beside a field named
+    // `decision` replaces the reviewer's text with the outcome name). The product's own
+    // converter never writes that shape (`applyHitlExtension` dedupes with `seenVars`).
+    const writers = new Map();
+    const claim = (variable, writer) => {
+        const first = writers.get(variable);
+        if (first !== undefined) {
+            throw new Error(`${where}: ${first} and ${writer} both write vars.${variable}, so one would overwrite the other. Give one a different variable.`);
+        }
+        writers.set(variable, writer);
+    };
+    claim(input.outputVar ?? `${id}_processResponse`, 'the task response (outputVar)');
+    for (const f of form.fields)
+        if (isAnswer(f))
+            claim(f.variable ?? f.id, `form field "${f.id}"`);
+    for (const v of Object.keys(input.outputs ?? {}))
+        claim(v, `outputs.${v}`);
+    const names = new Set();
+    const outcomeIds = new Map();
+    form.outcomes.forEach((o, i) => {
+        const name = typeof o === 'string' ? o : o?.name;
+        if (typeof name !== 'string' || name.trim() === '')
+            throw new Error(`${where}: every outcome needs a name.`);
+        if (names.has(name))
+            throw new Error(`${where}: outcome "${name}" is listed twice.`);
+        names.add(name);
+        // The schema's outcome ids must be unique too, and two names can reach one: an
+        // explicit `id` repeated, or `Needs review` and `Needs-review`, which both derive
+        // `needs-review`.
+        const outcomeId = outcomeIdOf(o, i);
+        const clash = outcomeIds.get(outcomeId);
+        if (clash !== undefined) {
+            throw new Error(`${where}: outcomes "${clash}" and "${name}" both have the id "${outcomeId}". Give one an explicit, different id: { name: '${name}', id: '…' }.`);
+        }
+        outcomeIds.set(outcomeId, name);
+    });
+}
+/**
+ * The rows a quick human task is written as.
+ *
+ * @param id - The task's element id.
+ * @param processId - The process id, which the default `hitlSchemaId` is derived from.
+ * @param input - The form and the task options.
+ * @returns The context, payload and output rows, the input schema and the type version.
+ * @throws Error when the form is malformed — see {@link validate}.
+ */
+export function quickHumanTaskRows(id, processId, input) {
+    const { form } = input;
+    validate(id, input);
+    const schemaId = form.schemaId ?? stableSchemaId(processId, id);
+    const fields = form.fields.map((f) => {
+        const row = { id: f.id, label: f.label ?? f.id, type: wireFormFieldType(f.type), direction: f.direction };
+        if (isShown(f))
+            row.binding = bindingOf(f.value);
+        if (isAnswer(f)) {
+            row.variable = `vars.${f.variable ?? f.id}`;
+            if (typeof f.required === 'boolean')
+                row.required = f.required;
+        }
+        return { ...row, ...formFieldSettingsWire(f) };
+    });
+    const outcomes = form.outcomes.map((o, i) => ({
+        id: outcomeIdOf(o, i),
+        name: typeof o === 'string' ? o : o.name,
+        type: 'string',
+        isPrimary: i === 0,
+        action: 'Continue',
+    }));
+    const shown = form.fields.filter(isShown);
+    const bindings = Object.fromEntries(shown.map((f) => [f.id, bindingOf(f.value)]));
+    const contextRows = [
+        { name: 'hitlType', type: 'string', value: 'quick' },
+        { name: '__hitlFormSchema', type: 'json', body: { id: schemaId, fields, outcomes } },
+        { name: 'hitlSchemaId', type: 'string', value: schemaId },
+        ...(shown.length ? [{ name: '__hitlInputBindings', type: 'json', body: bindings }] : []),
+        { name: 'taskTitle', type: 'string', value: input.title ?? input.name ?? id },
+        ...(input.priority !== undefined ? [{ name: 'priority', type: 'string', value: input.priority }] : []),
+        ...(input.labels !== undefined ? [{ name: 'labels', type: 'string', value: input.labels }] : []),
+    ];
+    // What the form shows, as JSON Schema — the converter's `inputSchema`.
+    const properties = {};
+    const required = [];
+    for (const f of shown) {
+        properties[f.id] = { ...formFieldJsonSchema(f.type), title: f.label ?? f.id };
+        if (f.direction === 'inOut' && f.required === true)
+            required.push(f.id);
+    }
+    const inputSchema = { $schema: DRAFT_07, type: 'object', properties, ...(required.length ? { required } : {}) };
+    const inputRows = [
+        { name: 'HitlTaskArguments', type: 'json', target: 'bodyField', body: Object.fromEntries(shown.map((f) => [f.id, f.value])) },
+    ];
+    const fieldById = new Map(form.fields.map((f) => [f.id, f]));
+    const outputRows = [
+        { name: RESPONSE_ROW, type: 'Actions.HITL', var: input.outputVar ?? `${id}_processResponse` },
+        ...form.fields.filter(isAnswer).map((f) => {
+            const v = f.variable ?? f.id;
+            return { name: v, type: rowTypeOf(f.type), source: `=${f.id}`, var: v, custom: true };
+        }),
+    ];
+    const mappedOutputRows = Object.entries(input.outputs ?? {}).map(([v, source]) => {
+        // The fallback type: an answer's field type for `=<fieldId>`, `string` otherwise
+        // (`=Action`, the outcome NAME, is a string). A declared variable overrides it.
+        const field = /^=([A-Za-z_$][\w$]*)$/.exec(source)?.[1];
+        const f = field === undefined ? undefined : fieldById.get(field);
+        return { name: v, type: f ? rowTypeOf(f.type) : 'string', source, var: v };
+    });
+    return { typeVersion: QUICK_TYPE_VERSION, contextRows, inputSchema, inputRows, outputRows, mappedOutputRows };
+}
+/**
+ * Rows as comparable text: each row's own keys sorted (a row read from XML and a row
+ * built here need not list them in the same order), but every body as its exact TEXT.
+ * A body that parses to the same value with other whitespace or key order would compile
+ * back to different bytes, so it must not count as a match.
+ */
+function rowsText(rows) {
+    return JSON.stringify(rows.map((r) => {
+        const entries = Object.entries(r)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => [k, k === 'body' || k === 'schema' ? textOf(v) : v]);
+        return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
+    }));
+}
+/** A body as the text it is written as — a value is JSON-stringified, as the serializer does. */
+function textOf(body) {
+    return typeof body === 'string' ? body : JSON.stringify(body);
+}
+/** Parse a json body read from XML, or `undefined` when it is not JSON. */
+function bodyValue(body) {
+    if (typeof body !== 'string')
+        return body;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read a quick task back as `.humanTask({ form })` options — or `undefined` when its
+ * rows are anything but what those options compile to.
+ *
+ * Best effort by construction, and safe because of the last step: the lifted options
+ * are run through {@link quickHumanTaskRows} and the result must equal the node's rows,
+ * order and all. A Studio Web task (sidecar schema, `_schemaFileId`, no response row)
+ * fails that and stays the verbatim `.activity()` it was.
+ *
+ * @param node - The node's rows, as decompile read them.
+ * @param processId - The id the decompiled `bpmn(…)` call will carry.
+ * @param authoredVarType - The wire type of each variable the decompiled source will
+ * DECLARE with `.var()` — what the serializer types a mapped `outputs` row from on the
+ * way back. A variable decompile folds away is not one: its row is re-typed from the
+ * fallback, so it has to already carry that type to match.
+ * @returns The options, or `undefined` to keep the node verbatim.
+ */
+export function liftQuickHumanTask(node, processId, authoredVarType = () => undefined) {
+    const ctx = new Map(node.contextRows.map((r) => [r.name, r]));
+    if (ctx.get('hitlType')?.value !== 'quick')
+        return undefined;
+    const schema = bodyValue(ctx.get('__hitlFormSchema')?.body);
+    if (!schema || !Array.isArray(schema.fields) || !Array.isArray(schema.outcomes))
+        return undefined;
+    const args = bodyValue(node.inputRows.find((r) => r.name === 'HitlTaskArguments')?.body);
+    let lifted;
+    try {
+        const fields = schema.fields.map((row) => {
+            const id = String(row.id);
+            const base = {
+                id,
+                ...(row.label !== undefined && row.label !== id ? { label: String(row.label) } : {}),
+                type: row.type,
+                ...liftFormFieldSettings(row),
+            };
+            const variable = typeof row.variable === 'string' ? row.variable.replace(/^vars\./, '') : undefined;
+            const answerVar = variable !== undefined && variable !== id ? { variable } : {};
+            const required = typeof row.required === 'boolean' ? { required: row.required } : {};
+            if (row.direction === 'input')
+                return { ...base, direction: 'input', value: String(args?.[id]) };
+            if (row.direction === 'inOut')
+                return { ...base, direction: 'inOut', value: String(args?.[id]), ...required, ...answerVar };
+            return { ...base, direction: 'output', ...required, ...answerVar };
+        });
+        const outcomes = schema.outcomes.map((o, i) => {
+            const name = String(o.name);
+            return outcomeIdOf(name, i) === o.id ? name : { name, id: String(o.id) };
+        });
+        const schemaId = String(schema.id);
+        const response = node.outputRows[0];
+        const answerVars = new Set(fields.filter((f) => f.direction !== 'input').map((f) => f.variable ?? f.id));
+        const extra = node.outputRows.slice(1).filter((r) => r.var !== undefined && !answerVars.has(r.var) && !r.custom);
+        lifted = {
+            form: { fields, outcomes, ...(schemaId !== stableSchemaId(processId, node.id) ? { schemaId } : {}) },
+            ...(node.name !== undefined ? { name: node.name } : {}),
+            ...(ctx.get('taskTitle')?.value !== (node.name ?? node.id) ? { title: ctx.get('taskTitle')?.value } : {}),
+            ...(ctx.has('priority') ? { priority: ctx.get('priority').value } : {}),
+            ...(ctx.has('labels') ? { labels: ctx.get('labels').value } : {}),
+            ...(extra.length ? { outputs: Object.fromEntries(extra.map((r) => [r.var, r.source ?? ''])) } : {}),
+            ...(response?.var !== undefined && response.var !== `${node.id}_processResponse` ? { outputVar: response.var } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+    let rebuilt;
+    try {
+        rebuilt = quickHumanTaskRows(node.id, processId, lifted);
+    }
+    catch {
+        return undefined;
+    }
+    const same = (node.typeVersion ?? 'v1') === rebuilt.typeVersion &&
+        rowsText(node.contextRows) === rowsText(rebuilt.contextRows) &&
+        node.inputSchema !== undefined &&
+        textOf(node.inputSchema) === textOf(rebuilt.inputSchema) &&
+        rowsText(node.inputRows) === rowsText(rebuilt.inputRows) &&
+        rowsText(node.outputRows) ===
+            rowsText([
+                ...rebuilt.outputRows,
+                ...rebuilt.mappedOutputRows.map((r) => ({ ...r, type: (r.var !== undefined ? authoredVarType(r.var) : undefined) ?? r.type })),
+            ]);
+    return same ? lifted : undefined;
+}

package/dist/bpmn/serialize.js

@@ -470,6 +470,7 @@ function createNode(ctx, n) {
                 skipCondition: n.skipCondition,
                 contextVerbatim: n.contextVerbatim,
                 outputRows: n.outputRows,
+                mappedOutputRows: n.mappedOutputRows,
             }, (varId) => ctx.authoredVarType.get(varId)), n);
         case 'subProcess':
             return applyActivityFields(ctx, createSubProcess(ctx, n), n);
@@ -822,6 +823,13 @@ export function implicitNodeVars(nodes, declared) {
             // is what keeps a node's own outputs inside the node: 83 of the 112 declarations
             // in `claims-intake-hitl` are this shape, and every one of them had to be
             // restated as a `.var()` because the derivation could not reach the row.
+            // A mapped row's own type is its fallback, so an undeclared variable is declared
+            // as the row is written; a declared one keeps its own (`claim` skips it). First, so
+            // `typedNodeDeclaredVars` below, which lists them too, cannot claim them untyped.
+            for (const row of n.mappedOutputRows ?? []) {
+                const d = rowDeclaration(row);
+                claim(row.var, n.id, d.type, d);
+            }
             if (n.outputRows) {
                 for (const row of n.outputRows) {
                     const d = rowDeclaration(row);

package/dist/bpmn/typed-node.d.ts

@@ -376,6 +376,12 @@ export interface TypedNodeInput {
      * for a caller that already knows the exact rows.
      */
     outputRows?: TypedOutputRow[];
+    /**
+     * Rows written after everything else, each typed from the author-declared variable it
+     * writes (the `varType` callback), its own `type` otherwise. Unlike `outputs` these
+     * survive `outputRows`; `.humanTask({ form })` uses them for its `outputs`.
+     */
+    mappedOutputRows?: TypedOutputRow[];
     /** `=`-expression that skips the node when truthy (activity/event tags only). */
     skipCondition?: string;
     /**

package/dist/bpmn/typed-node.js

@@ -556,6 +556,7 @@ varType) {
         // TypedNodeInput.outputRows — this is what lets a connector's response schema
         // survive a round trip.
         rows.push(...verbatimOutputRows(m, input.outputRows));
+        rows.push(...mappedRows(m, input.mappedOutputRows, varType));
         if (rows.length)
             payload.output = rows;
         return finish(m, spec, id, input.name, payload);
@@ -588,10 +589,15 @@ varType) {
         // which is what every row did before.
         rows.push(m.create('uipath:Output', { name: varId, type: varType?.(varId) ?? 'string', source, var: varId }));
     }
+    rows.push(...mappedRows(m, input.mappedOutputRows, varType));
     if (rows.length)
         payload.output = rows;
     return finish(m, spec, id, input.name, payload);
 }
+/** `TypedNodeInput.mappedOutputRows`, each typed from its declared variable when there is one. */
+function mappedRows(m, rows, varType) {
+    return verbatimOutputRows(m, (rows ?? []).map((r) => ({ ...r, type: (r.var !== undefined ? varType?.(r.var) : undefined) ?? r.type })));
+}
 /** `uipath:Output` rows exactly as the caller spelled them, deriving nothing. */
 export function verbatimOutputRows(m, rows) {
     return rows.map((row) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.55.0",
+  "version": "6.56.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -96,5 +96,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "64e3a8da320ffa0947e1a7edddcbabbdb9377e41"
+  "gitref": "31230281aaf4fa5e44d2844c08747ead2814e94d"
 }