@uipath/maestro-builder-sdk 6.39.0 → 6.40.0

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}. */

package/dist/bpmn/bpmn-sdk.js

@@ -697,6 +697,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'startEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             payload: opts.payload,
             interrupting: opts.interrupting === false ? false : undefined,
@@ -1754,6 +1755,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'connectorEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             subscribe: 'trigger',
             key: connector,
@@ -1907,6 +1909,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 +2039,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

@@ -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.

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/serialize.js

@@ -19,6 +19,7 @@ import { createConnectorTask } from './connector.js';
 import { createConnectorEvent, createExternalTask, intsvcOutputVar } from './intsvc.js';
 import { createExtensionPayload, createTypedNode, rowDeclaration, typedNodeOutputVar, verbatimOutputRows } from './typed-node.js';
 import { connectorOutputVars, typedNodeDeclaredVars } from './declared-vars.js';
+import { defaultEntryPointId } from './entry-point-id.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 const NS = {
@@ -138,16 +139,7 @@ export async function serialize(built, opts = {}) {
     const meta = built.metadata;
     if (meta?.migrationVersion !== undefined)
         processExt.push(m.create('uipath:MigrationVersion', { version: meta.migrationVersion }));
-    if (meta?.entryPointId !== undefined) {
-        // The package metadata generator discovers entry points by reading the root start
-        // event. A process-level `uipath:entryPointId` looks plausible and validates as XML,
-        // but is invisible to `update-metadata`, which then writes an empty entry-points.json.
-        const start = flowElements.find((element) => element.$type === 'bpmn:StartEvent');
-        if (start) {
-            const extensions = (start.extensionElements ??= m.create('bpmn:ExtensionElements', { values: [] }));
-            (extensions.values ??= []).unshift(m.create('uipath:EntryPointId', { value: meta.entryPointId }));
-        }
-    }
+    stampEntryPointIds(ctx, built, flowElements, meta?.entryPointId);
     if (meta?.tags !== undefined && meta.tags.length > 0)
         processExt.push(m.create('uipath:Tags', { tags: meta.tags.map((t) => m.create('uipath:Tag', { value: t })) }));
     if (meta?.caseManagement !== undefined)
@@ -218,6 +210,57 @@ export function processId(id) {
     return /^[A-Za-z_][\w.-]*$/.test(id) ? id : 'Process_1';
 }
 // ─── Scope (process root or a sub-process body) ───────────────────────────────
+/**
+ * `uipath:entryPointId` on the process's root start events, triggered or manual.
+ *
+ * The package metadata generator discovers entry points by reading the root start
+ * events — a process-level `uipath:entryPointId` looks plausible and validates as XML,
+ * but is invisible to `update-metadata`, which then writes an empty entry-points.json
+ * — and `uip maestro bpmn refresh` requires exactly one, a GUID, on each root manual
+ * start. The canvas writes one on every ROOT start and strips any inside a
+ * `bpmn:SubProcess` on save, so a nested start gets no derived id here, only one the
+ * author set. A root start takes, in order: the event's own option, else
+ * `.metadata({ entryPointId })` for the first root start in chain order, else the
+ * stable derived id (`entry-point-id.ts`, seeded from the builder's own process id, so
+ * two processes with the same start id derive different ids); `false` writes none.
+ */
+function stampEntryPointIds(ctx, built, flowElements, rootDefault) {
+    const { m } = ctx;
+    const own = new Map();
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind === 'startEvent' || n.kind === 'connectorEvent' || n.kind === 'typed')
+            own.set(n.id, n.entryPointId);
+    }
+    let first = true;
+    const stamp = (el, value) => {
+        if (value === undefined || value === false)
+            return;
+        const extensions = (el.extensionElements ??= m.create('bpmn:ExtensionElements', { values: [] }));
+        const values = (extensions.values ??= []);
+        if (values.some((x) => x.$type === 'uipath:EntryPointId'))
+            return;
+        values.unshift(m.create('uipath:EntryPointId', { value }));
+    };
+    const visit = (elements, root) => {
+        for (const el of elements) {
+            if (el.$type === 'bpmn:SubProcess') {
+                visit(el.flowElements ?? [], false);
+                continue;
+            }
+            if (el.$type !== 'bpmn:StartEvent')
+                continue;
+            const explicit = own.get(el.id);
+            if (!root) {
+                stamp(el, explicit);
+                continue;
+            }
+            const value = explicit !== undefined ? explicit : first && rootDefault !== undefined ? rootDefault : defaultEntryPointId(built.id, el.id);
+            first = false;
+            stamp(el, value);
+        }
+    };
+    visit(flowElements, true);
+}
 /** Build the flowElements array for one scope, wiring all references within it. */
 function buildScope(ctx, nodes, flows) {
     const { m } = ctx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.39.0",
+  "version": "6.40.0",
   "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": "df5d45c8b0eb17d5a82da37146e5b8130be03fab"
+  "gitref": "b3dd153cbf30937f6caf22ae3ad103d6ea678cb1"
 }