@uipath/maestro-builder-sdk 6.36.1 → 6.38.0

package/dist/registry/prepare/integration-service.js

@@ -0,0 +1,218 @@
+/**
+ * Prepare a connector operation the Flow node catalog does not serve, from
+ * Integration Service itself.
+ *
+ * `prepare` names an operation through `uip maestro flow registry get
+ * uipath.connector.<key>.<action>`: the registry node is the library entry's
+ * source and its `.v1def.json` sidecar. Some connectors have no node there at
+ * all, yet Integration Service serves them in full: `uip is activities list
+ * <key>` lists the curated activities with their object and HTTP method, and
+ * `uip is resources describe <key> <object> --operation <verb>` returns the
+ * path, the path/query parameters and the request and response fields. Told
+ * "op not in library", an author hand-fills `.activity('Intsvc.ActivityExecution')`
+ * tasks and gets the identity rows wrong.
+ *
+ * A BPMN connector task needs no registry node: the `sendTask` carries its own
+ * identity (`objectName`, `method`, `path`, `connectorKey`) and rows, which is
+ * exactly what the describe returns. So when the catalog serves NOTHING for the
+ * connector — not a misspelt action on a connector it does serve — this builds
+ * the library entry and a sidecar from the activity catalog and the describe,
+ * and the ordinary overlay write, descriptor regeneration and handoff follow.
+ * The sidecar is marked `synthesizedFrom: "integration-service"`: a Flow node
+ * embeds the registry's whole definition (form, handles, model), which no
+ * describe can supply, so Flow's compile and check refuse the entry with
+ * CONNECTOR_NO_FLOW_DEFINITION rather than emit a node the designer cannot open.
+ *
+ * Every `uip` call goes through the {@link BuildContext}; everything else is
+ * pure over the parsed replies.
+ */
+import { SCHEMA_VERSION, normalizeFieldKeys, pick } from "../library-build/canonical.js";
+import { SYNTHESIZED_FROM_INTEGRATION_SERVICE } from "../../core/synthesized-definition.js";
+import { isActivitiesCatalog, isConnectorGet, isDescribeOperation } from "../library-build/context.js";
+import { HTTP_METHOD_TO_OPERATION } from "../library-build/enrich.js";
+import { get, pyOr } from "../library-build/py.js";
+import { isPlainObject } from "./support.js";
+/** The marker a synthesized sidecar carries; Flow refuses a definition that has it. One owner, `core/`, so the writer and the refuser cannot drift. */
+export { SYNTHESIZED_FROM_INTEGRATION_SERVICE };
+/**
+ * The action id an activity goes by: its PascalCase name in kebab case —
+ * `CreateTestSet` → `create-test-set`, `AssignTestCasesToReq` →
+ * `assign-test-cases-to-req`, `CreateV2Attachment` → `create-v2-attachment`.
+ * A run of capitals stays one word (`GetPDFReport` → `get-pdf-report`).
+ */
+export function activityActionId(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}
+/** The curated rows of an activities listing, in the catalog's order. */
+export function curatedActivities(rows) {
+    const out = [];
+    for (const row of rows) {
+        if (!isPlainObject(row))
+            continue;
+        if (String(pyOr(get(row, "IsCurated"), "")).toLowerCase() !== "yes")
+            continue;
+        const name = String(pyOr(get(row, "Name"), "")).trim();
+        const objectName = String(pyOr(get(row, "ObjectName"), "")).trim();
+        const method = String(pyOr(get(row, "MethodName"), "")).trim().toUpperCase();
+        if (!name || !objectName || objectName === "N/A" || !method || method === "N/A")
+            continue;
+        out.push({
+            name,
+            displayName: String(pyOr(get(row, "DisplayName"), name)),
+            description: String(pyOr(get(row, "Description"), "")),
+            objectName,
+            method,
+        });
+    }
+    return out;
+}
+/**
+ * The curated activity an author's action names: by action id first
+ * (`create-test-set`), then by the activity's own name or display name,
+ * case-insensitively — `CreateTestSet`, `"Create Test Set"` and `create test set`
+ * all reach it. The spellings are compared both as given and in kebab case, so a
+ * display name with spaces matches whether or not the author kebab-cased it.
+ */
+export function matchActivity(activities, action) {
+    const wanted = action.trim().toLowerCase();
+    const wantedId = activityActionId(action.trim());
+    return (activities.find((a) => activityActionId(a.name) === wanted)
+        ?? activities.find((a) => a.name.toLowerCase() === wanted)
+        ?? activities.find((a) => a.displayName.trim().toLowerCase() === wanted)
+        ?? activities.find((a) => activityActionId(a.displayName) === wantedId));
+}
+/** The `is resources` verb an activity's HTTP method reads under; `undefined` for a verb the catalog has no describe for. */
+export function describeOperationFor(method) {
+    return HTTP_METHOD_TO_OPERATION.get(method.toUpperCase());
+}
+/**
+ * Prepare one action from Integration Service: the entry and the node the
+ * sidecar is built from, or why not.
+ */
+export async function integrationServiceEntry(ctx, input) {
+    const { connectorKey, action } = input;
+    const catalog = await isActivitiesCatalog(ctx, connectorKey);
+    if ("failure" in catalog)
+        return { miss: { kind: "no-catalog", reason: catalog.failure } };
+    const activities = curatedActivities(catalog.rows);
+    if (activities.length === 0)
+        return { miss: { kind: "no-catalog" } };
+    const activity = matchActivity(activities, action);
+    if (!activity)
+        return { miss: { kind: "no-such-activity", activities: activities.map((a) => activityActionId(a.name)) } };
+    // No guess for a method the table does not list: a describe read under the
+    // wrong verb returns another operation's path, and the entry would target it.
+    const operation = describeOperationFor(activity.method);
+    if (operation === undefined)
+        return { miss: { kind: "no-operation", activity } };
+    const described = await isDescribeOperation(ctx, connectorKey, activity.objectName, operation);
+    if (!isPlainObject(described))
+        return { miss: { kind: "no-schema", activity, operation } };
+    const connector = await isConnectorGet(ctx, connectorKey);
+    const entry = synthesizeEntry({ connectorKey, activity, operation, described, connector });
+    return { entry, action: activityActionId(activity.name), node: synthesizeNode(entry, described), activity, operation };
+}
+/**
+ * The library entry for one described activity — the shape `extractCanonical`
+ * writes from a registry node, filled from the describe instead: the IS
+ * object and verb, the path and its parameters, the request fields as the
+ * input schema. `httpMethod` keeps the catalog's spelling (`GETBYID` for a
+ * get-by-id, as registry entries do); the wire maps it. The entry goes by the
+ * activity's own action id, never the author's spelling: a display name would
+ * put spaces (or a `/`) in the overlay path and a second entry next to the id.
+ */
+export function synthesizeEntry(input) {
+    const { connectorKey, activity, operation, described, connector } = input;
+    const op = pyOr(pick(described, "Operation", "operation"), {});
+    const path = String(pyOr(pick(op, "Path", "path"), ""));
+    const method = String(pyOr(pick(op, "Method", "method"), activity.method)).toUpperCase();
+    const label = String(pyOr(pick(op, "Curated", "curated"), activity.displayName));
+    const parameters = normalizeFieldKeys(pyOr(pick(described, "Parameters", "parameters"), []));
+    const requestFields = normalizeFieldKeys(pyOr(pick(described, "RequestFields", "requestFields"), []));
+    const responseFields = normalizeFieldKeys(pyOr(pick(described, "ResponseFields", "responseFields"), []));
+    const connectorName = String(pyOr(get(connector, "Name"), connectorKey));
+    const icon = String(pyOr(get(connector, "Image"), ""));
+    const entry = {
+        schemaVersion: SCHEMA_VERSION,
+        nodeType: `uipath.connector.${connectorKey}.${activityActionId(activity.name)}`,
+        version: "1.0.0",
+        category: "connector",
+        tags: ["connector", "activity"],
+        connector: { key: connectorKey, name: connectorName },
+        operation: {
+            name: operation,
+            objectName: activity.objectName,
+            objectDisplayName: String(pyOr(pick(described, "DisplayName", "displayName"), activity.objectName)),
+            httpMethod: method,
+            path,
+            pathTemplate: path,
+            subType: "standard",
+            supportsStreaming: false,
+            activityType: "Curated",
+            parameters,
+        },
+        display: {
+            label,
+            description: activity.description || `(${connectorName}) ${label}`,
+            icon,
+            iconBackground: "",
+            iconBackgroundDark: "",
+            operationLabel: label,
+        },
+        runtime: {
+            bpmnType: "bpmn:SendTask",
+            serviceType: "Intsvc.ActivityExecution",
+            activityConfigurationVersion: "v1",
+            requiresConnection: true,
+            requiresFolderKey: true,
+            requiresConnectionForSchema: true,
+        },
+        inputSchema: { fields: requestFields },
+        outputSchema: { fields: responseFields },
+        provenance: {
+            source: SYNTHESIZED_FROM_INTEGRATION_SERVICE,
+            activity: activity.name,
+            method: activity.method,
+        },
+    };
+    return entry;
+}
+/**
+ * The node `planLibrary` turns into the `.v1def.json` sidecar — the little a
+ * BPMN compile reads of one (`inputDefinition.fields` for the body, the model's
+ * type and service type) and the marker Flow refuses on. `buildV1Definition`
+ * keeps every key here.
+ */
+export function synthesizeNode(entry, described) {
+    const e = entry;
+    const outputFields = normalizeFieldKeys(pyOr(pick(described, "ResponseFields", "responseFields"), []));
+    return {
+        nodeType: e.nodeType,
+        version: e.version,
+        category: e.category,
+        tags: e.tags,
+        display: { label: e.display.label, description: e.display.description, icon: e.display.icon },
+        model: {
+            type: "bpmn:SendTask",
+            serviceType: "Intsvc.ActivityExecution",
+            bindings: { resource: "connection", propertyAttribute: "ConnectionId" },
+            context: [
+                { name: "connectorKey", value: e.connector.key },
+                { name: "objectName", value: e.operation.objectName },
+                { name: "operation", value: e.operation.name },
+                { name: "method", value: e.operation.httpMethod },
+                { name: "path", value: e.operation.path },
+                { name: "connection", value: "" },
+                { name: "folderKey", value: "" },
+                { name: "activityConfigurationVersion", value: "v1" },
+            ],
+        },
+        inputDefinition: { fields: e.inputSchema.fields },
+        outputDefinition: { output: { fields: outputFields }, error: {} },
+        synthesizedFrom: SYNTHESIZED_FROM_INTEGRATION_SERVICE,
+    };
+}

