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
- 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.
- Keep
<Name>.bpmn.ts at the workspace root, beside package.json.
- Import from
@uipath/flow-sdk/bpmn and default-export a chain ending in .build().
- Start from the closest staged
examples/*.bpmn.ts.
- Run
uip maestro bpmn check <Name>.bpmn.ts --source after structural changes.
- Compile into the scaffolded project, format only when layout is needed, and run
product validation. 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.
- Use the merge pipeline for targeted edits to an existing process.
Capability router
| Surface |
Builder/API |
Reference |
Example |
| Process and nested scopes |
bpmn, subProcess |
Builders |
examples/NotifyChannel.bpmn.ts |
| Variables, inputs, and outputs |
var, input, output, schema |
ScopeBuilder |
examples/NotifyChannel.bpmn.ts |
| Start, end, catch, throw, boundary |
event methods |
Events |
examples/NotifyChannel.bpmn.ts |
| Exclusive, inclusive, parallel, event-based |
gateway methods |
GatewayOpts |
examples/NotifyChannel.bpmn.ts |
| Script and assignment tasks |
scriptTask, task |
ScopeBuilder |
examples/NotifyChannel.bpmn.ts |
| HTTP requests |
http |
HTTP |
examples/NotifyChannel.bpmn.ts |
| Orchestrator jobs and queues |
start/execute/queue methods |
Work dispatch |
examples/NotifyChannel.bpmn.ts |
| Human work |
humanTask |
Human tasks |
examples/NotifyChannel.bpmn.ts |
| Connectors and external work |
connector, externalAgent, externalWorkflow |
Connections |
examples/NotifyChannel.bpmn.ts |
| Generic registry activity |
activity |
ActivityNodeOpts |
examples/NotifyChannel.bpmn.ts |
| Existing BPMN |
bpmn decompile, compile, merge |
Brownfield |
examples/NotifyChannel.bpmn.ts |
| Process metadata, package, and layout |
metadata, project metadata, bpmn format |
Contract metadata |
examples/NotifyChannel.bpmn.ts |
Minimal shape
import { bpmn } from '@uipath/flow-sdk/bpmn';
export default bpmn('notify')
.name('Notify')
.startEvent('start')
.task('record', { set: { status: 'ready' } })
.endEvent('done')
.sequenceFlow('start', 'record')
.sequenceFlow('record', 'done')
.build();
Validation loop
uip maestro bpmn init <Name> # once, before authoring
uip maestro bpmn check <Name>.bpmn.ts --source
uip maestro bpmn compile <Name>.bpmn.ts -o <Name>/<Name>.bpmn
uip maestro bpmn format <Name>/<Name>.bpmn
uip maestro bpmn validate <Name>/<Name>.bpmn --output json
check owns source and graph invariants. Product validation owns the compiled
BPMN contract. Change the TypeScript source and rebuild; do not patch emitted XML.
Evidence boundary
Static success does not prove tenant resource resolution, human outcomes, or
runtime-only values. Read BPMN runtime decisions
when the requested outcome depends on those behaviors.
1---2name: uipath-maestro-bpmn-23description: TRIGGER for authoring structural-core UiPath Maestro BPMN as `<Name>.bpmn.ts` with the TypeScript builder SDK (`@uipath/flow-sdk/bpmn`) and running the `uip maestro bpmn` check/compile/format/validate loop. Covers events, gateways, tasks, sub-processes, sequence flows, bindings, static rules, and semantic `.bpmn` output. Flow builder authoring → uipath-maestro-flow; case plans → uipath-maestro-case. DO NOT TRIGGER for registry-backed typed BPMN nodes beyond the structural core.4---5<!--6Provenance: snapshot of UiPath/flow-builder-sdk7`typescript/sdk/skill/SKILL-bpmn.md` @ 4aa3d67. Canonical source lives there;8edit upstream and re-sync (see UiPath/flow-builder-sdk#405).9-->1011# UiPath Maestro BPMN — TypeScript Builder SDK1213Author a Maestro process as a typed BPMN graph and compile it to `.bpmn` XML.14Builder methods map directly to events, gateways, activities, sub-processes,15variables, bindings, and sequence flows.1617Use this file as a router. Read only the reference named by the capability you18need, then let TypeScript and `bpmn check` provide the detailed contract.1920## Workflow21221. Scaffold the project first: `uip maestro bpmn init <Name>`. It writes23 `<Name>/<Name>.bpmn` plus `project.uiproj`, `operate.json`, `entry-points.json`,24 `bindings_v2.json`, and `package-descriptor.json` — the layout `bpmn pack` and25 product tooling require. Run it inside a solution to join that solution; run it26 outside one and a parent `<Name>Solution` is scaffolded around it.272. Keep `<Name>.bpmn.ts` at the workspace root, beside `package.json`.283. Import from `@uipath/flow-sdk/bpmn` and default-export a chain ending in `.build()`.294. Start from the closest staged `examples/*.bpmn.ts`.305. Run `uip maestro bpmn check <Name>.bpmn.ts --source` after structural changes.316. Compile **into the scaffolded project**, format only when layout is needed, and run32 product validation. Exactly one emitted `<Name>.bpmn` may exist, at33 `<Name>/<Name>.bpmn`; do not leave a second copy at the workspace root, and do not34 leave the template `init` wrote in place of your compiled output.357. Use the merge pipeline for targeted edits to an existing process.3637## Capability router3839| Surface | Builder/API | Reference | Example |40|---|---|---|---|41| Process and nested scopes | `bpmn`, `subProcess` | [Builders](references/api.md#bpmnbuilder-class) | `examples/NotifyChannel.bpmn.ts` |42| Variables, inputs, and outputs | `var`, `input`, `output`, `schema` | [ScopeBuilder](references/api.md#scopebuilder-class) | `examples/NotifyChannel.bpmn.ts` |43| Start, end, catch, throw, boundary | event methods | [Events](references/bpmn-runtime.md#events-and-timers) | `examples/NotifyChannel.bpmn.ts` |44| Exclusive, inclusive, parallel, event-based | gateway methods | [GatewayOpts](references/api.md#gatewayopts-interface) | `examples/NotifyChannel.bpmn.ts` |45| Script and assignment tasks | `scriptTask`, `task` | [ScopeBuilder](references/api.md#scopebuilder-class) | `examples/NotifyChannel.bpmn.ts` |46| HTTP requests | `http` | [HTTP](references/bpmn-runtime.md#http-and-orchestrator-work) | `examples/NotifyChannel.bpmn.ts` |47| Orchestrator jobs and queues | start/execute/queue methods | [Work dispatch](references/bpmn-runtime.md#http-and-orchestrator-work) | `examples/NotifyChannel.bpmn.ts` |48| Human work | `humanTask` | [Human tasks](references/bpmn-runtime.md#human-task-outcomes) | `examples/NotifyChannel.bpmn.ts` |49| Connectors and external work | `connector`, `externalAgent`, `externalWorkflow` | [Connections](references/bpmn-runtime.md#connectors-and-bindings) | `examples/NotifyChannel.bpmn.ts` |50| Generic registry activity | `activity` | [ActivityNodeOpts](references/api.md#activitynodeopts-interface) | `examples/NotifyChannel.bpmn.ts` |51| Existing BPMN | `bpmn decompile`, `compile`, `merge` | [Brownfield](references/bpmn-runtime.md#brownfield-editing) | `examples/NotifyChannel.bpmn.ts` |52| Process metadata, package, and layout | `metadata`, project metadata, `bpmn format` | [Contract metadata](references/bpmn-runtime.md#contract-metadata) | `examples/NotifyChannel.bpmn.ts` |5354## Minimal shape5556```ts57import { bpmn } from '@uipath/flow-sdk/bpmn';5859export default bpmn('notify')60 .name('Notify')61 .startEvent('start')62 .task('record', { set: { status: 'ready' } })63 .endEvent('done')64 .sequenceFlow('start', 'record')65 .sequenceFlow('record', 'done')66 .build();67```6869## Validation loop7071```bash72uip maestro bpmn init <Name> # once, before authoring73uip maestro bpmn check <Name>.bpmn.ts --source74uip maestro bpmn compile <Name>.bpmn.ts -o <Name>/<Name>.bpmn75uip maestro bpmn format <Name>/<Name>.bpmn76uip maestro bpmn validate <Name>/<Name>.bpmn --output json77```7879`check` owns source and graph invariants. Product validation owns the compiled80BPMN contract. Change the TypeScript source and rebuild; do not patch emitted XML.8182## Evidence boundary8384Static success does not prove tenant resource resolution, human outcomes, or85runtime-only values. Read [BPMN runtime decisions](references/bpmn-runtime.md)86when the requested outcome depends on those behaviors.
uipath