Uipath Maestro Flow

<!-- CANONICAL — edit here, not in UiPath/flow-builder-sdk. Why: docs/SKILLS_PROMOTION_PLAN.md in that repo. -->

UiPath Flow — TypeScript Builder SDK

UiPath Flow orchestrations can be authored in TypeScript using the @uipath/maestro-builder-sdk package. The SDK provides a builder API to construct a Flow graph, allowing developers to define inputs, outputs, steps, and control flow in a type-safe manner. The graph is "compiled" down to a Flow JSON, which is the artifact used for executing the Flow on the UiPath platform. An existing Flow JSON can also be decompiled back into TypeScript for editing.

Project layout

@uipath/maestro-builder-sdk is installed globally (npm install -g); examples/ contains authored examples, and references/ contains the details routed from this guide. A Flow is authored as .flow-sdk/<Name>.flow.ts inside its project folder <Solution>/<Name>/, and it imports the package directly.

Authoring files live in .flow-sdk/; the compiled artifact does not. .flow-sdk/ is the SDK's own work directory: the source, bindings.json, connectors/ and connectors-local/ all go there by default, relative to the directory you run uip from. Each Flow project keeps its own, so a solution can hold several flows; Studio Web never reads it, and uip solution pack/upload and flow debug leave it out. Run the SDK verbs (flow check, compile, decompile, merge, registry pull/prepare, node .flow-sdk/*.pipeline.mjs) from the project folder <Solution>/<Name>/, as ( cd <Solution>/<Name> && … ) when your shell does not keep its directory between commands; every .flow-sdk/ path in this guide and its references is relative to that folder. Everything else runs from the workspace root. Scaffold the project first, seed the source from it, then emit back into it — compile -o is the authority over where the emitted file is written. <Solution> and <Name> are the request's own names, used verbatim: a request that gives one name for both ("inside a solution of the same name") uses it for both, and a request that names only the Flow uses <Name> for both. Look for an existing solution before uip solution init: run find . -maxdepth 2 -name '*.uipx'. If one exists and a user can answer, ask which to use (one option per solution, then "Create a new solution", then "Something else") and scaffold nothing until they do; never create a second solution silently. Headless, use the solution the request names, else the only one present, else a new one named as above, and record the choice in the final response.

uip solution init <Solution>
( cd <Solution> && uip maestro flow init <Name> --sdk-source )
# edit <Solution>/<Name>/.flow-sdk/<Name>.flow.ts, then run the Lifecycle loop below

Do not hand-write the skeleton. --sdk-source decompiles the trigger-only artifact flow init writes into the project's .flow-sdk/<Name>.flow.ts, creating the folder; the source carries the flow id and name the product already assigned — a hand-written flow('<name>') invents an id instead. So the stub is the seed rather than litter: the first compile -o overwrites it in place. init refuses an existing source file unless --force; when the source is already there, drop --sdk-source. Maestro Automate is --automate on the same flow init: when the request names Maestro Automate as the product, run ( cd <Solution> && uip maestro flow init <Name> --automate --sdk-source ); the bare verb ("automate invoice intake") asks for a plain Flow. Nothing after init changes; the flag writes runtimeOptions.profile into operate.json plus a .maestro_automate marker (how Orchestrator and Studio Web tell the two apart), and compile -o rewrites only the .flow, so both survive.

An existing project needs no init: skip the first two commands and seed from the .flow that is already there with ( cd <Solution>/<Name> && uip maestro flow decompile <Name>.flow -o .flow-sdk/<Name>.flow.ts --no-pipeline ) (--no-pipeline skips the brownfield helper, references/brownfield.md); skip the decompile when the source already exists. The three names stay aligned: .flow-sdk/<Name>.flow.ts, the <Name> project directory, and <Name>.flow inside it. Exactly one emitted <Name>.flow may exist, at <Solution>/<Name>/<Name>.flow, and never a second copy at the workspace root — validators and evidence collectors cannot choose safely between duplicates. Emitting to the root is correct only for the packaged-SDK local gates, which never scaffold a project; pick the loop first (Lifecycle) and do not mix the two.