package/dist/registry/prepare/messages.d.ts

@@ -21,7 +21,8 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal } from "../errors.js";
-import { type RegistryCatalog } from "./actions.js";
+import { type RegistryCatalog, type RegistryRefresh } from "./actions.js";
+import type { IntegrationServiceMiss } from "./integration-service.js";
 export declare const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
 export declare const PREPARE_COMMAND = "npx flow-sdk registry prepare";
@@ -101,6 +102,10 @@ export declare function unresolvedOperationMessage(input: {
     name: string;
     probes: readonly ProbeMiss[];
     catalog: RegistryCatalog;
+    /** What Integration Service said, when the catalog served nothing for the connector and IS was asked instead. */
+    integrationService?: IntegrationServiceMiss;
+    /** Whether the catalog was refreshed before that conclusion. */
+    registryRefresh?: RegistryRefresh;
 }): string;
 /**
  * A `registry get` probe failed for a reason other than "Node not found" — an
@@ -133,6 +138,41 @@ export declare function inputFieldNote(count: number | undefined | null): string
 export declare function tsNote(jsonOnly: boolean, connectorKey: string): string;
 /** The action path's success line. */
 export declare function preparedSummaryLine(nodeType: string, out: string, ts: string, variants: number, fieldNote: string): string;
+/**
+ * "The catalog serves no node for <key>", worded by what was measured: a fact
+ * after a forced pull, the local copy's answer when the pull failed or did not
+ * run (`registry get` and `registry search` answer from a copy that never
+ * refreshes itself).
+ */
+export declare function catalogServesNothingPhrase(key: string, refresh: RegistryRefresh | undefined): string;
+/** The progress line before the one `registry pull --force` the fallback runs. */
+export declare function refreshingCatalogLine(key: string): string;
+/** The warning when that pull failed; the fallback continues against the local copy. */
+export declare function catalogRefreshFailedLine(reason: string): string;
+/** The note when the author's `--action` spelling was not the entry's id. */
+export declare function actionCanonicalizedLine(given: string, actionId: string): string;
+/**
+ * What Integration Service serves when the Flow catalog serves nothing for a
+ * connector: the curated activities' action ids, so the author re-runs with
+ * one of them, or why the one they named could not be read.
+ */
+export declare function integrationServiceLines(key: string, name: string, miss: IntegrationServiceMiss, refresh?: RegistryRefresh): string[];
+/** The action path's source line when Integration Service supplied the entry. */
+export declare function preparedFromIntegrationServiceLine(key: string, activity: {
+    name: string;
+    objectName: string;
+    method: string;
+}, refresh?: RegistryRefresh): string;
+/**
+ * The pasteable BPMN call for an operation prepared from Integration Service —
+ * the only family that compiles it, so the Flow import handoff is not printed
+ * for it. Required inputs are named with their type; the rest are left to the
+ * descriptor the overlay carries.
+ */
+export declare function bpmnConnectorUsageLines(connectorKey: string, action: string, required: ReadonlyArray<{
+    name: string;
+    type: string;
+}>, boundConnection?: string, boundFolder?: string): string[];
 /** Why this run did not overwrite the overlay (`_keep_prepared_schema`). */
 export declare function keptSchemaMessage(action: string, kept: number, discarded: number): string;
 /** The set was SHAPED right but resolved to nothing new: a VALUE is wrong for this connection. */

