Uipath Maestro Bpmn

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

UiPath Maestro BPMN — TypeScript Builder SDK

Author a Maestro process as a typed BPMN graph and compile it to .bpmn XML. Builder methods map directly to events, gateways, activities, sub-processes, variables, bindings, and sequence flows.

Use this file as a router. Read only the reference named by the capability you need, then let TypeScript and bpmn check provide the detailed contract.

Workflow

1. Scaffold the project first: uip maestro bpmn init <Name>. It writes <Name>/<Name>.bpmn plus project.uiproj, operate.json, entry-points.json, bindings_v2.json, and package-descriptor.json — the layout bpmn pack and product tooling require. Run it inside a solution to join that solution; run it outside one and a parent <Name>Solution is scaffolded around it.
2. Keep <Name>.bpmn.ts at the workspace root, beside package.json.
3. Import from @uipath/maestro-builder-sdk/bpmn and default-export a chain ending in .build().
4. Seed the source by decompiling the stub bpmn init wrote — uip maestro bpmn decompile <Name>/<Name>.bpmn -o <Name>.bpmn.ts --style nested — rather than hand-writing the skeleton. --style nested lifts an existing process's boundary events, gateways and event sub-processes into the nesting constructs, writes the top level in order (flowMode('sequence')), and leaves whatever it cannot prove flat with a printed reason; the compiled graph is verified identical before it is written. It KEEPS the flow ids the constructs now imply: an import's edge_… is pinned back onto the implied edge with a .flowIds([…]) call at the top of the chain, so the recompile reproduces the ids the artifact arrived with. That matters for brownfield work — bpmn merge keys every element by id, flows included, so a renamed flow reads as a new one, the original is deleted with its diagram edge, and a gateway default left naming the old id produces a file validate rejects. --keep-flow-ids now only confines the lift to regions whose ids already match, for source with no pin table, at the cost of lifting far less. Without --style nested the whole process is written flat. It carries the process id and the entryPointId UUID the product assigned, which a hand-written chain cannot invent. An existing project needs no init: seed from the .bpmn already there. For shape, copy the closest staged examples/*.bpmn.ts. Two things it does to the declaration blocks, both reported: it DROPS bindings nothing references (--keep-unused-bindings keeps them) and it writes .preserve({ … }) for state the document carried that nothing derives. Leave the .preserve call alone; see Process contract.
5. Run uip maestro bpmn check <Name>.bpmn.ts --source after structural changes.
6. Compile into the scaffolded project, then format it, then refresh it, then run product validation — in that order, every time. validate refuses a file with no diagram (BPMN_PARSE_ERROR: No diagrams found), and compile writes none; format adds it. Exactly one emitted <Name>.bpmn may exist, at <Name>/<Name>.bpmn; do not leave a second copy at the workspace root, and do not leave the template init wrote in place of your compiled output.
7. refresh is part of the loop, not part of packaging. init generates entry-points.json and operate.json once, naming the start event of the template it wrote (Event_start); they do not follow source edits. Author a start event with any other id — which authoring from your own chain always does — and step 6's validator fails on the mismatch: entry-points.json references start event "Event_start" via filePath, but no <bpmn:startEvent id="Event_start"> exists. uip maestro bpmn refresh <project-path> regenerates both from the compiled BPMN. Run it after any edit that changes a start event id or adds or removes an entry point. It validates before it writes, so lay the diagram out first (format) or it fails with MISSING_DI_SHAPE, and it needs an init-generated project — with no project.uiproj it has nothing to regenerate.
8. Use the merge pipeline for targeted edits to an existing process.

API index

Indexed in the INSTALLED PACKAGE, not here, because a .d.ts line span is only true of the build that emitted it. The @uipath/maestro-builder-sdk package ships dist/api-members.md, keyed by field or method name (gateway), and dist/api-index.md, keyed by exported symbol (BpmnBuilder). Match one name — do not read either end to end — then read the span it gives you: the whole declaration, doc comment included. Both cover all three entry points; each file's own header spells the paths its rows are relative to.

Capability router

Minimal shape

import { bpmn } from '@uipath/maestro-builder-sdk/bpmn';

export default bpmn('notify')
  .name('Notify')
  .flowMode('sequence')
  .var('status', 'string')
  .startEvent('start')
  .task('record', { set: { status: 'ready' } })
  .endEvent('done')
  .build();

In sequence mode each element continues to the next, so a process written top to bottom has no .sequenceFlow(); branch with .choose(), attach handlers in an activity's body, and read bpmn check --graph to see the wiring that resulted. The explicit form — .sequenceFlow('start', 'record') after the elements, in the default mode — is what bpmn decompile writes for an import unless --style nested lifts it, and both forms mix freely.