@uipath/maestro-builder-sdk 6.37.0 → 6.38.0

package/dist/bpmn/decompile.js

@@ -244,7 +244,225 @@ function localName(type) {
     const local = type.split(':')[1] ?? type;
     return local.charAt(0).toLowerCase() + local.slice(1);
 }
+// The connector lift's state for one `decompile()` call. Planned in a pre-pass so the
+// variable block, which is written before any element, already knows which tasks come
+// back as `.connector()` — their declarations derive differently (`derivedVariableIds`).
+// The lift's per-decompile state. Module-level `let`s, reset at the top of `decompile()`
+// and read while it emits: nothing awaits between the reset and the last emit, and the
+// module is not re-entered, which is the invariant this relies on. A per-call context
+// object is the right shape if that ever changes.
+let runLibrary;
+let runLiftPlans = new Map();
+let runLiftSkipped = [];
+let runLiftCalls = new Map();
 /** The `uipath:*` payload element on an element, if it has one. */
+/** Context rows a connector task carries that `.connector()` writes itself, or that the lift reads. */
+const CONNECTOR_CONTEXT_ROWS = new Set([
+    'connectorKey', 'operation', 'objectName', 'method', 'path', 'connection', 'folderKey', 'resourceKey',
+    'metadata', 'activityConfigurationVersion', 'activity',
+]);
+/** Row targets `.connector()` can address — the library's parameter locations plus the body. */
+const CONNECTOR_ROW_TARGETS = new Set(['path', 'query', 'body', 'multipart', 'file']);
+/**
+ * Plan every connector task's lift in `container` (sub-processes included): the id →
+ * plan for the ones `.connector()` can express, and a reason for each one it cannot.
+ */
+function planConnectorLifts(container, skip) {
+    for (const el of container.flowElements ?? []) {
+        if (el.$type === 'bpmn:SubProcess')
+            planConnectorLifts(el, skip);
+        const payload = payloadOf(el);
+        if (!payload || extensionTypeOf(payload) !== 'Intsvc.ActivityExecution')
+            continue;
+        if (skip.has(el.id)) {
+            runLiftSkipped.push({ id: el.id, reason: 'the lift did not verify' });
+            continue;
+        }
+        const outcome = planConnectorLift(el, payload);
+        if (typeof outcome === 'string')
+            runLiftSkipped.push({ id: el.id, reason: outcome });
+        else
+            runLiftPlans.set(el.id, outcome);
+    }
+}
+/** The `=bindings.<id>` a context value references, or `undefined` for anything else. */
+function bindingIdOf(value) {
+    const m = typeof value === 'string' ? /^=bindings\.([A-Za-z0-9_]+)$/.exec(value) : null;
+    return m ? m[1] : undefined;
+}
+/**
+ * A row's value as `.connector()` takes it: an `=`-expression as the string it is;
+ * otherwise the literal, coerced to the type the library declares for the parameter,
+ * because the file writes every scalar row as `type="string"` (`value="false"`,
+ * `value="0"`) and the shared validator refuses a string where it declares a boolean
+ * or an integer.
+ */
+function liftedInputValue(raw, dataType) {
+    if (raw.startsWith('='))
+        return raw;
+    switch ((dataType ?? 'string').toLowerCase()) {
+        case 'boolean':
+            return raw === 'true' ? true : raw === 'false' ? false : raw;
+        case 'integer':
+        case 'number':
+            return raw.trim() !== '' && Number.isFinite(Number(raw)) ? Number(raw) : raw;
+        default:
+            return raw;
+    }
+}
+/**
+ * The `.connector()` call for one task, or why there is none. Everything here is a
+ * fact the lift needs and the generic form carries; what the SDK regenerates on
+ * compile is deliberately not read (see `BpmnDecompileOptions.connectors`).
+ */
+function planConnectorLift(el, payload) {
+    const library = runLibrary;
+    if (!library)
+        return 'no connector library';
+    const ctx = contextOf(payload);
+    const rows = payload.context?.input ?? [];
+    const unknownCtx = rows.map((r) => r.name).filter((n) => !CONNECTOR_CONTEXT_ROWS.has(n));
+    if (unknownCtx.length)
+        return `context row(s) .connector() does not write: ${unknownCtx.join(', ')}`;
+    if (rows.some((r) => r.required !== undefined || r.target !== undefined))
+        return 'a context row carries attributes the record form cannot';
+    const ctxString = (k) => (typeof ctx[k] === 'string' ? ctx[k] : undefined);
+    const connectorKey = ctxString('connectorKey');
+    if (!connectorKey)
+        return 'no connectorKey';
+    let identity;
+    try {
+        identity = library.identifyAction({
+            connectorKey,
+            httpMethod: ctxString('method'),
+            endpoint: ctxString('path'),
+            objectName: ctxString('objectName'),
+        });
+    }
+    catch (e) {
+        return `not in the library: ${e.message}`;
+    }
+    const connection = bindingIdOf(ctx.connection);
+    if (!connection)
+        return `connection is ${ctx.connection === undefined ? 'absent' : JSON.stringify(ctx.connection)}, not a =bindings.<id> reference`;
+    const folder = ctx.folderKey === undefined ? undefined : bindingIdOf(ctx.folderKey);
+    if (ctx.folderKey !== undefined && folder === undefined)
+        return `folderKey is ${JSON.stringify(ctx.folderKey)}, not a =bindings.<id> reference`;
+    let params;
+    let declared;
+    try {
+        const resolved = library.resolve(identity.key, identity.action, identity.version, identity.object);
+        params = new Map((resolved.entry.operation?.parameters ?? []).map((p) => [p.name, p.dataType]));
+        declared = new Set([...params.keys(), ...resolved.fields.map((f) => f.name)]);
+    }
+    catch (e) {
+        return `the library cannot resolve ${identity.key}/${identity.action}: ${e.message}`;
+    }
+    const inputs = {};
+    for (const row of payload.input ?? []) {
+        const target = row.target;
+        if (target === undefined || !CONNECTOR_ROW_TARGETS.has(target)) {
+            return `payload row "${row.name}" has ${target === undefined ? 'no target' : `target "${target}"`}`;
+        }
+        if (target === 'body') {
+            if (row.name !== 'body')
+                return `body row is named "${row.name}"`;
+            const body = safeJson(row.body ?? '{}');
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                return 'the body row is not a JSON object';
+            for (const [k, v] of Object.entries(body)) {
+                if (k in inputs)
+                    return `"${k}" appears both as a parameter row and in the body`;
+                // `.connector()` validates every input against the library, and a field the
+                // static library does not declare — an entity's own columns on a Data Fabric
+                // update, a form's fields — is refused until `registry prepare` loads it.
+                if (!declared.has(k) && !declared.has(k.split('.')[0])) {
+                    return `body field "${k}" is not in the library for ${identity.key}/${identity.action} (connection-specific; \`registry prepare\` loads it)`;
+                }
+                inputs[k] = v;
+            }
+            continue;
+        }
+        if (row.value === undefined)
+            return `payload row "${row.name}" carries no value attribute`;
+        if (row.name in inputs)
+            return `payload row "${row.name}" appears twice`;
+        inputs[row.name] = liftedInputValue(String(row.value), params.get(row.name));
+    }
+    let outputVar;
+    let errorVar;
+    const outputs = {};
+    for (const row of payload.output ?? []) {
+        const standard = (row.name === 'response' && row.source === '=response' && outputVar === undefined) ||
+            (row.name === 'Error' && row.source === '=Error' && errorVar === undefined);
+        // The two standard rows may carry a schema body — the SDK writes the library's
+        // response schema there, and regenerates it. Any other row's body, or a target or
+        // description on any row, is something `.connector()` cannot say.
+        if (row.target !== undefined || row.description !== undefined || (row.body !== undefined && !standard)) {
+            return `output row "${row.name}" carries attributes .connector() does not write`;
+        }
+        if (standard && row.name === 'response')
+            outputVar = row.var;
+        else if (standard)
+            errorVar = row.var;
+        else {
+            // An extra mapped row: `outputs` keys it by its variable, so one without a
+            // variable or a source, or a second row on the same variable, cannot be said.
+            if (typeof row.var !== 'string' || typeof row.source !== 'string')
+                return `output row "${row.name}" has no variable or no source`;
+            if (row.var in outputs)
+                return `two output rows write "${row.var}"`;
+            const plain = row.name === row.var && (row.type ?? 'string') === 'string' && !row.custom;
+            outputs[row.var] = plain
+                ? row.source
+                : { source: row.source, ...(row.name !== row.var ? { name: row.name } : {}), ...((row.type ?? 'string') !== 'string' ? { type: row.type } : {}), ...(row.custom ? { custom: true } : {}) };
+        }
+    }
+    return {
+        key: identity.key,
+        action: identity.action,
+        version: identity.version === '1.0.0' ? undefined : identity.version,
+        object: identity.object,
+        inputs,
+        connection,
+        folder,
+        outputVar: outputVar !== undefined && outputVar !== `${el.id}_response` ? outputVar : undefined,
+        errorVar: errorVar !== undefined && errorVar !== `${el.id}_Error` ? errorVar : undefined,
+        outputs: Object.keys(outputs).length ? outputs : undefined,
+    };
+}
+/** The `outputs` option of a lifted connector as source. */
+function connectorOutputsSource(outputs) {
+    return `{ ${Object.entries(outputs)
+        .map(([v, spec]) => `${key(v)}: ${typeof spec === 'string' ? tsText(spec) : opts([
+        ['source', tsText(spec.source)],
+        ['name', spec.name !== undefined ? tsText(spec.name) : undefined],
+        ['type', spec.type !== undefined ? tsText(spec.type) : undefined],
+        ['custom', spec.custom ? 'true' : undefined],
+    ])}`)
+        .join(', ')} }`;
+}
+/** A planned connector task as its `.connector()` call. */
+function emitConnectorLift(chain, el, payload, plan) {
+    const options = opts([
+        ['name', el.name !== undefined ? tsText(el.name) : undefined],
+        ['connection', tsText(plan.connection)],
+        ['folder', plan.folder !== undefined ? tsText(plan.folder) : undefined],
+        ['version', plan.version !== undefined ? tsText(plan.version) : undefined],
+        ['object', plan.object !== undefined ? tsText(plan.object) : undefined],
+        ['outputVar', plan.outputVar !== undefined ? tsText(plan.outputVar) : undefined],
+        ['errorVar', plan.errorVar !== undefined ? tsText(plan.errorVar) : undefined],
+        ['outputs', plan.outputs ? connectorOutputsSource(plan.outputs) : undefined],
+        ['skipCondition', payload.skipCondition !== undefined ? tsText(payload.skipCondition) : undefined],
+        ['tags', tagsOf(el)],
+        ['retry', emitRetry(retryOf(el))],
+        ['errorMapping', emitErrorMapping(errorMappingOf(el))],
+        ['loop', emitLoop(el)],
+    ]);
+    const call = `.connector(${tsText(el.id)}, ${tsText(plan.key)}, ${tsText(plan.action)}, ${record(plan.inputs) ?? '{}'}${optionalArg(options)})`;
+    runLiftCalls.set(el.id, call);
+    chain.add(call);
+}
 function payloadOf(el) {
     for (const ext of el.extensionElements?.values ?? []) {
         if (ext.$type === 'uipath:Activity' || ext.$type === 'uipath:Event' || ext.$type === 'uipath:Mapping')
@@ -1584,6 +1802,11 @@ function emitElement(chain, el, depth, indent) {
         if (kind === 'startEvent' && startEventDefinitionCarriesConfig(el)) {
             return emitTriggerStartEvent(chain, el, payload, type);
         }
+        // A connector task the library can name, planned in the pre-pass — see
+        // `BpmnDecompileOptions.connectors` for what the lift gives up and how it is checked.
+        const plan = runLiftPlans.get(el.id);
+        if (plan)
+            return emitConnectorLift(chain, el, payload, plan);
         return emitTypedNode(chain, el, payload, type);
     }
     switch (kind) {
@@ -1930,7 +2153,16 @@ export async function decompile(xml, options = {}) {
     // found none, so NOTHING was recognised as derived and every declaration was echoed
     // by hand. That was invisible — an echoed declaration takes the id before
     // `implicitNodeVars` can claim it, so the output was correct, just 112 lines of it.
-    const { ids: derived, folds } = derivedVariableIds(process, varsExt, host.rehome);
+    // The connector lift, planned first: the variable block below needs to know which
+    // tasks come back as `.connector()`, whose declarations derive as a connector's.
+    runLibrary = options.library;
+    runLiftPlans = new Map();
+    runLiftSkipped = [];
+    runLiftCalls = new Map();
+    if (options.library && (options.connectors ?? 'lift') === 'lift') {
+        planConnectorLifts(process, options.verbatimConnectors ?? new Set());
+    }
+    const { ids: derived, folds } = derivedVariableIds(process, varsExt, host.rehome, new Set(runLiftPlans.keys()));
     const schemaPlan = planSchemas([
         ...(varsExt?.input ?? []),
         ...(varsExt?.inputOutput ?? []),
@@ -1951,12 +2183,14 @@ export async function decompile(xml, options = {}) {
     // hand-editing". Only when something was actually folded: a document of explicit
     // `.var()` calls already states its order by their position, and the extra line would
     // be noise.
+    let preambleLines = 0;
     if (derived.size) {
         const ids = [...(varsExt?.input ?? []), ...(varsExt?.inputOutput ?? []), ...(varsExt?.output ?? [])].map((v) => v.id);
         chain.add(`.preserve({ variableOrder: [${ids.map(tsText).join(', ')}] })`);
     }
     try {
         emitVariablesInto(chain, host.container, host.rehome?.to ?? host.container.id, derived, host.rehome, schemaPlan, publicDeclarationScopeOf(process, host.rehome?.to ?? host.container.id));
+        preambleLines = chain.all.length;
         if (options.style === 'nested') {
             const sequence = options.sequenceMode ?? true;
             const summary = { handlers: 0, branches: 0, nets: 0, leftFlat: [], renamedFlows: [], sequence };
@@ -1975,11 +2209,18 @@ export async function decompile(xml, options = {}) {
     }
     finally {
         foldedVarSchemas = undefined;
+        runLibrary = undefined;
     }
     const importFrom = options.importSpecifier ?? './bpmn-sdk.js';
     const imported = ['bpmn', ...[...schemaPlan.imports].sort()].join(', ');
     const head = `import { ${imported} } from ${tsText(importFrom)};\n\nexport default bpmn(${tsText(process.id)})`;
     const name = process.name !== undefined ? `\n${indent}.name(${tsText(process.name)})` : '';
+    options.onConnectorLift?.({
+        lifted: [...runLiftPlans.keys()],
+        verbatim: runLiftSkipped,
+        preamble: `${host.note}${head}${name}\n${chain.all.slice(0, preambleLines).join('\n')}`,
+        calls: runLiftCalls,
+    });
     return `${host.note}${head}${name}\n${chain.all.join('\n')}\n${indent}.build();\n`;
 }
 /**
@@ -2010,7 +2251,9 @@ export async function decompile(xml, options = {}) {
  */
 function derivedVariableIds(process, varsExt, 
 /** The collaboration→process re-parenting, so `elementId` is compared post-move. */
-rehome) {
+rehome, 
+/** Connector tasks the lift writes as `.connector()`, whose declarations `implicitNodeVars` derives as a connector's. */
+lifted = new Set()) {
     // var id -> the declaration `implicitNodeVars` would derive for it
     const candidates = new Map();
     const walk = (container) => {
@@ -2042,6 +2285,20 @@ rehome) {
                 for (const row of payload.output ?? []) {
                     if (!row.var)
                         continue;
+                    // A lifted connector's two variables are claimed the way `.connector()` claims
+                    // them — `json`, named after the id, no schema — so a file's own `jsonSchema`
+                    // declaration with a body stays an explicit `.var()` rather than being folded
+                    // onto a row the lifted call no longer has.
+                    if (lifted.has(el.id)) {
+                        // A `.connector()` call has no row to fold a declaration's schema onto, so
+                        // a declaration that carries one stays explicit whatever its wire type —
+                        // `noFold` below — rather than vanishing into `foldedVarSchemas`, which the
+                        // lift never reads.
+                        // The wire type the row implies: `json` for the response and Error rows, the
+                        // row's own for an extra mapped row (`integer`), as `implicitNodeVars` declares.
+                        candidates.set(row.var, { owner: el.id, wire: rowDeclaration({ name: row.name, type: row.type }).wire, noFold: true });
+                        continue;
+                    }
                     // A script task's rows come back as `outputs` when that form reproduces
                     // them, and `implicitNodeVars` then derives their declarations from the
                     // keys: id as the name, that arm's own wire type. Rows that need spelling
@@ -2092,7 +2349,7 @@ rehome) {
         // against 28 rows, so without the fold almost every structured output stays an
         // explicit `.var()`.
         if (String(v.body ?? '') !== String(c.schema ?? '')) {
-            if (c.schema !== undefined || v.body === undefined)
+            if (c.schema !== undefined || v.body === undefined || c.noFold)
                 continue;
             folds.set(v.id, v.body);
         }

package/dist/bpmn/serialize.js

@@ -85,6 +85,7 @@ export async function serialize(built, opts = {}) {
         schemas: built.schemas,
         variableOrder: built.preservation?.variableOrder,
         bindingSink: new Map(),
+        declaredBindings: new Map(built.bindings.map((b) => [b.id, { name: b.name, default: b.default, resourceKey: b.resourceKey }])),
         varTypeOf: (varId) => authoredVarType.get(varId),
     };
     // `.name()` was accepted by the builder, stored on the built graph, and never
@@ -664,6 +665,14 @@ export function implicitNodeVars(nodes, declared) {
             const { response, error } = connectorOutputVars(n);
             claim(response, n.id);
             claim(error, n.id);
+            // An extra mapped row declares its variable as the row is typed (`string` when the
+            // row says nothing), not as `object`: `{ poCount: { source, type: 'integer' } }`
+            // writes an `integer` row and must declare an integer.
+            for (const [varId, spec] of Object.entries(n.outputs ?? {})) {
+                const row = typeof spec === 'string' ? { source: spec } : spec;
+                const d = rowDeclaration({ name: row.name ?? varId, type: row.type ?? 'string' });
+                claim(varId, n.id, d.type, d);
+            }
         }
         else if (n.kind === 'typed') {
             // Shared with the expression checker rather than repeated here. Repeating it is

package/lib/library-json.samples/index.json

@@ -180,6 +180,15 @@
       "activityType": "Curated",
       "objectName": "QueryEntityRecordsCurated",
       "path": "uipath-uipath-dataservice/query-entity-records@1.0.0.json"
+    },
+    {
+      "nodeType": "uipath.connector.uipath-uipath-dataservice.update-entity-record",
+      "version": "1.0.0",
+      "connectorKey": "uipath-uipath-dataservice",
+      "label": "Update Entity Record",
+      "activityType": "Curated",
+      "objectName": "UpdateEntityRecordV2",
+      "path": "uipath-uipath-dataservice/update-entity-record@1.0.0.json"
     }
   ]
 }

package/lib/library-json.samples/uipath-uipath-dataservice/update-entity-record@1.0.0.json

@@ -0,0 +1,132 @@
+{
+  "schemaVersion": "1",
+  "nodeType": "uipath.connector.uipath-uipath-dataservice.update-entity-record",
+  "version": "1.0.0",
+  "category": "connector.196550",
+  "tags": [
+    "connector",
+    "activity"
+  ],
+  "connector": {
+    "key": "uipath-uipath-dataservice",
+    "name": "UiPath Data Fabric",
+    "tier": "1",
+    "discovery": {
+      "type": "dynamic",
+      "hasObjectDiscovery": true,
+      "hasFieldDiscovery": true,
+      "hasCustomObjectDiscovery": true,
+      "hasCustomFieldDiscovery": true
+    }
+  },
+  "operation": {
+    "name": "Replace",
+    "objectName": "UpdateEntityRecordV2",
+    "objectDisplayName": "Update Entity Record",
+    "httpMethod": "PUT",
+    "path": "/v2/{entityName}/UpdateEntityRecord",
+    "subType": "standard",
+    "supportsStreaming": false,
+    "activityType": "Curated",
+    "schemaAction": {
+      "name": "GenerateSchema",
+      "parents": [
+        "entityName"
+      ],
+      "replaces": "both"
+    },
+    "pathTemplate": "/v2/{entityName}/UpdateEntityRecord",
+    "parameters": [
+      {
+        "name": "entityName",
+        "type": "path",
+        "dataType": "string",
+        "required": true,
+        "displayName": "Entity",
+        "description": "Enter entity name",
+        "reference": {
+          "objectName": "system",
+          "lookupNames": [
+            "name"
+          ],
+          "lookupValue": "name",
+          "path": "/standard-objects-hybrid"
+        }
+      },
+      {
+        "name": "recordId",
+        "type": "query",
+        "dataType": "string",
+        "required": true,
+        "displayName": "Record ID",
+        "description": "Enter Record ID to update the corresponding record"
+      },
+      {
+        "name": "expansionLevel",
+        "type": "query",
+        "dataType": "integer",
+        "required": false,
+        "displayName": "Record level depth",
+        "description": "Specify the depth of related records to be retrieved from the service. This property supports values from 1 to 3.",
+        "defaultValue": 3
+      }
+    ]
+  },
+  "display": {
+    "label": "Update Entity Record",
+    "description": "Updates an existing record in a Data Fabric entity",
+    "icon": "https://alpha.uipath.com/311c6049-4966-4ef2-a6f3-8ceccaf38d54/studio_/typecache/icons/98381fa079bbcf73264f551006d6ef7580fb53992f3d9f94361eb5d9e06040cb.svg",
+    "iconBackground": "",
+    "iconBackgroundDark": "",
+    "operationLabel": "Update Entity Record"
+  },
+  "runtime": {
+    "bpmnType": "bpmn:SendTask",
+    "serviceType": "Intsvc.ActivityExecution",
+    "activityConfigurationVersion": "v1",
+    "requiresConnection": true,
+    "requiresFolderKey": true,
+    "requiresConnectionForSchema": true
+  },
+  "inputSchema": {
+    "fields": [
+      {
+        "name": "entityName",
+        "type": "string",
+        "required": true,
+        "description": "Enter entity name",
+        "displayName": "Entity",
+        "reference": {
+          "objectName": "system",
+          "lookupNames": [
+            "name"
+          ],
+          "lookupValue": "name",
+          "path": "/standard-objects-hybrid"
+        }
+      },
+      {
+        "name": "recordId",
+        "type": "string",
+        "required": true,
+        "description": "Enter Record ID to update the corresponding record",
+        "displayName": "Record ID"
+      },
+      {
+        "name": "expansionLevel",
+        "type": "integer",
+        "required": false,
+        "description": "Specify the depth of related records to be retrieved from the service. This property supports values from 1 to 3.",
+        "displayName": "Record level depth",
+        "enum": [
+          1,
+          2,
+          3
+        ]
+      }
+    ]
+  },
+  "outputSchema": {
+    "fields": []
+  }
+}