Skip to content

Commit 536927d

Browse files
committed
fix: carry #4891 under #4892 so the pick applies on release/v1.207
#4892 edits lines #4891 adds. This branch now holds release/v1.207 + #4891 + #4892. Merge after the #4891 pick (#4995).
1 parent 5f848c2 commit 536927d

19 files changed

Lines changed: 454 additions & 65 deletions

‎skill-flavors/studioweb/uipath-maestro-bpmn/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ When a reference tells you to run a command that is not available, use the Studi
8888
every error it prints (it exits non-zero) before you compile. `compile` writes what
8989
the source says; `check` is what reports a probable mistake, such as a `vars.<id>`
9090
read of a variable nothing declares (`EXPR_UNDECLARED_REF`) or a declared variable
91-
read without `vars.` (`EXPR_BARE_VAR_REF`). For two of these, a read in an
91+
read without `vars.` (`EXPR_BARE_VAR_REF`; fix: `=js:vars.<id>`). For two of these, a read in an
9292
`errorMapping` condition and a bare `=amount`, `check` is the only offline gate:
9393
`bpmn validate` accepts both. Studio Web ships its own SDK: an older one refuses the
9494
read in `compile` itself.

‎skills/uipath-maestro-bpmn/SKILL.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ need, then let TypeScript and `bpmn check` provide the detailed contract.
2020
2. Seed an existing process, or the stub `bpmn init` wrote, with `bpmn decompile`; never hand-write the skeleton (Workflow step 4).
2121
3. Leave a `.preserve({ … })` call that `decompile` wrote alone; it carries state nothing else derives (Workflow step 4).
2222
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`.
23+
Author every expression as `=js:` ([exceptions](references/bpmn-runtime.md#variables-and-the-process-contract)).
2324
5. After each compile of a new process, run `format`, then `refresh`, then `validate`, in that order (Workflow steps 6–7).
2425
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)).
2526
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.
@@ -124,7 +125,7 @@ A discovery-only request (discover types or save registry evidence, no authoring
124125
every error it prints (it exits non-zero) before you compile. `compile` writes what
125126
the source says; `check` is what reports a probable mistake, such as a `vars.<id>`
126127
read of a variable nothing declares (`EXPR_UNDECLARED_REF`) or a declared variable
127-
read without `vars.` (`EXPR_BARE_VAR_REF`). For two of these, a read in an
128+
read without `vars.` (`EXPR_BARE_VAR_REF`; fix: `=js:vars.<id>`). For two of these, a read in an
128129
`errorMapping` condition and a bare `=amount`, `check` is the only offline gate:
129130
`bpmn validate` accepts both.
130131
Needs `@uipath/maestro-builder-sdk` 6.86.0 or later; an older `compile` refuses the read itself.
@@ -257,7 +258,7 @@ export default bpmn('approval')
257258
t.onError(true, { errorVar: 'failure' }, (b) => b.endEvent('failed', { name: 'Approval failed' }));
258259
})
259260
.choose('approved', [
260-
{ when: '=vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post') },
261+
{ when: '=js:vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post') },
261262
{ otherwise: true, label: 'No', body: (b) => b.task('reject') },
262263
])
263264
.endEvent('done')
@@ -278,7 +279,7 @@ export default bpmn('approval')
278279
- An event sub-process guards the whole container it sits in, catching what nothing closer caught; a boundary handler guards one activity.
279280
To fail one iteration rather than the whole run, put the `eventSubProcess` inside the multi-instance sub-process.
280281
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.
281-
A boundary handler captures nothing by default; there `errorVar` is what makes the error readable, as `=vars.<errorVar>.code`.
282+
A boundary handler captures nothing by default; there `errorVar` is what makes the error readable, as `=js:vars.<errorVar>.code`.
282283
- `check` warns `NO_DEFAULT_FLOW` on an exclusive gateway whose every flow is conditioned; give it an `otherwise` arm or a default.
283284
- `.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.
284285
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.

‎skills/uipath-maestro-bpmn/examples/ContractRegistry.bpmn.ts‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
*
1717
* Every `.dataService()` writes its response to `<id>_response` and the error payload
1818
* to `<id>_Error`, both declared for you, so the next node reads
19-
* `=vars.create_response.Id` with nothing more written.
19+
* `=js:vars.create_response.Id` with nothing more written.
2020
*/
2121
import { bpmn } from '@uipath/maestro-builder-sdk/bpmn';
2222

