@uipath/maestro-builder-sdk 6.39.0 → 6.40.1

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

@@ -112,6 +112,8 @@ export type BpmnNode = {
      * BPMN's default, interrupting, and writes no attribute.
      */
     interrupting?: boolean;
+    /** A start event's own `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
 } | {
     kind: 'boundaryEvent';
     id: string;
@@ -175,6 +177,8 @@ export type BpmnNode = {
     name?: string;
     /** The registry extension type, e.g. `'Intsvc.UnifiedHttpRequest'`. */
     type: string;
+    /** When emitted as a `bpmn:startEvent`: its `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
     /** `uipath:context` values, by field name. */
     context: Record<string, unknown>;
     /** The payload, shaped by the type's `inputPattern`. */
@@ -203,6 +207,8 @@ export type BpmnNode = {
     kind: 'connectorEvent';
     id: string;
     name?: string;
+    /** A trigger's `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
     /**
      * `trigger` STARTS the process (`Intsvc.EventTrigger`, a `bpmn:startEvent`
      * carrying a message event definition); `event` pauses one mid-flow
@@ -539,8 +545,15 @@ export interface ProcessMetadata {
      * The root start event's package entry-point id (`uipath:entryPointId`). A GUID —
      * the one `bpmn init` assigned, or `crypto.randomUUID()`; `validate` refuses any
      * other value and `check` reports `ENTRYPOINT_ID_NOT_GUID`.
+     *
+     * Optional since every start event gets a stable derived id when none is set
+     * (`entry-point-id.ts`): the canvas writes one on every start, and
+     * `uip maestro bpmn refresh` requires one on every root manual start. `false`
+     * writes none on the root start — what `decompile` emits for an import that
+     * carried none, so the round trip stays faithful. A start event other than the
+     * first root one takes its id on the event itself (`StartOpts.entryPointId`).
      */
-    entryPointId?: string;
+    entryPointId?: string | false;
     /** Free-form document tags (`uipath:tags` / `uipath:tag`). */
     tags?: string[];
     /** Case-management marker (`uipath:caseManagement`) — `version` plus its body value. */
@@ -685,6 +698,15 @@ export interface StartOpts {
      * {@link ScopeBuilder.eventSubProcess} sets this from its own `interrupting` option.
      */
     interrupting?: boolean;
+    /**
+     * This start event's `uipath:entryPointId`. Unset, a root start derives a stable id
+     * from the process and event ids — which therefore changes if either is renamed, so
+     * pin the old id here when renaming in a deployed process; `false` writes none (what
+     * `decompile` emits for an imported start that carried none). The first root start
+     * may also take it from `.metadata({ entryPointId })`. A start inside a sub-process
+     * derives nothing (the canvas strips ids there) and writes only a value set here.
+     */
+    entryPointId?: string | false;
 }
 /**
  * Options for `.endEvent()`. `terminate`, `error`, or `message` picks the event
@@ -1497,6 +1519,11 @@ export interface ConnectorEventOpts extends ActivityOpts {
     outputs?: Record<string, string>;
     /** `=`-expression that skips the node when truthy. */
     skipCondition?: string;
+    /**
+     * `.eventTrigger()` only: the start event's `uipath:entryPointId`. Unset, a stable
+     * id is derived; `false` writes none. Ignored by `.waitForEvent()`.
+     */
+    entryPointId?: string | false;
 }
 /** Options for `.externalAgent()` / `.externalWorkflow()`. */
 export interface ExternalTaskOpts extends ActivityOpts {
@@ -1607,6 +1634,12 @@ export interface ActivityNodeOpts extends ActivityOpts {
      * writing `.activity()` by hand wants the defaults.
      */
     contextVerbatim?: boolean;
+    /**
+     * When the registry type is emitted as a `bpmn:startEvent` (a trigger such as
+     * `Intsvc.EventTrigger`): its `uipath:entryPointId`. Unset, a stable id is derived;
+     * `false` writes none, as `decompile` emits for an imported start that carried none.
+     */
+    entryPointId?: string | false;
 }
 /**
  * The BPMN task elements that are legal with NO `uipath:*` payload.
@@ -1892,6 +1925,8 @@ export interface EventSubProcessOpts {
     startName?: string;
     /** A payload on the start event, spelled out by hand — see {@link ExtensionPayload}. Exclusive with `errorVar`. */
     startPayload?: ExtensionPayload;
+    /** The nested start event's `uipath:entryPointId`, written only when set: the canvas strips ids inside a sub-process, so none is derived. */
+    startEntryPointId?: string | false;
     /** `uipath:tags` on the sub-process — see {@link ActivityOpts.tags}. */
     tags?: Record<string, string>;
     /** A `uipath:mapping` on the sub-process itself — see {@link SubProcessOpts.payload}. */
@@ -2690,9 +2725,10 @@ declare abstract class ScopeBuilder {
      * therefore proves the graph runs and the artifact validates — nothing about the
      * message actually arriving. See Phase 5 in `docs/BPMN_COVERAGE_DESIGN.md`.
      *
-     * The throw side (`Maestro.SendMessageEvent`) is deliberately NOT authored: its
-     * required `Reference` payload field cannot be expressed in a way the platform
-     * validator accepts. See `unsatisfiableRequiredInputs`.
+     * The throw side (`Maestro.SendMessageEvent`) has no builder method yet; author it
+     * as `.activity('send', 'Maestro.SendMessageEvent', { context: { name, inputSchema },
+     * inputs: { Reference } })` — it validates on uip 1.205 (Phase 6 in
+     * `docs/BPMN_COVERAGE_DESIGN.md`).
      *
      * @example
      * **Wait for another process to signal a shipment**

package/dist/bpmn/bpmn-sdk.js

@@ -344,6 +344,15 @@ class ScopeBuilder {
      * @returns This builder, so calls chain.
      */
     pushActivity(node, body) {
+        // An `outputVar` names the variable the type's own output row lands in; a type
+        // with no output row (the fire-and-forget Async starts) would accept it and emit
+        // nothing, so the author reads a variable nothing ever writes.
+        if (node.kind === 'typed' && node.outputVar !== undefined && !node.outputRows && !registryType(node.type, node.spec).output) {
+            throw new Error(`"${node.id}" (${node.type}) publishes no output row, so outputVar "${node.outputVar}" would bind nothing. ` +
+                (node.type.endsWith('Async')
+                    ? 'The Async start returns before the job does: drop outputVar, or use the waiting form (async: false) to read the response.'
+                    : 'Drop outputVar, or spell the rows with outputRows.'));
+        }
         this.place(node);
         if (body)
             body(new ActivityBuilder(this, node.id));
@@ -697,6 +706,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'startEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             payload: opts.payload,
             interrupting: opts.interrupting === false ? false : undefined,
@@ -1619,9 +1629,10 @@ class ScopeBuilder {
      * therefore proves the graph runs and the artifact validates — nothing about the
      * message actually arriving. See Phase 5 in `docs/BPMN_COVERAGE_DESIGN.md`.
      *
-     * The throw side (`Maestro.SendMessageEvent`) is deliberately NOT authored: its
-     * required `Reference` payload field cannot be expressed in a way the platform
-     * validator accepts. See `unsatisfiableRequiredInputs`.
+     * The throw side (`Maestro.SendMessageEvent`) has no builder method yet; author it
+     * as `.activity('send', 'Maestro.SendMessageEvent', { context: { name, inputSchema },
+     * inputs: { Reference } })` — it validates on uip 1.205 (Phase 6 in
+     * `docs/BPMN_COVERAGE_DESIGN.md`).
      *
      * @example
      * **Wait for another process to signal a shipment**
@@ -1754,6 +1765,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'connectorEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             subscribe: 'trigger',
             key: connector,
@@ -1907,6 +1919,7 @@ class ScopeBuilder {
             outputRows: opts.outputRows,
             skipCondition: opts.skipCondition,
             contextVerbatim: opts.contextVerbatim,
+            entryPointId: opts.entryPointId,
             tags: opts.tags,
             retry: opts.retry,
             errorMapping: opts.errorMapping,
@@ -2036,6 +2049,7 @@ class ScopeBuilder {
         sb._begin({
             kind: 'startEvent',
             id: startId,
+            entryPointId: opts.startEntryPointId,
             name: opts.startName,
             event,
             payload: opts.startPayload ?? (capture !== undefined ? errorCapturePayload(capture, 'startEvent') : undefined),

package/dist/bpmn/check.js

@@ -3,7 +3,7 @@ import { allNodes, folderCompanionKeys, implicitNodeVars, processId } from './se
 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, REGISTRY_GAPS, registryType, unsatisfiableRequiredInputs, } from './typed-node.js';
+import { bindingRequiredFields, CASE_RUNTIME_INTERNAL_TYPES, missingRequiredContext, missingRequiredInputs, REGISTRY_GAPS, registryType, } from './typed-node.js';
 import { ownEntry } from '../core/own-entry.js';
 /**
  * The job-start family — the types whose engine handler switches addressing on the
@@ -310,15 +310,25 @@ const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  * main one agent spent its whole turn budget there. Reported here, at the first rung.
  */
 function checkEntryPointId(built, diags) {
+    const report = (where, id, at) => {
+        diags.push({
+            level: 'error',
+            code: 'ENTRYPOINT_ID_NOT_GUID',
+            message: `${where} "${id}" is not a GUID; \`uip maestro bpmn validate\` refuses it. Use the id \`bpmn init\` ` +
+                `assigned (decompile the stub it wrote to carry it), a fresh one from \`crypto.randomUUID()\`, or leave it ` +
+                `unset and the SDK derives a stable one.`,
+            ...(at !== undefined ? { where: at } : {}),
+        });
+    };
     const id = built.metadata?.entryPointId;
-    if (id === undefined || GUID.test(id))
-        return;
-    diags.push({
-        level: 'error',
-        code: 'ENTRYPOINT_ID_NOT_GUID',
-        message: `metadata.entryPointId "${id}" is not a GUID; \`uip maestro bpmn validate\` refuses it. Use the id \`bpmn init\` ` +
-            `assigned (decompile the stub it wrote to carry it), or a fresh one from \`crypto.randomUUID()\`.`,
-    });
+    if (typeof id === 'string' && !GUID.test(id))
+        report('metadata.entryPointId', id);
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind !== 'startEvent' && n.kind !== 'connectorEvent' && n.kind !== 'typed')
+            continue;
+        if (typeof n.entryPointId === 'string' && !GUID.test(n.entryPointId))
+            report(`"${n.id}" entryPointId`, n.entryPointId, n.id);
+    }
 }
 /**
  * A `folderKey` binding must be keyed by its CONNECTION, not by the folder.
@@ -1417,20 +1427,20 @@ inEventSubProcess = false) {
                     where: n.id,
                 });
             }
-            // A type whose required payload fields cannot be expressed at all. Warning,
-            // not error: the node is as correct as the registry allows, so refusing it
-            // would block work the platform, not the author, has to fix. Saying nothing
-            // is worse — the artifact validates here and is rejected by the CLI.
-            const unsatisfiable = unsatisfiableRequiredInputs(n.type, n.spec);
-            if (unsatisfiable.length) {
+            // A type the case-management runtime writes for itself. Warning, not error:
+            // the platform validates it, and nobody designs a process around it. The one
+            // legitimate authored form is a preserved import, which `decompile` writes as
+            // `contextVerbatim: true` — that node is left alone, so a brownfield edit that
+            // keeps the platform's nodes as they were is not told off on every check.
+            if (CASE_RUNTIME_INTERNAL_TYPES.has(n.type) && n.contextVerbatim !== true) {
                 diags.push({
                     level: 'warning',
-                    code: 'REQUIRED_INPUT_UNSATISFIABLE',
-                    message: `"${n.id}" (${n.type}) declares required input(s) ${unsatisfiable.map((f) => `"${f}"`).join(', ')}, ` +
-                        `but its "${registryType(n.type, n.spec).inputPattern}" pattern merges every input into one row, so the ` +
-                        `platform's required-field rule cannot see them. \`uip maestro bpmn validate\` will report ` +
-                        `EMPTY_REQUIRED_FIELD whatever this node carries — a platform defect, not an authoring error. ` +
-                        `See docs/BPMN_COVERAGE_DESIGN.md D13.`,
+                    code: 'TYPE_RUNTIME_INTERNAL',
+                    message: `"${n.id}" (${n.type}) is a node the case-management runtime writes for itself when it materializes a ` +
+                        `case plan (scheduler state only the platform produces); the canvas offers it nowhere, and a process is not ` +
+                        `designed around one — author the case in the Case SDK instead. To preserve an imported one as it was, keep ` +
+                        `the form \`decompile\` writes (\`contextVerbatim: true\`), which this check leaves alone. ` +
+                        `See its row in typescript/sdk/bpmn-coverage.json.`,
                     where: n.id,
                 });
             }

package/dist/bpmn/decompile.js

@@ -61,6 +61,7 @@ import { BPMN_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from '../schema-version.js';
 import { commentText } from '../core/comment-text.js';
 import { tsLiteral, tsText } from '../core/ts-literal.js';
+import { defaultEntryPointId } from './entry-point-id.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 /**
@@ -717,6 +718,47 @@ function emitOutputRows(payload) {
     return `[${rendered.join(', ')}]`;
 }
 // ─── Element emitters ─────────────────────────────────────────────────────────
+/**
+ * The process being decompiled, for the entry-point spelling below: the builder id
+ * the derived default is seeded from, the root start events, and the one root start
+ * whose id `.metadata({ entryPointId })` spells — the only root start, when there is
+ * exactly one. With several, every root start spells its own on the event, because
+ * `serialize` hands `.metadata()`'s id to the first root start in CHAIN order and the
+ * chain is emitted manual-first, which need not be document order.
+ */
+let runEntryPoints = {
+    builderProcessId: '',
+    rootStartIds: new Set(),
+};
+/**
+ * How an imported start event's `uipath:entryPointId` is spelled on the event's own
+ * call, or `undefined` for none. A root start: the value as text when the file
+ * carries one the SDK would not derive; nothing when it equals the derived default
+ * (compile writes it back unprompted); `false` when the file carries none, so the
+ * recompile adds nothing. The lone root start is `.metadata()`'s and gets nothing
+ * here. A nested start derives nothing on compile, so it is spelled only when the
+ * file carries a value.
+ */
+function entryPointOption(el) {
+    if (localName(el.$type) !== 'startEvent' || el.id === runEntryPoints.metadataStartId)
+        return undefined;
+    const legacy = runEntryPoints.processLevel;
+    const value = entryPointValueOf(el) ?? (legacy !== undefined && legacy.startId === el.id ? legacy.value : undefined);
+    if (!runEntryPoints.rootStartIds.has(el.id))
+        return value === undefined ? undefined : tsText(value);
+    return entryPointText(el.id, value);
+}
+/** The `uipath:entryPointId` value a start event carries, if any. */
+function entryPointValueOf(el) {
+    const row = (el.extensionElements?.values ?? []).find((x) => x.$type === 'uipath:EntryPointId');
+    return row?.value !== undefined ? String(row.value) : undefined;
+}
+/** `entryPointOption`'s spelling for a ROOT start event id and the value it carries. */
+function entryPointText(startId, value) {
+    if (value === undefined)
+        return 'false';
+    return value === defaultEntryPointId(runEntryPoints.builderProcessId, startId) ? undefined : tsText(value);
+}
 /**
  * A registry-typed node.
  *
@@ -776,6 +818,7 @@ function emitTypedNode(chain, el, payload, type) {
         ['outputs', verbatimRows === undefined ? record(extras) : undefined],
         ['skipCondition', payload.skipCondition !== undefined ? tsText(payload.skipCondition) : undefined],
         ['contextVerbatim', Object.keys(ctx).length ? 'true' : undefined],
+        ['entryPointId', entryPointOption(el)],
         ['tags', tagsOf(el)],
         ['retry', emitRetry(retryOf(el))],
         ['errorMapping', emitErrorMapping(errorMappingOf(el))],
@@ -1489,6 +1532,7 @@ function renderEventSubProcess(plan, sp, depth, indent) {
         ],
         ['startId', start.id !== `${sp.id}_start` ? tsText(start.id) : undefined],
         ['startName', start.name !== undefined ? tsText(start.name) : undefined],
+        ['startEntryPointId', entryPointOption(start)],
         ['startPayload', payload && type && capture === undefined ? opts([['type', tsText(type)], ['outputRows', emitOutputRows(payload) ?? '[]']]) : undefined],
         ['tags', tagsOf(sp)],
         ['payload', spPayload && spType ? opts([['type', tsText(spType)], ['outputRows', emitOutputRows(spPayload) ?? '[]']]) : undefined],
@@ -1665,6 +1709,7 @@ function emitTriggerStartEvent(chain, el, payload, type) {
         ['name', el.name !== undefined ? tsText(el.name) : undefined],
         ...eventOptions(el),
         ['trigger', trigger],
+        ['entryPointId', entryPointOption(el)],
     ])})`);
 }
 /**
@@ -1748,6 +1793,7 @@ function emitEvent(chain, el, kind, payload, type) {
         // Only a start event can be non-interrupting, and only the exception is
         // spelled — the builder's default is BPMN's.
         ['interrupting', kind === 'startEvent' && el.isInterrupting === false ? 'false' : undefined],
+        ['entryPointId', entryPointOption(el)],
         ['payload', eventPayload],
     ]))})`);
 }
@@ -2086,6 +2132,26 @@ export async function decompile(xml, options = {}) {
     const migration = findExt('uipath:MigrationVersion');
     const rootStart = (process.flowElements ?? []).find((x) => x.$type === 'bpmn:StartEvent');
     const entryPoint = (rootStart?.extensionElements?.values ?? []).find((x) => x.$type === 'uipath:EntryPointId') ?? findExt('uipath:EntryPointId');
+    const rootStarts = (process.flowElements ?? []).filter((x) => x.$type === 'bpmn:StartEvent');
+    // `bpmn(process.id)` is what the source will say, so it is the seed on both sides.
+    const builderId = String(process.id ?? '');
+    const processLevelEntryPoint = findExt('uipath:EntryPointId');
+    runEntryPoints = {
+        builderProcessId: builderId,
+        rootStartIds: new Set(rootStarts.map((x) => x.id)),
+        metadataStartId: rootStarts.length === 1 ? rootStart?.id : undefined,
+        ...(rootStarts.length > 1 && rootStart !== undefined && processLevelEntryPoint?.value !== undefined
+            && !(rootStart.extensionElements?.values ?? []).some((x) => x.$type === 'uipath:EntryPointId')
+            ? { processLevel: { startId: rootStart.id, value: String(processLevelEntryPoint.value) } }
+            : {}),
+    };
+    // A lone root start's id is `.metadata()`'s: the file's own value when the SDK would
+    // not derive it, `false` when the file carries none (so the recompile adds none), and
+    // nothing when it equals the derived default. With several root starts each spells
+    // its own on the event (see `runEntryPoints`).
+    const rootEntryPointText = rootStarts.length === 1 && rootStart !== undefined
+        ? entryPointText(rootStart.id, entryPoint?.value !== undefined ? String(entryPoint.value) : undefined)
+        : undefined;
     const tagsExt = findExt('uipath:Tags');
     const caseMgmt = findExt('uipath:CaseManagement');
     const tagValues = (tagsExt?.tags ?? []).map((t) => t.value).filter((v) => typeof v === 'string');
@@ -2103,13 +2169,13 @@ export async function decompile(xml, options = {}) {
     const schema = preserveSchemaVersion(BPMN_SCHEMA_VERSIONS, migration?.version);
     if (schema.call)
         chain.add(schema.call);
-    if (entryPoint !== undefined ||
+    if (rootEntryPointText !== undefined ||
         tagValues.length > 0 ||
         caseMgmt !== undefined ||
         nonExecutable) {
         chain.add(`.metadata(${opts([
             ['executable', nonExecutable ? 'false' : undefined],
-            ['entryPointId', entryPoint?.value !== undefined ? tsText(entryPoint.value) : undefined],
+            ['entryPointId', rootEntryPointText],
             ['tags', tagValues.length > 0 ? `[${tagValues.map((t) => tsText(t)).join(', ')}]` : undefined],
             [
                 'caseManagement',

package/dist/bpmn/entry-point-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The default `uipath:entryPointId` for one start event.
+ *
+ * @param builderProcessId - The id `bpmn(id)` was called with — not the `bpmn:process` id
+ *   on the wire, which `processId()` folds every non-identifier name to `Process_1`, so
+ *   two such processes would share every start's id.
+ * @param startEventId - The start event's element id.
+ */
+export declare function defaultEntryPointId(builderProcessId: string, startEventId: string): string;

package/dist/bpmn/entry-point-id.js

@@ -0,0 +1,35 @@
+/**
+ * The entry-point id a start event carries when nobody chose one.
+ *
+ * The canvas writes `uipath:entryPointId` on every root start event, and the CLI's
+ * packaging (`uip maestro bpmn refresh`, UiPath/cli `bpmn-packaging/entry-points.ts`)
+ * requires exactly one, a GUID, on every root manual start — "read from the BPMN,
+ * never minted, so the derived entry-points.json is stable across runs".
+ *
+ * A root start with no id of its own gets this one: the first 128 bits of SHA-256
+ * over the builder's process id and the start event id, in GUID shape — the derivation
+ * the Case compiler uses for an entry point's `uniqueId`. It is the same on every
+ * compile and machine, differs between processes and between starts, and is
+ * reproducible by `decompile`, which omits an id equal to it.
+ *
+ * It is derived from two names, so it CHANGES when either is renamed. The entry point's
+ * `uniqueId` is what Orchestrator rebinds a release by on upgrade
+ * (`ReleasesManager.cs`, `UniqueId`): rename `bpmn('Invoice')` or its start in a
+ * process that is already deployed, and on the next upgrade Orchestrator finds no
+ * entry point with the old `uniqueId` and silently rebinds the release to the main
+ * entry point. Pin the old id on the start (`.startEvent(id, { entryPointId })` or
+ * `.metadata({ entryPointId })`) when renaming either; `decompile` of the deployed
+ * file carries it.
+ */
+import { sha256Uuid } from '../core/stable-id.js';
+/**
+ * The default `uipath:entryPointId` for one start event.
+ *
+ * @param builderProcessId - The id `bpmn(id)` was called with — not the `bpmn:process` id
+ *   on the wire, which `processId()` folds every non-identifier name to `Process_1`, so
+ *   two such processes would share every start's id.
+ * @param startEventId - The start event's element id.
+ */
+export function defaultEntryPointId(builderProcessId, startEventId) {
+    return sha256Uuid(`uipath:entryPointId/${builderProcessId}/${startEventId}`);
+}

package/dist/bpmn/registry-fallback.js

@@ -159,7 +159,11 @@ export function shapeExtensionType(spec) {
         output,
         eventDefinition: eventDefinitionOf(spec.XmlTemplate),
         requiresDiscovery: Boolean(spec.RequiresDiscovery),
+        isDynamic: Boolean(spec.IsDynamic),
         bindingPattern: spec.BindingPattern ?? 'none',
+        placements: Object.fromEntries(Object.entries((spec.Placements ?? {}))
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, p]) => [name, { element: p?.Type ?? null, eventDefinition: p?.EventDefinition?.Type ?? null }])),
     };
 }
 /** `registry get <type>`, shaped, or `undefined` when the registry has no such type. */