package/dist/registry/prepare/messages.js

@@ -23,6 +23,7 @@
 import { Refusal, messageOf } from "../errors.js";
 import { commentText } from "../../core/comment-text.js";
 import { plausibleMatches } from "./actions.js";
+import { HTTP_METHOD_TO_OPERATION } from "../library-build/enrich.js";
 import { pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 export const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
@@ -178,7 +179,7 @@ function sharedTokens(wanted, candidate) {
  * offline validators accept and the runtime dispatches to the wrong operation.
  */
 export function unresolvedOperationMessage(input) {
-    const { connectorKey: key, name, probes, catalog } = input;
+    const { connectorKey: key, name, probes, catalog, integrationService, registryRefresh } = input;
     const lines = [
         `${PREFIX}\`${key} ${name}\` is neither an action nor an event the registry serves:`,
         ...probeLines(probes),
@@ -221,6 +222,8 @@ export function unresolvedOperationMessage(input) {
     else {
         lines.push("", `\`registry search ${key}\` lists no action for ${key} either.`);
     }
+    if (integrationService !== undefined)
+        lines.push("", ...integrationServiceLines(key, name, integrationService, registryRefresh));
     lines.push("", "`registry get` and `registry search` answer from the CLI's local copy of the catalog.", "If it looks stale, refresh it first: `uip maestro flow registry pull --force`.", 
     // Named `flow` on purpose, whatever family you are authoring: this is the
     // catalog `prepare` itself reads, and `uip maestro bpmn registry pull` fills
@@ -311,6 +314,84 @@ export function tsNote(jsonOnly, connectorKey) {
 export function preparedSummaryLine(nodeType, out, ts, variants, fieldNote) {
     return `${PREFIX}${nodeType} → ${out}/ (${ts}, ${variants} variant(s), ${fieldNote})`;
 }
+/**
+ * "The catalog serves no node for <key>", worded by what was measured: a fact
+ * after a forced pull, the local copy's answer when the pull failed or did not
+ * run (`registry get` and `registry search` answer from a copy that never
+ * refreshes itself).
+ */
+export function catalogServesNothingPhrase(key, refresh) {
+    if (refresh?.ok === true)
+        return `the Flow node catalog, refreshed with \`uip maestro flow registry pull --force\`, serves no node for ${key}`;
+    const why = refresh === undefined ? "it was not refreshed" : `refreshing it failed: ${refresh.reason}`;
+    return `the CLI's local copy of the Flow node catalog serves no node for ${key} (${why})`;
+}
+/** The progress line before the one `registry pull --force` the fallback runs. */
+export function refreshingCatalogLine(key) {
+    return `  the local catalog copy serves no node for ${key}; refreshing it (uip maestro flow registry pull --force) and looking again.`;
+}
+/** The warning when that pull failed; the fallback continues against the local copy. */
+export function catalogRefreshFailedLine(reason) {
+    return `${PREFIX}registry pull --force failed (${reason}); continuing with the local catalog copy, which may be stale.`;
+}
+/** The note when the author's `--action` spelling was not the entry's id. */
+export function actionCanonicalizedLine(given, actionId) {
+    return `  action: "${given}" is Integration Service activity ${actionId}; the entry is written under that id.`;
+}
+/**
+ * What Integration Service serves when the Flow catalog serves nothing for a
+ * connector: the curated activities' action ids, so the author re-runs with
+ * one of them, or why the one they named could not be read.
+ */
+export function integrationServiceLines(key, name, miss, refresh) {
+    const phrase = catalogServesNothingPhrase(key, refresh);
+    const head = `${phrase[0].toUpperCase()}${phrase.slice(1)}, so Integration Service was asked instead (\`uip is activities list ${key}\`).`;
+    if (miss.kind === "no-catalog") {
+        return miss.reason === undefined
+            ? [head, `It lists no curated activity for ${key} either — the connector may need enabling on this tenant, or the key may be misspelt.`]
+            : [head, `That call failed: ${miss.reason}`, "Fix that (the connection, the login, the connector's enablement on this tenant), then re-run."];
+    }
+    if (miss.kind === "no-operation") {
+        return [
+            head,
+            `It lists \`${name}\` (${miss.activity.name}: ${miss.activity.objectName} ${miss.activity.method}), but ${miss.activity.method} maps to no`,
+            `\`is resources\` operation (${[...HTTP_METHOD_TO_OPERATION.keys()].join(", ")} do), so there is no describe to prepare it from.`,
+            "Author it as an `.activity('Intsvc.ActivityExecution')` task from `uip is activities list` and `uip is resources describe` by hand.",
+        ];
+    }
+    if (miss.kind === "no-schema") {
+        return [
+            head,
+            `It lists \`${name}\` (${miss.activity.name}: ${miss.activity.objectName} ${miss.activity.method}), but`,
+            `\`uip is resources describe ${key} ${miss.activity.objectName} --operation ${miss.operation} --connection-id <id>\` returned no schema for it,`,
+            "so there is nothing to prepare from. Check the connection, then re-run.",
+        ];
+    }
+    const close = plausibleMatches(name, miss.activities);
+    const lines = [head];
+    if (close.length > 0)
+        lines.push(`Closest activity to "${name}": ${close.slice(0, 3).join(", ")}`);
+    lines.push(`Activities Integration Service serves for ${key} (re-run with one as --action):`, ...miss.activities.map((a) => `  ${a}`));
+    return lines;
+}
+/** The action path's source line when Integration Service supplied the entry. */
+export function preparedFromIntegrationServiceLine(key, activity, refresh) {
+    return (`  source: Integration Service activity ${activity.name} (${activity.objectName} ${activity.method}) — ${catalogServesNothingPhrase(key, refresh)}, `
+        + "so this operation compiles in BPMN only (a Flow step or agent tool needs the registry's node definition).");
+}
+/**
+ * The pasteable BPMN call for an operation prepared from Integration Service —
+ * the only family that compiles it, so the Flow import handoff is not printed
+ * for it. Required inputs are named with their type; the rest are left to the
+ * descriptor the overlay carries.
+ */
+export function bpmnConnectorUsageLines(connectorKey, action, required, boundConnection = "<binding-name>", boundFolder = "<folder-binding-name>") {
+    const inputs = required.map((f) => `${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(f.name) ? f.name : JSON.stringify(f.name)}: /* ${commentText(f.type)}, required */`).join(", ");
+    return [
+        `.connector("<id>", "${connectorKey}", "${action}", { ${inputs} }, { connection: "${boundConnection}", folder: "${boundFolder}" })`,
+        "this operation was prepared from Integration Service, so it compiles in BPMN only; `bpmn check` and `bpmn compile` read the overlay from ./connectors-local (or --connectors-local <dir>).",
+    ];
+}
 /** Why this run did not overwrite the overlay (`_keep_prepared_schema`). */
 export function keptSchemaMessage(action, kept, discarded) {
     return (`${PREFIX}kept the prepared schema for ${action} ` +

package/dist/registry/prepare/pipeline.js

@@ -35,12 +35,13 @@ import { enrichEntry } from "../library-build/enrich.js";
 import { expandGenericForConnector, genericTemplatesByOp } from "../library-build/generic-expand.js";
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
-import { registryCatalog } from "./actions.js";
+import { refreshRegistryCatalog, registryCatalog } from "./actions.js";
 import { chooseConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, solutionConnectionIds, } from "./connections.js";
 import { prepareEvent } from "./event.js";
+import { integrationServiceEntry } from "./integration-service.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, bpmnConnectorUsageLines, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedFromIntegrationServiceLine, actionCanonicalizedLine, catalogRefreshFailedLine, refreshingCatalogLine, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
 import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
 import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
@@ -326,13 +327,21 @@ export async function prepareConnector(options, ports) {
         return prepareConnector({ ...options, ...labels, connectionId: chosenId, refreshLookups: true }, ports);
     }
 }
-/** Everything after stage 0, against one settled connection. */
-async function prepareOnConnection(options, ports, connected) {
+/**
+ * Everything after stage 0, against one settled connection. `registryRefresh`
+ * is set on the one re-entry after `registry pull --force` (below), so the
+ * pull runs at most once per command.
+ */
+async function prepareOnConnection(options, ports, connected, registryRefresh) {
     const cwd = ports.cwd ?? process.cwd();
     const info = (line) => ports.reporter.info(line);
     const warn = (line) => ports.reporter.warn(line);
     const command = ports.prepareCommand ?? PREPARE_COMMAND;
-    const { connectorKey, action } = options;
+    const { connectorKey } = options;
+    // Rebound to the activity's own action id when Integration Service supplies
+    // the entry, so the overlay path, the summary and the handoff all spell the
+    // id the entry goes by rather than the author's `--action`.
+    let action = options.action;
     const fieldPairs = options.fields ?? [];
     const parentFields = parseFields(fieldPairs);
     const outShown = options.out ?? defaultOverlayOut(cwd);
@@ -341,7 +350,8 @@ async function prepareOnConnection(options, ports, connected) {
     const jsonOnly = options.jsonOnly ?? false;
     const { connectionId, bound, rollback } = connected;
     const ctx = createBuildContext({ client: ports.client, caches: ports.caches ?? memoryCaches(), reporter: ports.reporter, concurrency: 1, timeoutMs: ports.timeoutMs }, { connectionId, parentFields });
-    const nodeType = `uipath.connector.${connectorKey}.${action}`;
+    let nodeType = `uipath.connector.${connectorKey}.${action}`;
+    let fromIntegrationService;
     const actionProbe = await registryProbe(ctx, nodeType);
     if ("miss" in actionProbe) {
         // Not an activity. Connector EVENTS live one namespace over, and their
@@ -375,20 +385,52 @@ async function prepareOnConnection(options, ports, connected) {
             throw new PrepareRefusal(registryGetFailedMessage(connectorKey, action, probes), "REGISTRY_GET_FAILED");
         }
         const catalog = await registryCatalog(ports.client, connectorKey, ports.timeoutMs);
-        throw new PrepareRefusal(unresolvedOperationMessage({ connectorKey, name: action, probes, catalog }), "OPERATION_UNKNOWN");
+        // A catalog that serves NOTHING for the connector — no action, no event, and
+        // the search itself answered — is a connector the Flow registry does not
+        // carry, not a misspelt action on one it does. Integration Service still
+        // serves it, and a BPMN connector task needs nothing more.
+        if (catalog.failure === undefined && catalog.actions.length === 0 && catalog.events.length === 0) {
+            // The probes and the search answer from the CLI's local catalog copy,
+            // which never refreshes itself. Pull once and look again before
+            // concluding anything: a stale copy would send a connector the catalog
+            // does serve down the BPMN-only path, and the summary would state it.
+            if (registryRefresh === undefined) {
+                info(refreshingCatalogLine(connectorKey));
+                const refreshed = await refreshRegistryCatalog(ports.client, ports.timeoutMs);
+                if (!refreshed.ok)
+                    warn(catalogRefreshFailedLine(refreshed.reason));
+                return prepareOnConnection(options, ports, connected, refreshed);
+            }
+            const prepared = await integrationServiceEntry(ctx, { connectorKey, action });
+            if ("miss" in prepared) {
+                throw new PrepareRefusal(unresolvedOperationMessage({ connectorKey, name: action, probes, catalog, integrationService: prepared.miss, registryRefresh }), "OPERATION_UNKNOWN");
+            }
+            info(preparedFromIntegrationServiceLine(connectorKey, prepared.activity, registryRefresh));
+            if (prepared.action !== action)
+                info(actionCanonicalizedLine(action, prepared.action));
+            action = prepared.action;
+            nodeType = prepared.entry.nodeType;
+            fromIntegrationService = prepared;
+        }
+        else {
+            throw new PrepareRefusal(unresolvedOperationMessage({ connectorKey, name: action, probes, catalog }), "OPERATION_UNKNOWN");
+        }
     }
-    const payload = ctx.caches.registry.read(actionProbe.name);
+    // The registry reply this entry came from, or none when Integration Service
+    // supplied it — then there is no node to read parents from and the sidecar
+    // is built from the synthesized node instead.
+    const payload = fromIntegrationService === undefined && "name" in actionProbe ? ctx.caches.registry.read(actionProbe.name) : undefined;
     // The registry's own declaration of parent inputs, read from the same reply.
-    const declared = declaredParents(payload);
-    let entry = extractCanonical(nodeOf(payload));
+    const declared = payload === undefined ? [] : declaredParents(payload);
+    let entry = fromIntegrationService?.entry ?? extractCanonical(nodeOf(payload));
     if (entry === undefined)
         throw new PrepareRefusal(noCanonicalEntryMessage(nodeType), "NO_CANONICAL_ENTRY");
     if (options.version)
         entry.version = options.version;
     if (parentFields.size > 0) {
-        const request = objectActionRequest(payload, parentFields);
+        const request = payload === undefined ? undefined : objectActionRequest(payload, parentFields);
         if (request === undefined) {
-            throw new PrepareRefusal(parentFieldNamesMismatchMessage([...parentFields.keys()], objectActionSpecs(payload)), "PARENT_FIELDS_MISMATCH");
+            throw new PrepareRefusal(parentFieldNamesMismatchMessage([...parentFields.keys()], payload === undefined ? [] : objectActionSpecs(payload)), "PARENT_FIELDS_MISMATCH");
         }
         entry.operation.customFieldsRequestDetails = request;
     }
@@ -422,11 +464,14 @@ async function prepareOnConnection(options, ports, connected) {
     else {
         if (objectName || options.allObjects)
             throw new PrepareRefusal(objectFlagsOnlyForGenericMessage(), "OBJECT_NOT_GENERIC");
-        entry = await enrichEntry(ctx, entry); // full schema via --connection-id
+        // An Integration Service entry IS the describe; there is nothing to enrich it with.
+        if (fromIntegrationService === undefined)
+            entry = await enrichEntry(ctx, entry); // full schema via --connection-id
         preparedEntries = [entry];
     }
     const entryNodeType = entry.nodeType;
-    const plan = planLibrary(preparedEntries, (requestedNodeType) => (requestedNodeType === entryNodeType ? nodeOf(payload) : undefined));
+    const sidecarNode = fromIntegrationService?.node ?? nodeOf(payload);
+    const plan = planLibrary(preparedEntries, (requestedNodeType) => (requestedNodeType === entryNodeType ? sidecarNode : undefined));
     for (const line of plan.warnings)
         warn(line);
     const kept = keepPreparedSchema(out, entryNodeType, plan.files, parentFields, objectName);
@@ -501,7 +546,20 @@ async function prepareOnConnection(options, ports, connected) {
             warn(missingParentsNote(connectorKey, action, actionParents, missing, parentFields, command));
         }
     }
-    if (!jsonOnly) {
+    if (fromIntegrationService !== undefined) {
+        // BPMN is the family that compiles this entry, so the handoff is its call,
+        // whether or not a module was generated; the Flow import is never repointed.
+        const required = fromIntegrationService.entry.inputSchema?.fields ?? [];
+        const params = fromIntegrationService.entry.operation.parameters ?? [];
+        const fields = [
+            ...params.filter((f) => f.required === true).map((f) => ({ name: String(f.name), type: String(f.dataType ?? "string") })),
+            ...required.filter((f) => f.required === true).map((f) => ({ name: String(f.name), type: String(f.type ?? f.dataType ?? "string") })),
+        ];
+        for (const line of bpmnConnectorUsageLines(connectorKey, action, fields, pyOr(bound?.connection, "<binding-name>"), pyOr(bound?.folder, "<folder-binding-name>"))) {
+            info(nextLine(line));
+        }
+    }
+    else if (!jsonOnly) {
         // Print what was bound, so the last line of output is a call the reader
         // can paste rather than `<binding-name>` placeholders. `or`, not `??`: an
         // empty symbolic name is a placeholder in Python's eyes too.

package/dist/registry/uip/commands.d.ts

@@ -17,7 +17,15 @@ export declare function connectionArgs(connectionId?: string): string[];
 export declare function fieldArgs(parentFields: ReadonlyMap<string, string> | Readonly<Record<string, string>> | undefined): string[];
 export declare function registrySearchConnectors(): string[];
 export declare function registrySearch(query: string): string[];
+/**
+ * `uip maestro flow registry pull --force`: refresh the CLI's local copy of the
+ * Flow node catalog, which `registry get` and `registry search` answer from and
+ * which never refreshes itself.
+ */
+export declare function registryPull(): string[];
 export declare function registryGet(nodeType: string, connectionId?: string): string[];
+/** `uip is activities list <key> --output json`: the connector's activity catalog — curated activities with their object and HTTP method, and the generic record verbs. No connection needed. */
+export declare function isActivitiesList(connectorKey: string): string[];
 export declare function isConnectorsMetadata(connectorKey: string): string[];
 export declare function isResourcesDescribeOperation(connectorKey: string, objectName: string, operation: string, connectionId?: string, parentFields?: ReadonlyMap<string, string> | Readonly<Record<string, string>>): string[];
 export declare function isResourcesDescribeObject(connectorKey: string, objectName: string, connectionId?: string): string[];

package/dist/registry/uip/commands.js

@@ -28,9 +28,21 @@ export function registrySearchConnectors() {
 export function registrySearch(query) {
     return [UIP, "maestro", "flow", "registry", "search", query, "--output", "json"];
 }
+/**
+ * `uip maestro flow registry pull --force`: refresh the CLI's local copy of the
+ * Flow node catalog, which `registry get` and `registry search` answer from and
+ * which never refreshes itself.
+ */
+export function registryPull() {
+    return [UIP, "maestro", "flow", "registry", "pull", "--force"];
+}
 export function registryGet(nodeType, connectionId) {
     return [UIP, "maestro", "flow", "registry", "get", nodeType, "--output", "json", ...connectionArgs(connectionId)];
 }
+/** `uip is activities list <key> --output json`: the connector's activity catalog — curated activities with their object and HTTP method, and the generic record verbs. No connection needed. */
+export function isActivitiesList(connectorKey) {
+    return [UIP, "is", "activities", "list", connectorKey, "--output", "json"];
+}
 export function isConnectorsMetadata(connectorKey) {
     return [UIP, "is", "connectors", "metadata", connectorKey, "--output", "json"];
 }

package/dist/serialize.js

@@ -22,6 +22,7 @@ import { resolveVersionCarried } from './core/nodes/versioned.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
 import { formFieldJsonSchema, formFieldSettingsWire, wireFormFieldType } from './core/form-field-type.js';
 import { ConnectorResolveError } from './core/connector-resolve-error.js';
+import { synthesizedDefinitionRefusal } from './core/synthesized-definition.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
@@ -5225,6 +5226,10 @@ export function serialize(built, opts = {}) {
                     addEdge(scope, t, id);
                 return [{ node: id, port: successPort(type) }];
             }
+            // An entry `prepare` synthesized from Integration Service compiles in BPMN only.
+            const noDefinition = synthesizedDefinitionRefusal(rc);
+            if (noDefinition)
+                throw noDefinition;
             const id = stepUid(scope, step.name);
             const node = makeNode(rc.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def: rc.v1def });
             declareListOutputType(node, rc);
@@ -5594,6 +5599,12 @@ export function serialize(built, opts = {}) {
                     if (!opts.library)
                         throw new Error(`inline agent "${step.name}"'s connector tool needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
                     const rc = opts.library.resolve(tr.connector, tr.operation, tr.version, tr.object);
+                    // An entry `prepare` synthesized from Integration Service compiles in
+                    // BPMN only — for a tool as for a step: `connectorToolDef` reads the
+                    // same definition, and a synthesized one has no form or handles.
+                    const noDefinition = synthesizedDefinitionRefusal(rc);
+                    if (noDefinition)
+                        throw noDefinition;
                     tdef = connectorToolDef(rc);
                     label = tr.name ?? rc.v1def?.display?.label ?? tr.operation;
                     // The connection rides the same three places it does for a

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"
     }
   ]
 }