@@ -47,7 +47,7 @@ export default bpmn('ContractRegistry')
4747
.dataService('create', {
4848
...df,
4949
op: 'create',
50-
record: { contractTitle: '=vars.contractTitle', status: 'Open', priority: 2, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
50+
record: { contractTitle: '=js:vars.contractTitle', status: 'Open', priority: 2, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
5151
})
5252
// The filter is a query parameter; `start`/`limit` default to 0/100.
5353
// `sortBy` becomes the body's `_sortFieldName` (the connector's own RequestField) and
@@ -58,19 +58,19 @@ export default bpmn('ContractRegistry')
5858
.dataService('update', {
5959
...df,
6060
op: 'update',
61-
id: '=vars.create_response.Id',
62-
record: { contractTitle: '=vars.contractTitle', status: 'Open', priority: 1, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
61+
id: '=js:vars.create_response.Id',
62+
record: { contractTitle: '=js:vars.contractTitle', status: 'Open', priority: 1, dueDate: '2026-08-01', value: 12500.5, isUrgent: true },
6363
})
64-
.dataService('get', { ...df, op: 'get', recordId: '=vars.update_response.Id', expansionLevel: 3 })
64+
.dataService('get', { ...df, op: 'get', recordId: '=js:vars.update_response.Id', expansionLevel: 3 })
6565
.endEvent('done', {
6666
name: 'Done',
6767
payload: {
6868
type: 'BPMN.Variables',
6969
outputRows: [
70-
{ name: 'createdRecord', type: 'json', var: 'createdRecord', source: '=vars.create_response' },
71-
{ name: 'dueSoon', type: 'json', var: 'dueSoon', source: '=vars.queryDue_response' },
72-
{ name: 'untitled', type: 'json', var: 'untitled', source: '=vars.queryUntitled_response' },
73-
{ name: 'retrievedRecord', type: 'json', var: 'retrievedRecord', source: '=vars.get_response' },
70+
{ name: 'createdRecord', type: 'json', var: 'createdRecord', source: '=js:vars.create_response' },
71+
{ name: 'dueSoon', type: 'json', var: 'dueSoon', source: '=js:vars.queryDue_response' },
72+
{ name: 'untitled', type: 'json', var: 'untitled', source: '=js:vars.queryUntitled_response' },
73+
{ name: 'retrievedRecord', type: 'json', var: 'retrievedRecord', source: '=js:vars.get_response' },
7474
],
7575
},
7676
})

‎skills/uipath-maestro-bpmn/examples/InvoiceApproval.bpmn.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
* produces from a process someone actually runs: 71 elements, wide gateway routing,
88
* and six node types in one graph.
99
*
10+
* Its plain `=` expressions are the import's legacy C#: copy none of them, and write
11+
* every new expression as `=js:` (`'=js:vars.total * 0.9'`), except a human-task
12+
* form field's `value`, which stays `=vars.<id>`.
13+
*
1014
* | it demonstrates | as |
1115
* | --- | --- |
1216
* | an Integration Service **event trigger** | `.activity(…, 'Intsvc.EventTrigger')` on a start event |

‎skills/uipath-maestro-bpmn/examples/InvoiceEscalation.bpmn.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,12 +123,12 @@ export default bpmn('invoice-escalation')
123123
// back to the approver; `rejected` ends the process; `approved` continues.
124124
.choose('route', [
125125
{
126-
when: '=vars.decision == "Approve"',
126+
when: '=js:vars.decision == "Approve"',
127127
label: 'Approved',
128128
body: (b) => b.task('markApproved', { name: 'Mark approved', set: { outcome: 'APPROVED' } }),
129129
},
130130
{
131-
when: '=vars.decision == "Needs info"',
131+
when: '=js:vars.decision == "Needs info"',
132132
label: 'Needs info',
133133
body: (b) => b.task('requestInfo', { name: 'Ask the vendor', set: { outcome: 'AWAITING_VENDOR' } }).goto('approve'),
134134
},

‎skills/uipath-maestro-bpmn/references/bpmn-runtime.md‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ make from syntax alone. Exact signatures remain in the generated API.
2424
.var('scoreValue', 'number')
2525
// … tasks write scoreValue …
2626
.endEvent('done', { payload: { type: 'BPMN.Variables', outputRows: [
27-
{ name: 'score', type: 'number', source: '=vars.scoreValue', var: 'score' },
27+
{ name: 'score', type: 'number', source: '=js:vars.scoreValue', var: 'score' },
2828
] } })
2929
```
3030
Never read an `.output()` before its end event; read the `.var()` instead.
@@ -62,16 +62,24 @@ make from syntax alone. Exact signatures remain in the generated API.
6262
Unlike a task's output row, a start-event row does not declare its variable: without the
6363
`.var()`, `check` fails `EXPR_UNDECLARED_REF`.
6464

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

7684
<!-- RULE:bpmn.variables.input-name -->
7785
- Input values are matched to declarations by display `name` when a run starts, so an
@@ -249,7 +257,7 @@ make from syntax alone. Exact signatures remain in the generated API.
249257
propertyAttribute: 'folderPath', resourceKey: 'CreditAssessment', resourceSubType: 'ProcessOrchestration' })
250258
// …
251259
.startAgenticProcess('assess', { process: '=bindings.childName', folder: '=bindings.childFolder',
252-
input: { annualIncome: '=vars.annualIncome' }, outputs: { score: '=result.score' } })
260+
input: { annualIncome: '=js:vars.annualIncome' }, outputs: { score: '=result.score' } })
253261
```
254262
The called process must map its outputs at its end event ([output end mapping](#variables-and-the-process-contract)),
255263
or `result.score` is `null`.
@@ -317,7 +325,7 @@ make from syntax alone. Exact signatures remain in the generated API.
317325
```
318326

319327
<!-- RULE:bpmn.http.url-placeholders -->
320-
- 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.
328+
- 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.
321329

322330
<!-- RULE:bpmn.orchestrator.business-rule -->
323331
- A deployed business rule is `.businessRule(id, { process, folder, input, outputs })`, nothing else.
@@ -421,9 +429,9 @@ binding half, which is the same for every connector-backed node.
421429
way the platform's own tools do and needs no connector library or `prepare`
422430
step. The response lands in `<id>_response` and the error payload in
423431
`<id>_Error`, both declared for you — read the created record's id as
424-
`=vars.<id>_response.Id`. Map results onto process outputs on the end event
432+
`=js:vars.<id>_response.Id`. Map results onto process outputs on the end event
425433
(`payload: { type: 'BPMN.Variables', outputRows: [{ name, type, var, source:
426-
'=vars.<id>_response' }] }`). Do not hand-fill
434+
'=js:vars.<id>_response' }] }`). Do not hand-fill
427435
`.activity('Intsvc.ActivityExecution', …)` for these operations: the library
428436
ships one Data Service operation, so `.connector()` cannot author the rest, and a
429437
hand-filled node gets `objectName`, the parameter targets and the folder binding

‎skills/uipath-maestro-bpmn/references/connectors.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ A failed search gives `uip`'s reason; fix what it names: log in again for a sess
5959
{
6060
'fields.project.key': lookup('uipath-atlassian-jira', 'create-issue', 'fields.project.key').by('name', 'Coder Eval'),
6161
'fields.issuetype.id': '10001',
62-
'fields.summary': '=vars.summary',
62+
'fields.summary': '=js:vars.summary',
6363
},
6464
{ connection: 'jira', folder: 'jiraFolder' })
6565
```
@@ -221,7 +221,7 @@ uip is triggers objects <connector> <EVENT> --connection-id <id> --output json
221221
uip is triggers describe <connector> <EVENT> <object> --connection-id <id> --output json
222222
```
223223

224-
- 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.
224+
- 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.
225225
`outputs` maps payload fields onto variables of their own, and its sources read the payload under `response`: `outputs: { subject: '=response.subject' }`.
226226
A bare `'=subject'` reads nothing: the payload is not at the top level.
227227
- `folderPath` is deprecated and ignored: the task names its folder by the `folder` binding alone, so drop it.
@@ -234,7 +234,7 @@ Write the step so that `check` passes and the CLI, not prose, says what is missi
234234

235235
- **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.
236236
Write the `.connector()` call of §2 with symbolic `connection` and `folder` names and no `bindings.json`.
237-
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`).
237+
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`).
238238
`check`, `compile` and `format` pass and emit a real `Intsvc.ActivityExecution` task reading `=bindings.<name>`.
239239
`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.
240240
- **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)'`.

0 commit comments

Comments
 (0)