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
3 changes: 1 addition & 2 deletions skill-flavors/studioweb/uipath-maestro-flow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,9 @@ Schema-dynamic operations (`loadByDefault`, dependent dropdowns, `customFieldsRe
```bash
cd /solution/<Project>
uip maestro flow decompile new.flow -o .flow-sdk/new.flow.ts --no-pipeline
# Add your steps to it:
# Delete its .layout() call so compile lays it out, then add your steps:
uip maestro flow check .flow-sdk/new.flow.ts --source
uip maestro flow compile .flow-sdk/new.flow.ts -o new.flow
Comment thread
tmatup marked this conversation as resolved.
Resolved
uip maestro flow format new.flow --output json
uip maestro flow validate new.flow --output json
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Studio Web does not use these gates. Its loop is
`check --source --baseline` against the canvas copy, each `prepare` it names,
`compile` into `/tmp/flow-draft/<Project>/<Name>/edited/`, `merge` into the
target `.flow`, then `validate`. A new flow runs `check --source`, each
`prepare` it names, `compile` into its `.flow`, `format`, then `validate`. There is no compiled-artifact `check`; `validate` is that rung.
`prepare` it names, `compile` into its `.flow` (compile lays it out), then `validate`. There is no compiled-artifact `check`; `validate` is that rung.

Warnings require deliberate review; whether one blocks a release comes from the
surrounding task or release policy.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ there is no partial scaffold to repair. If a Flow folder is missing from
<!--skill-flavor:skip-registration-fix:end-->

<!--skill-flavor:misshapen-format:start-->
**Misshapen nodes on the canvas.** `compile` writes a placeholder
`ui.position` on each node — all of them on one row — and no top-level `layout`
block. In Studio Web this shows only on a new `.flow` that `compile` wrote
straight, with no merge: `merge` keeps the layout of the original and places
each added node, moving others to fit it; leave them where it put them. Fix such a new file once with
`uip maestro flow format <Name>.flow` — see
[`operate.md`](operate.md#lay-out-the-emitted-flow-first). Never run it on a
merged file: it lays out the canvas of the user again.
**Misshapen nodes on the canvas.** A source with no `.layout()` is not the
cause: `compile` lays it out the way `uip maestro flow format` does and gives
every node its canvas size. The exception is an SDK older than 6.113.0,
which leaves every node on one row; the fallback is in
[`operate.md`](operate.md#layout-of-the-emitted-flow).
`merge` keeps the layout of the original and places each added node, moving
others to fit it; leave them where it put them. Never run `format` on a merged
file: it lays out the canvas of the user again.
<!--skill-flavor:misshapen-format:end-->
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,12 @@ positions of the user, and `merge` keeps them and places each added node,
moving later nodes right or down and growing containers only to fit added ones.
`format` lays out every node again and discards them.

A new `.flow` that `compile` wrote straight, with no merge, is different.
`compile` writes a placeholder `ui.position` on each node, all on one flat row,
and no top-level `layout` block. So run `format` once on such a file, before
the user opens it, unless its source sets `.layout()` (below):

```bash
uip maestro flow format <Name>.flow --output json
```
A new `.flow` that `compile` wrote straight, with no merge, needs no `format`
either. For a source with no `.layout()`, `compile` lays out every node the way
`format` does and gives each its canvas-shape size: a container (a loop, for
example) 560 × 320, an agent node 288 × 96, every other node 96 × 96. A
decompiled `new.flow` carries a `.layout()` with the canvas trigger's entry:
delete that call before you compile, or every other node stays on one row.
<!--skill-flavor:operate-format:end-->

<!--skill-flavor:layout-sdk-version:start-->
Expand Down Expand Up @@ -172,3 +170,7 @@ connection that is not in the solution fails at run time with a binding error.
tell the user to chat with it from the Studio Web designer. The host returns no
chat link.
<!--skill-flavor:operate-debug-conversational:end-->

<!--skill-flavor:compile-layout-sdk-upgrade:start-->
or tell the user the flow needs `@uipath/maestro-builder-sdk` 6.113.0 or later: Studio Web owns the SDK copy.
<!--skill-flavor:compile-layout-sdk-upgrade:end-->
2 changes: 0 additions & 2 deletions skills/uipath-maestro-flow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@
<!--skill-flavor:sdk-project-layout:end-->

<!--skill-flavor:sdk-connector-discovery:start-->
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 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()` (not for an external agent: see the table). With none pulled it searches the tenant through `uip`. For another tenant capability (agent, process), which that library does not hold, run the family's `uip maestro flow registry search` ([`references/agent.md`](references/agent.md)). For document extraction, default to a published IXP model ([`references/ixp.md`](references/ixp.md)); the Extract document node only when asked for by name or already in the flow ([`references/extract-document-node.md`](references/extract-document-node.md)). A `script()` returning fixed values is never a stand-in for that step, and `mock()` only marks a capability the search proved absent.

Check warning on line 59 in skills/uipath-maestro-flow/SKILL.md

View workflow job for this annotation

GitHub Actions / skills/uipath-maestro-flow

Possibly stale `uip maestro registry search <brand or service name>` (valid prefix: `maestro registry search`)
Connectors require [`.flow-sdk/bindings.json`](references/bindings.md).
`uip maestro registry pull` writes a descriptor per referenced connector to `.flow-sdk/connectors/<key>.ts` and caches the library outside the project.
If the library cannot be downloaded, `pull` fetches referenced connectors via `uip` into `connectors-local/`; with none pulled, so do `check` and `compile`.
Expand Down Expand Up @@ -103,8 +103,6 @@
```bash
( 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
# Greenfield only (never a merged or .layout() file), before upload/debug/a designer:
uip maestro flow format "<Solution>/<Name>/<Name>.flow" --output json
# Stated runtime claim; ask per references/operate.md
( cd "<Solution>" && uip solution resources refresh --solution-folder . --output json )
( cd "<Solution>" && uip maestro flow debug <Name> --log-level error \
Expand Down
14 changes: 6 additions & 8 deletions skills/uipath-maestro-flow/references/CLI-LOOP.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,14 +133,12 @@
Warnings require deliberate review; whether one blocks a release comes from the
surrounding task or release policy.

Layout is deliberately absent from this sequence. `uip maestro flow format`
is not an authoring gate — `validate` passes without it and nothing upstream
reads a position. For a greenfield file (one `compile` wrote from scratch), run
it before the file reaches anything that draws it: `solution upload`,
`flow debug`, or a person opening the project in a designer. Do not run it on a
merged brownfield file, or on one whose source sets `.layout()`: `format`
re-lays out every node, so it discards the positions the author chose. See
[`operate.md`](operate.md#lay-out-the-emitted-flow-first).
Layout is not a step in this sequence. `compile` lays out a source with no
`.layout()` the way `uip maestro flow format` does, so the file is ready for
`solution upload`, `flow debug`, or a designer. Do not run `format` on a merged
brownfield file, or on one whose source sets `.layout()`: `format` re-lays out
every node, so it discards the positions the author chose. See
[`operate.md`](operate.md#layout-of-the-emitted-flow).

These authoring verbs require a prerelease of `@uipath/cli` that exposes them.
<!--skill-flavor:local-gates:end-->
Expand Down Expand Up @@ -340,7 +338,7 @@
For a fault, query the backend incident payload with the returned instance id:

```bash
uip maestro flow debug-instance incidents <instanceId> \

Check warning on line 341 in skills/uipath-maestro-flow/references/CLI-LOOP.md

View workflow job for this annotation

GitHub Actions / skills/uipath-maestro-flow

Possibly stale `uip maestro flow debug-instance incidents` (valid prefix: `maestro flow`)
--output-filter "[*].{E:ElementId,C:ErrorCode,M:ErrorMessage,D:ErrorDetails}"
```

Expand Down
23 changes: 11 additions & 12 deletions skills/uipath-maestro-flow/references/diagnose.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,19 +119,18 @@ the flag silently returns a plain Flow.
<!--skill-flavor:skip-registration-fix:end-->

<!--skill-flavor:misshapen-format:start-->
**Misshapen nodes on the canvas.** `compile` writes a placeholder
`ui.position` on each node — all of them on one row — and no top-level `layout`
block. The canvas uses a node's `layout.nodes[<id>]` entry when there is one
and its `node.ui` otherwise, so a greenfield file draws at the placeholders.
Symptom: the flow behaves correctly and is unreadable, a switch's arms strung
out in a line instead of side by side. This is not a run-time fault and no
check reports it — `validate` passes, because layout is not an authoring
concern. Fix, for a greenfield file only: `uip maestro flow format <Name>.flow`,
which is owed before an upload, a debug, or anyone opening the project in a
designer — see [`operate.md`](operate.md#lay-out-the-emitted-flow-first). Do not
run it on a merged brownfield file; it re-lays out the author's canvas.
**Misshapen nodes on the canvas.** Symptom: the flow behaves correctly and is
unreadable: nodes overlap, or a node is drawn at the wrong size. This is not a
run-time fault and no check reports it — `validate` passes, because layout is
not an authoring concern. A source with no `.layout()` is not the cause:
`compile` lays it out the way `uip maestro flow format` does and gives every
node its canvas size. The exception is an SDK older than 6.113.0, which
leaves every node on one row; the fallback is in
[`operate.md`](operate.md#layout-of-the-emitted-flow).
Do not run `format` on a merged brownfield file; it re-lays out the author's
canvas.
<!--skill-flavor:misshapen-format:end-->
When the source sets `.layout()`, the misshapen node is the one with no entry, an entry at the wrong coordinates, an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) without `dim(288, 96)`, or a container whose `dim()` no longer holds a body that grew.
When the source sets `.layout()`, the misshapen node is the one with no entry, an entry at the wrong coordinates, or a container whose `dim()` no longer holds a body that grew.
In a greenfield source: add or move its `at(x, y)`, resize with `dim(width, height)`, and recompile rather than running `format`, which would discard every other entry too.
In a merged brownfield file only an added node's entry lands; fix an existing node's position or size in the merged `.flow`'s `layout.nodes` ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim), [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps)).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ that lives in Studio Web and has to be pulled down first — ask them for its UR
<!--skill-flavor:extract-find-flow:end-->
1. **Check the tenant can run it:** `uip maestro flow extraction check --output json`. An answer other than `Available` stops the loop here, and a check that settles nothing is a question for the user ([Check the tenant can run it](#check-the-tenant-can-run-it)).
2. **Declare the file the flow takes in,** unless it already has one: `uip maestro flow variables create <file> invoice -d in -t file --description '<what the document is>'`. Its `TriggerNodeId` is the `<trigger>` in `$vars.<trigger>.output.invoice`, so it comes before the node that reads it.
3. **Add the node** with `--label` naming what it extracts, and `--input` carrying `fileRef`, laid out per [operate.md](operate.md#lay-out-the-emitted-flow-first).
3. **Add the node** with `--label` naming what it extracts, and `--input` carrying `fileRef`, laid out per [operate.md](operate.md#layout-of-the-emitted-flow).
4. **Connect it in the graph** with `edges create` ([Wiring the file it reads](#wiring-the-file-it-reads)).
5. **Write the taxonomy** — [extract-document-taxonomy.md](extract-document-taxonomy.md).
6. **Bind the result to a flow output** so the extraction leaves the flow — [Returning the result](#returning-the-result).
Expand Down Expand Up @@ -161,7 +161,7 @@ The `error` port carries failures. Wire it with `edges create --source-port erro

Extraction that nothing reads is not much use, so the flow usually declares an output carrying it. That takes three steps, and the last one has no CLI command — write it into the `.flow` file directly rather than going looking for a verb that does it.

Declare the output global, then add an End node ([laid out](operate.md#lay-out-the-emitted-flow-first)) and wire the extract node to it:
Declare the output global, then add an End node ([laid out](operate.md#layout-of-the-emitted-flow)) and wire the extract node to it:

```bash
uip maestro flow variables create <file> extractedData -d out -t object --description 'The structured data extracted from the document' --output json
Expand Down
48 changes: 23 additions & 25 deletions skills/uipath-maestro-flow/references/operate.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,16 @@ Authoring is upstream. Do not ship a flow whose source has not been through the
loop in [`CLI-LOOP.md`](CLI-LOOP.md) — `check` on the source, `compile` to emit,
`validate` on the emitted `.flow`.

## Lay out the emitted flow first
## Layout of the emitted flow

<!--skill-flavor:operate-format:start-->
```bash
uip maestro flow format <Name>.flow --output json
```
`compile` lays out the flow. For a flow or subflow whose source has no
`.layout()`, each node gets the position `uip maestro flow format` would give
it. Running `format` on the compiled file moves nothing; skip it.

**Greenfield files only.** Layout is not an authoring concern — nothing
upstream needs it, and `validate` passes without it. It becomes one here, the
moment a file `compile` wrote from scratch is opened by something that draws
it: `solution upload`, `flow debug`, or a person opening the project in a
designer. Run `format` before any of those, on the artifact as last emitted,
unless its source sets `.layout()` (below).

`compile` writes a placeholder `ui.position` on each node and no top-level
`layout` block. The canvas places each node from its `layout.nodes[<id>]`
entry when there is one, and from `node.ui` otherwise, so a greenfield file
draws at the placeholders. They are one flat row: a four-armed switch arrives
as a single 3,000px line with the arms in sequence rather than side by side.
`format` builds `layout`, fans the arms onto their own rows, sizes each node by
its canvas shape, and reports `NodesRepositioned`. Skipping it on a greenfield
file is the most common cause of misshapen nodes in Studio Web.
Every node also gets its canvas-shape size, unless `.layout()` sets one: a
container (a loop, for example) is 560 × 320, an agent node (`inlineAgent`,
`conversationalAgent`, `voiceAgent`) 288 × 96, and every other node 96 × 96.

**Never format a merged brownfield file.** The original's `layout` already
holds the canvas author's positions, and `merge` keeps them, moving later
Expand All @@ -40,6 +28,16 @@ re-lays out every node and discards them. Upload or debug the merged file as
`merge` wrote it.
<!--skill-flavor:operate-format:end-->

This needs `@uipath/maestro-builder-sdk` 6.113.0 or later. An older SDK
writes every node 96 × 96 on one row at y = 144 (an agent node's `ui.size` is
96 × 96, not 288 × 96). With such an SDK, run
`uip maestro flow format <Name>.flow --output json` once on a greenfield file
(never on a merged or `.layout()` file), and in a `.layout()` give each agent
node `dim(288, 96)` and each container at least `dim(560, 320)`;
<!--skill-flavor:compile-layout-sdk-upgrade:start-->
or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`.
<!--skill-flavor:compile-layout-sdk-upgrade:end-->

`nodes create` without `--position`, or a hand edit that adds nodes, leaves every new
node at `layout.nodes[<id>].position` 0,0. After such an edit to a file with no
author-chosen layout, run `format`, then confirm each node in `layout.nodes` has a
Expand All @@ -48,13 +46,13 @@ distinct position. With an author-chosen layout, skip `format` and pass

### Lay out from source instead: `.layout()`, `at()`, `dim()`

The builder can place the nodes itself, so the emitted file never needs `format` — provided every node that is not 96 × 96 carries its size (rule 1).
`.layout()` replaces compile's layout with positions you choose.
`.layout({ nodes })` on the flow takes one entry per node, keyed by node id; `at(x, y)` writes an entry, and `dim(width, height)` the size a container needs.
A step's id is its name.
The trigger's is `start` unless `.triggerId()` renamed it.
An End's is the `name` its `.return` gave it, and an unnamed End is `end`, then `end2`, `end3`, … in emission order, so a flow with several unnamed Ends has that many keys to write.
Use it when the request asks for a particular arrangement, or when a decompiled source already carries one ([`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps)).
Otherwise `format` is less work and lays out as well.
Otherwise leave it out: compile lays out the flow itself.

```ts
import { at, dim, flow } from '@uipath/maestro-builder-sdk';
Expand All @@ -65,7 +63,7 @@ export default flow('invoice-intake')
nodes: {
start: at(256, 144), fetch: at(448, 144), eachInvoice: at(640, 144, dim(576, 320)),
extract: at(144, 96), route: at(336, 96), // inside eachInvoice, relative to it
review: at(1312, 144, dim(288, 96)), // an agent node carries its size
review: at(1312, 144), // an agent node: compile gives it 288 × 96
done: at(1696, 144),
onFailure: at(448, 528), end: at(640, 528), // below the container, not beside its body
},
Expand All @@ -77,9 +75,9 @@ Rules:

1. **Use the canvas grid.** A node is 96 px square; a column is 192 px, a row 160 px: `x = 256 + 192 × column`, `y = 144 + 160 × row`.
The main path goes on row 0 left to right; an error handler or a side arm takes the row below.
Compile writes 96 × 96 on every node and the designer draws the persisted size, so a node whose canvas shape is larger must carry it: an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) is `at(x, y, dim(288, 96))`, and the next column starts 384 px to its right; a container carries its `dim()` (rule 2), and the row below it starts one row gap (64 px) under its bottom edge, not at the next 160 px row.
2. **A child's position is relative to its container.** A loop or do-while body starts at `at(144, 96)` inside the container's padding, and the container needs a `dim()` that holds the body: the right edge of its rightmost child plus 144, by the bottom edge of its lowest child plus 96, never smaller than `format`'s `dim(560, 320)`.
For one row of 96 px nodes that is `dim(max(560, 192 × bodyNodes + 192), 320)`; a body with an inline agent, a second row or a nested container is measured from its own entries, not from the node count.
Compile gives a node without `dim()` its canvas-shape size: an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) is 288 × 96, so the next column starts 384 px to its right; a container is 560 × 320 unless its `dim()` makes it larger (rule 2), and the row below it starts one row gap (64 px) under its bottom edge, not at the next 160 px row.
2. **A child's position is relative to its container.** A loop or do-while body starts at `at(144, 96)` inside the container's padding. The container's 560 × 320 holds a small body; give it a `dim()` only when the body needs more: the right edge of its rightmost child plus 144, by the bottom edge of its lowest child plus 96.
For one row of 96 px nodes that is `dim(192 × bodyNodes + 192, 320)` from two body nodes on (two nodes: `dim(576, 320)`, as `eachInvoice` above); a body with an inline agent, a second row or a nested container is measured from its own entries, not from the node count.
3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout; an unknown key fails `compile`.
4. **Never `format` a file whose source sets `.layout()`.** `format` re-lays out every node and discards the source's positions, exactly as it does to a merged brownfield file.
<!--skill-flavor:layout-sdk-version:start-->
Expand Down
Loading