Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skill-flavors/studioweb/uipath-maestro-bpmn/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ When a reference tells you to run a command that is not available, use the Studi
every error it prints (it exits non-zero) before you compile. `compile` writes what
the source says; `check` is what reports a probable mistake, such as a `vars.<id>`
read of a variable nothing declares (`EXPR_UNDECLARED_REF`) or a declared variable
read without `vars.` (`EXPR_BARE_VAR_REF`). For two of these, a read in an
read without `vars.` (`EXPR_BARE_VAR_REF`; fix: `=js:vars.<id>`). For two of these, a read in an
`errorMapping` condition and a bare `=amount`, `check` is the only offline gate:
`bpmn validate` accepts both. Studio Web ships its own SDK: an older one refuses the
read in `compile` itself.
Expand Down
7 changes: 4 additions & 3 deletions skills/uipath-maestro-bpmn/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ need, then let TypeScript and `bpmn check` provide the detailed contract.
2. Seed an existing process, or the stub `bpmn init` wrote, with `bpmn decompile`; never hand-write the skeleton (Workflow step 4).
3. Leave a `.preserve({ … })` call that `decompile` wrote alone; it carries state nothing else derives (Workflow step 4).
4. Run `uip maestro bpmn check <Name>.bpmn.ts --source` before every compile, and fix every error it prints first (Workflow step 5). `check` lints the SDK source only; it never replaces `validate`.
Author every expression as `=js:` ([exceptions](references/bpmn-runtime.md#variables-and-the-process-contract)).
5. After each compile of a new process, run `format`, then `refresh`, then `validate`, in that order (Workflow steps 6–7).
After a `merge` into an existing process, run `refresh` and `validate` only; run `format` only when `refresh` or `validate` reports `BPMN_PARSE_ERROR` with `No diagrams found`, `MISSING_DI_SHAPE` or `MISSING_DI_EDGE`, because it lays out the whole diagram again and drops the user's pools, lanes, colors and placement; after that `format`, run `refresh` and `validate` again and, unless the report was `No diagrams found`, tell the user the canvas layout was reset ([Brownfield](references/bpmn-runtime.md#brownfield-editing)).
6. A different target system (Document Understanding → agent, Outlook → Gmail) changes a node's type and binding, not the graph; reshape only when the process differs.
Expand Down Expand Up @@ -124,7 +125,7 @@ A discovery-only request (discover types or save registry evidence, no authoring
every error it prints (it exits non-zero) before you compile. `compile` writes what
the source says; `check` is what reports a probable mistake, such as a `vars.<id>`
read of a variable nothing declares (`EXPR_UNDECLARED_REF`) or a declared variable
read without `vars.` (`EXPR_BARE_VAR_REF`). For two of these, a read in an
read without `vars.` (`EXPR_BARE_VAR_REF`; fix: `=js:vars.<id>`). For two of these, a read in an
`errorMapping` condition and a bare `=amount`, `check` is the only offline gate:
`bpmn validate` accepts both.
Needs `@uipath/maestro-builder-sdk` 6.86.0 or later; an older `compile` refuses the read itself.
Expand Down Expand Up @@ -257,7 +258,7 @@ export default bpmn('approval')
t.onError(true, { errorVar: 'failure' }, (b) => b.endEvent('failed', { name: 'Approval failed' }));
})
.choose('approved', [
{ when: '=vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post') },
{ when: '=js:vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post') },
{ otherwise: true, label: 'No', body: (b) => b.task('reject') },
])
.endEvent('done')
Expand All @@ -278,7 +279,7 @@ export default bpmn('approval')
- An event sub-process guards the whole container it sits in, catching what nothing closer caught; a boundary handler guards one activity.
To fail one iteration rather than the whole run, put the `eventSubProcess` inside the multi-instance sub-process.
An error net captures the caught error on its start by default, into `vars.<net>_Error` — so `.eventSubProcess('failures', …)` gives you `vars.failures_Error`, with nothing more written. It holds a JSON string: read a field through `JSON.parse(vars.failures_Error)` ([Events and timers](references/bpmn-runtime.md#events-and-timers)). That per-net id is what the designer writes: over the real exports measured, every error capture carries a unique id with the display name `Error`, and the bare `vars.Error` appears in none of them. The `Error` spelling that IS fixed is the capture row's `source="=Error"`, the key the engine seeds the payload under, which the SDK writes for you. `errorVar` names the variable something else; `errorVar: false` omits the capture.
A boundary handler captures nothing by default; there `errorVar` is what makes the error readable, as `=vars.<errorVar>.code`.
A boundary handler captures nothing by default; there `errorVar` is what makes the error readable, as `=js:vars.<errorVar>.code`.
- `check` warns `NO_DEFAULT_FLOW` on an exclusive gateway whose every flow is conditioned; give it an `otherwise` arm or a default.
- `.flowMode('sequence')`, called before the first element, wires consecutive elements of that scope in order, so a process written top to bottom needs no `.sequenceFlow()` at all; a `.subProcess()` body inherits it and may set its own.
An element that already has an explicit outgoing flow is not also wired to the next one, a bare gateway is wired into but implies no outgoing flows, and an element nothing leads into or a path that does not end is refused at build.
Expand Down
18 changes: 9 additions & 9 deletions skills/uipath-maestro-bpmn/examples/ContractRegistry.bpmn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
*
* Every `.dataService()` writes its response to `<id>_response` and the error payload
* to `<id>_Error`, both declared for you, so the next node reads
* `=vars.create_response.Id` with nothing more written.
* `=js:vars.create_response.Id` with nothing more written.
*/
import { bpmn } from '@uipath/maestro-builder-sdk/bpmn';

Expand Down Expand Up @@ -47,7 +47,7 @@ export default bpmn('ContractRegistry')
.dataService('create', {
...df,
op: 'create',
record: { contractTitle: '=vars.contractTitle', status: 'Open', priority: 2, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
record: { contractTitle: '=js:vars.contractTitle', status: 'Open', priority: 2, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
})
// The filter is a query parameter; `start`/`limit` default to 0/100.
// `sortBy` becomes the body's `_sortFieldName` (the connector's own RequestField) and
Expand All @@ -58,19 +58,19 @@ export default bpmn('ContractRegistry')
.dataService('update', {
...df,
op: 'update',
id: '=vars.create_response.Id',
record: { contractTitle: '=vars.contractTitle', status: 'Open', priority: 1, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
id: '=js:vars.create_response.Id',
record: { contractTitle: '=js:vars.contractTitle', status: 'Open', priority: 1, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
})
.dataService('get', { ...df, op: 'get', recordId: '=vars.update_response.Id', expansionLevel: 3 })
.dataService('get', { ...df, op: 'get', recordId: '=js:vars.update_response.Id', expansionLevel: 3 })
.endEvent('done', {
name: 'Done',
payload: {
type: 'BPMN.Variables',
outputRows: [
{ name: 'createdRecord', type: 'json', var: 'createdRecord', source: '=vars.create_response' },
{ name: 'dueSoon', type: 'json', var: 'dueSoon', source: '=vars.queryDue_response' },
{ name: 'untitled', type: 'json', var: 'untitled', source: '=vars.queryUntitled_response' },
{ name: 'retrievedRecord', type: 'json', var: 'retrievedRecord', source: '=vars.get_response' },
{ name: 'createdRecord', type: 'json', var: 'createdRecord', source: '=js:vars.create_response' },
{ name: 'dueSoon', type: 'json', var: 'dueSoon', source: '=js:vars.queryDue_response' },
{ name: 'untitled', type: 'json', var: 'untitled', source: '=js:vars.queryUntitled_response' },
{ name: 'retrievedRecord', type: 'json', var: 'retrievedRecord', source: '=js:vars.get_response' },
],
},
})
Expand Down
4 changes: 4 additions & 0 deletions skills/uipath-maestro-bpmn/examples/InvoiceApproval.bpmn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
* produces from a process someone actually runs: 71 elements, wide gateway routing,
* and six node types in one graph.
*
* Its plain `=` expressions are the import's legacy C#: copy none of them, and write
* every new expression as `=js:` (`'=js:vars.total * 0.9'`), except a human-task
* form field's `value`, which stays `=vars.<id>`.
*
* | it demonstrates | as |
* | --- | --- |
* | an Integration Service **event trigger** | `.activity(…, 'Intsvc.EventTrigger')` on a start event |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,12 @@ export default bpmn('invoice-escalation')
// back to the approver; `rejected` ends the process; `approved` continues.
.choose('route', [
{
when: '=vars.decision == "Approve"',
when: '=js:vars.decision == "Approve"',
label: 'Approved',
body: (b) => b.task('markApproved', { name: 'Mark approved', set: { outcome: 'APPROVED' } }),
},
{
when: '=vars.decision == "Needs info"',
when: '=js:vars.decision == "Needs info"',
label: 'Needs info',
body: (b) => b.task('requestInfo', { name: 'Ask the vendor', set: { outcome: 'AWAITING_VENDOR' } }).goto('approve'),
},
Expand Down
38 changes: 23 additions & 15 deletions skills/uipath-maestro-bpmn/references/bpmn-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ make from syntax alone. Exact signatures remain in the generated API.
.var('scoreValue', 'number')
// … tasks write scoreValue …
.endEvent('done', { payload: { type: 'BPMN.Variables', outputRows: [
{ name: 'score', type: 'number', source: '=vars.scoreValue', var: 'score' },
{ name: 'score', type: 'number', source: '=js:vars.scoreValue', var: 'score' },
] } })
```
Never read an `.output()` before its end event; read the `.var()` instead.
Expand All @@ -48,16 +48,24 @@ make from syntax alone. Exact signatures remain in the generated API.
seeds every declaration by id. The start-event mapping that bridges each input into
an internal variable is the canvas's spelling, not a requirement.

<!-- RULE:bpmn.expression.js-for-methods -->
- A plain `=` expression is evaluated C#-style, not as JavaScript: comparisons, arithmetic and
`vars.x` reads work, a JS method call does not, and a JS property such as `.length` reads back `null` with no incident (use `.Count`). `=vars.d.toLowerCase() == "approve"` passes
validate, then faults the run (incident `400302`); in a gateway `when` it evaluates `false` and the
run takes the wrong branch. Prefix any expression that calls a JavaScript
method (`toLowerCase`, `includes`, `concat`, `map`, `JSON.parse`) with `=js:`; .NET methods
(`Contains`, `Split`, `String.IsNullOrEmpty`) work in plain `=`, as decompiled canvas expressions show.
Local `flow-debug` does not show this ([offline checks](operate.md#debug--a-controlled-studio-web-run)).
- A `.task()`'s `set` values are strings: an `=`-expression or a literal. `set: { done: true }`
fails `check` (`TS2322`) and `compile` (`value.startsWith is not a function`); write `'=true'`.
<!-- RULE:bpmn.expression.js-everywhere -->
- Write every expression you author as `=js:` JavaScript, in any field: `set`, a `when`, a row
`source`, a connector input, a loop `collection` or `completion`, a timer `date`
(`'=js:vars.total * 0.9'`, `'=js:vars.tier == "gold"'`). A plain `=` passes `check`, `compile` and
`validate`, but it is C#: the designer opens any plain expression beyond a bare variable read in its
C# editor, and a JavaScript method in it (`=vars.d.toLowerCase() == "approve"`) faults the run
(incident `400302`), or in a gateway `when` evaluates `false` and takes the wrong branch. Local
`flow-debug` does not show this ([offline checks](operate.md#debug--a-controlled-studio-web-run)).
Leave plain only what the canvas writes plain: a row `source` reading the node's own result
(`=result…`, `=response…`, `=Error`, a form field such as `=Action`, an agent output such as
`=Decision`), `=bindings.<id>`, `=iterator[0]`, the start-event row that maps a process input
(`=vars.<inputId>`), and a human-task form field's `value` (`=vars.<id>`: its runtime evaluates
UiPath expressions, not JavaScript). An imported file's existing plain `=` expressions are C#
(`examples/InvoiceApproval.bpmn.ts`): leave them as they are, and copy none of them.
In a plain `=` you keep or edit, `.length` reads back `null` with no incident: use `.Count`.
`.length` works only inside `=js:`.
- A `.task()`'s `set` values are strings: an `=js:` expression or a literal. `set: { done: true }`
fails `check` (`TS2322`) and `compile` (`value.startsWith is not a function`); write `'=js:true'`.

<!-- RULE:bpmn.variables.input-name -->
- Input values are matched to declarations by display `name` when a run starts, so an
Expand Down Expand Up @@ -233,7 +241,7 @@ make from syntax alone. Exact signatures remain in the generated API.
propertyAttribute: 'folderPath', resourceKey: 'CreditAssessment', resourceSubType: 'ProcessOrchestration' })
// …
.startAgenticProcess('assess', { process: '=bindings.childName', folder: '=bindings.childFolder',
input: { annualIncome: '=vars.annualIncome' }, outputs: { score: '=result.score' } })
input: { annualIncome: '=js:vars.annualIncome' }, outputs: { score: '=result.score' } })
```
The called process must map its outputs at its end event ([output end mapping](#variables-and-the-process-contract)),
or `result.score` is `null`.
Expand Down Expand Up @@ -301,7 +309,7 @@ make from syntax alone. Exact signatures remain in the generated API.
```

<!-- RULE:bpmn.http.url-placeholders -->
- Fill every `{name}` or `<NAME>` in an HTTP `url` before compiling, with a discovered or given value or an `=`-expression; never invent one. Nothing checks this: `check`, `compile` and `validate` all pass `/repos/{owner}/{repo}`, and the request goes out literally.
- Fill every `{name}` or `<NAME>` in an HTTP `url` before compiling, with a discovered or given value or an `=js:` expression; never invent one. Nothing checks this: `check`, `compile` and `validate` all pass `/repos/{owner}/{repo}`, and the request goes out literally.

<!-- RULE:bpmn.orchestrator.business-rule -->
- A deployed business rule is `.businessRule(id, { process, folder, input, outputs })`, nothing else.
Expand Down Expand Up @@ -405,9 +413,9 @@ binding half, which is the same for every connector-backed node.
way the platform's own tools do and needs no connector library or `prepare`
step. The response lands in `<id>_response` and the error payload in
`<id>_Error`, both declared for you — read the created record's id as
`=vars.<id>_response.Id`. Map results onto process outputs on the end event
`=js:vars.<id>_response.Id`. Map results onto process outputs on the end event
(`payload: { type: 'BPMN.Variables', outputRows: [{ name, type, var, source:
'=vars.<id>_response' }] }`). Do not hand-fill
'=js:vars.<id>_response' }] }`). Do not hand-fill
`.activity('Intsvc.ActivityExecution', …)` for these operations: the library
ships one Data Service operation, so `.connector()` cannot author the rest, and a
hand-filled node gets `objectName`, the parameter targets and the folder binding
Expand Down
6 changes: 3 additions & 3 deletions skills/uipath-maestro-bpmn/references/connectors.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ A failed search gives `uip`'s reason; fix what it names: log in again for a sess
{
'fields.project.key': lookup('uipath-atlassian-jira', 'create-issue', 'fields.project.key').by('name', 'Coder Eval'),
'fields.issuetype.id': '10001',
'fields.summary': '=vars.summary',
'fields.summary': '=js:vars.summary',
},
{ connection: 'jira', folder: 'jiraFolder' })
```
Expand Down Expand Up @@ -221,7 +221,7 @@ uip is triggers objects <connector> <EVENT> --connection-id <id> --output json
uip is triggers describe <connector> <EVENT> <object> --connection-id <id> --output json
```

- The payload lands in `outputVar` (default `<id>_result`) and a failure in `<id>_Error`; the node declares both, so `=vars.<id>_result.subject` reads a payload field downstream.
- The payload lands in `outputVar` (default `<id>_result`) and a failure in `<id>_Error`; the node declares both, so `=js:vars.<id>_result.subject` reads a payload field downstream.
`outputs` maps payload fields onto variables of their own, and its sources read the payload under `response`: `outputs: { subject: '=response.subject' }`.
A bare `'=subject'` reads nothing: the payload is not at the top level.
- `folderPath` is deprecated and ignored: the task names its folder by the `folder` binding alone, so drop it.
Expand All @@ -234,7 +234,7 @@ Write the step so that `check` passes and the CLI, not prose, says what is missi

- **The operation's metadata is local**: §1 finds it in the library (a local cache, so this works offline), and `check` names no `uip maestro registry prepare` for it (`OBJECT_UNPREPARED`, `CUSTOM_FIELDS_UNPREPARED`, or a `CONNECTOR_INPUT` for a field only the connection discovers), since only a live `prepare` clears those.
Write the `.connector()` call of §2 with symbolic `connection` and `folder` names and no `bindings.json`.
Leave no `lookup()` in it, because `compile` refuses one until `prepare` records it (`LOOKUP_UNRESOLVED`); a lookup field takes a runtime `=vars.<id>` or a fixed-vocabulary literal (`send_as: 'bot'`), which `check` only warns about (`LOOKUP_RUNTIME_VALUE`, `LOOKUP_LITERAL_ID`).
Leave no `lookup()` in it, because `compile` refuses one until `prepare` records it (`LOOKUP_UNRESOLVED`); a lookup field takes a runtime `=js:vars.<id>` or a fixed-vocabulary literal (`send_as: 'bot'`), which `check` only warns about (`LOOKUP_RUNTIME_VALUE`, `LOOKUP_LITERAL_ID`).
`check`, `compile` and `format` pass and emit a real `Intsvc.ActivityExecution` task reading `=bindings.<name>`.
`refresh` then refuses (`Connection binding "<name>" default must be a GUID.`) and `validate` reports `MISSING_BINDING`: that is the draft's blocker, so stop there, and do not edit a binding or a package file to get past it.
- **Otherwise, with no tenant for `prepare` to reach** (the operation is not in the library, or `check` asks for a `prepare`): write the step as a bare `.task(id, { name })` whose name says what it does and carries the connector key and the operation, such as `'Send Slack digest (uipath-salesforce-slack / send-message-to-channel, unresolved)'`.
Expand Down
Loading