Install the SDK first, once per machine: npm install -g @uipath/maestro-builder-sdk; skip it when already installed, and see references/CLI-LOOP.md for the checks and failure handling.

Integrations with non-UiPath systems are handled through connectors. Choose the node before writing it. For an external service or data (weather, Slack, a REST API), run uip maestro registry search '<brand or service name>' over the local connector library, unless the request names the transport itself ("over HTTP, not a connector" means http()): a hit is a connector, "total": 0 is a miss and means http(), and a usage error means the library is not cached, so run uip maestro registry pull first. For document extraction or another tenant capability (agent, process), which that library does not hold, run the family's uip maestro flow registry search (references/ixp.md, references/agent.md). A script() returning fixed values is never a stand-in for that step, and mock() only marks a capability the search proved absent. Connectors require .flow-sdk/bindings.json. uip maestro registry pull writes a descriptor per referenced connector to .flow-sdk/connectors/<key>.ts, and caches the library itself outside the project. Prepared connector modules live at .flow-sdk/connectors-local/<key>.ts; their descriptor data is kept separately below .flow-sdk/connectors-local/descriptors/<key>/. Because the source sits in .flow-sdk/ too, it imports them as ./connectors/<key>.ts and ./connectors-local/<key>.ts.

The connector loop: author → check → prepare → check → compile

Authoring never waits on prepare: once the search above has chosen the node, no further discovery command precedes the source. Write the connector step from the task's own words — the fields you intend, lookup() tokens for ids, { object: '<name-as-the-task-said-it>' } for a generic operation — then run uip maestro flow check .flow-sdk/<Name>.flow.ts --source. Check names every prepare you owe, with the exact command: OBJECT_UNPREPARED for an unmaterialized object, CUSTOM_FIELDS_UNPREPARED for an input outside the tenant-agnostic snapshot, LOOKUP_UNRESOLVED for a lookup token with no recorded value, CONNECTOR_INPUT for a field the operation does not declare. Run that one uip maestro registry prepare <connector-key> <action> — --object, --resolve and -f compose in a single invocation, it finds the connection itself, writes .flow-sdk/bindings.json, and repoints your import at the generated ./connectors-local/<key>.ts descriptor — then re-run check and compile. Where two flows import the same connector it names them instead of guessing, and asks for --source. CONNECTOR_NOT_IN_LIBRARY, CONNECTOR_OBJECT_REQUIRED and CONNECTOR_OBJECT_NOT_GENERIC are source fixes, not prepares: connector-params.md.

Schema-dynamic operations (loadByDefault, dependent dropdowns, customFieldsRequestDetails) need the prepare check names with every required -f, and a post-compile cache check: references/connector-params.md.

Hello world Flow

import { flow, script, input, out, types } from '@uipath/maestro-builder-sdk';
export default flow('hello').name('Hello')
  .input({ name: types.string }).output({ greeting: types.string })
  .step('greet', script({ code: 'return `Hello ${$vars.start.output.name}`;' }))
  .return({ greeting: out('greet') }).build();

A script is a first-class Flow node; it runs inline JavaScript and returns a value. The start step is the default name for a "manual trigger", which carries the flow's inputs. A Flow can have outputs, which are returned to the caller when the flow completes successfully.

Lifecycle

Pick one loop before any build command; never mix them in one workspace or use one as a probe for the other (their layouts and evidence contracts differ):

• Product-CLI loop (emit-only) when the task asks for product validate/debug evidence, or the workspace is emit-only: a package.json with { "flowSdk": { "emitOnly": true } } (the product-runtime eval sets it), or FLOW_SDK_EMIT_ONLY=1. Scaffold first (Project layout), then run the block below.
• Packaged-SDK local gates otherwise: source check, compile to the root, validate — references/CLI-LOOP.md.

The uip maestro flow commands delegate their semantics to the installed @uipath/maestro-builder-sdk. Emit-only belongs to the project, not the directory you run from: the nearest package.json up the tree that declares flowSdk.emitOnly decides it, a nested one that does not mention flowSdk inherits, and emitOnly: false opts out. In that mode compile only serializes source, both flow check modes refuse, and product validate owns structural verification. The base pass is emit, any required artifact bindings, then validate:

( cd <Solution>/<Name> && uip maestro flow compile .flow-sdk/<Name>.flow.ts -o <Name>.flow )
uip maestro flow validate <Solution>/<Name>/<Name>.flow --output json
# Before anything opens the emitted file (upload, debug, a designer):
uip maestro flow format <Solution>/<Name>/<Name>.flow --output json
# Only for a stated runtime-behavior claim:
( cd <Solution> && uip solution resources refresh --solution-folder . --output json )
( cd <Solution> && uip maestro flow debug <Name> --log-level error \
  --output-filter "{status:finalStatus,instance:instanceId,url:studioWebUrl,failed:elementExecutions[?status!='Completed'].{id:elementId,status:status},<Out>:variables.globals.<Out>,incidents:incidents}" \
  --output json )

<Out>: each declared out variable, never all of variables.globals. Re-run it from compile after the last source or binding edit. Valid is top-level Result plus Data.Status: "Valid"; treat Data.Warnings as failures except the reviewed shared-connection advisory. Completed with the expected globals and an empty failed is runtime evidence; a bare exit code is not. Debug inputs, attachments, other projections and incidents: references/CLI-LOOP.md.

Editing an existing flow

In brownfield work, preserve the supplied source, step names, and unaffected wiring. Insert a step by moving the old edge through it, not by creating a second path. If only emitted .flow JSON exists, decompile it, compile the pristine baseline, edit narrowly, and merge the delta back into the original. These are before/after judgments; no final-artifact checker can prove them.

For a narrow edit, decompile writes .flow-sdk/<Name>.pipeline.mjs, which runs the loop in two invocations and gets the baseline ordering right. It keeps its baseline, edited and merged .flow files in .flow-sdk/ too:

uip maestro flow decompile <Name>.flow -o .flow-sdk/<Name>.flow.ts
node .flow-sdk/<Name>.pipeline.mjs      # captures the pristine baseline
# edit .flow-sdk/<Name>.flow.ts narrowly
node .flow-sdk/<Name>.pipeline.mjs      # compiles the edit and merges it back
uip maestro flow validate .flow-sdk/<Name>.merged.flow --output json

Validate the merged artifact, never the intermediate edited compile. If the source must stay inside the Flow project (for example, to preserve relative sidecars), keep baseline, edited, and candidate .flow files in an external .flow-work/ directory. Validate the candidate, replace the canonical artifact, and leave exactly one .flow under the project. The reference below contains the copyable safe-project sequence.

True-brownfield procedure: references/brownfield.md.

Builder frame

The quick start above shows the shape — flow(id), declarations, nodes, .return(...), .build(). Three things it does not show:

• .var(name, types.*, default?) declares a flow VARIABLE: a value more than one step writes or reads. .input and .output are the flow's contract with its caller; a var is the state in between. A step writes one with { updates: { name: <expr> } }. Inputs, outputs and vars use one of the six types the Flow CLI and Workbench offer: types.string, types.number, types.boolean, types.object, types.array, types.file. The other types members (integer, float, double, date, datetime, jsonSchema) come from the Case and BPMN builders; the Flow builder and validate accept them without an error, but Workbench does not offer them, so write a date as types.string and an integer as types.number.

• .return(...) ends a PATH. .terminate(...) ends the RUN. They look interchangeable on a straight chain and are not: inside a .parallel arm a terminate aborts the sibling arms mid-flight, where a return leaves them going.

• Expressions are how a step names something that is not a literal. There is one per kind of thing you can refer to:

  	refers to
  input(name)	a flow input
  v(name)	a flow variable
  out(step, path?)	a step's result, whole or one field
  err(step, field?)	a FAILED step's error envelope — only inside its handler
  ran(step)	whether a step ran at all, as a boolean
  lit(value)	a constant, where a raw value would be ambiguous
  js`…` / tmpl`…`	an expression, or a string, you write yourself

  ran(step) earns an early mention: when arms converge, one shared continuation usually reads better than the same work duplicated per arm, and ran is how that continuation asks whether the value it wants was produced.