224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
# The flow editor
|
|
|
|
Build a flow by naming its messages and configuring its nodes. Fluksio draws
|
|
the connections and arranges the canvas for you.
|
|
|
|
## The canvas
|
|
|
|
The graph runs left to right on desktop and top to bottom on phones. On a
|
|
phone, at most two nodes sit side by side and the rest wrap onto the rows
|
|
below, so a large flow grows downwards in one column.
|
|
|
|
- **Nodes** show their execution status.
|
|
- **Edges** are routed around the nodes, a loop back to an earlier node
|
|
included, and pulse when values pass through. Click one to inspect its
|
|
payload.
|
|
- **Endpoints** show flow inputs, dashboard widgets and nodes in other flows
|
|
that exchange messages with this flow. A value passing lights
|
|
one up in a sweep: left to right when it sends into the flow, right to left
|
|
when it reads out of it.
|
|
- **Clicking an endpoint** shows a flow input's type, starting value and
|
|
current value, with a pencil that opens the flow settings to edit it. A node
|
|
in another flow opens that flow on the label leading back here, with its
|
|
edges highlighted.
|
|
|
|
Values update over a websocket. A connection banner tells you when the editor
|
|
cannot reach the engine.
|
|
|
|
## Adding a node
|
|
|
|
Choose **Add node** in the bottom dock, or use ⌘P / Ctrl-P. The command palette
|
|
also jumps between flows and offers reusable nodes. Select a type to add it
|
|
and open its settings.
|
|
|
|
## The node panel
|
|
|
|
**Consumes** and **Provides** declare the node's ports. Each has a bound
|
|
message, a port name, a payload type and a delivery interval. Outputs also have
|
|
a streaming toggle.
|
|
|
|
A row reads top to bottom, from where a value starts to where it ends. An
|
|
input starts as a message and arrives in your code as an argument, so the
|
|
message is on top and the argument below it (*as* `prompt`). An output starts
|
|
as a key of what your code returns and ends as a message, so the key is on top.
|
|
|
|
A **Device** node stands for a paired device instead: pick the device, then
|
|
its ports under **Publishes** (the device's port, then the message) and
|
|
**Follows** (the message, then the port it drives; see
|
|
[the device's own ports](dashboards.md#the-devices-own-ports)). A device that
|
|
reports its ports offers them in a list with their type filled in and a form
|
|
for the settings each one reads, and the command palette offers each one as a
|
|
shortcut, such as *Hallway camera*.
|
|
|
|
Message fields suggest existing names. Matching an output's message is how
|
|
you connect an input.
|
|
|
|
A port name follows the message's last segment (`home.outdoor` becomes
|
|
`outdoor`) until you name it. While it follows, it is shown as muted text, and
|
|
the pencil beside it opens a field. A field only appears on its own when the
|
|
name differs from the message. Set a port name to keep the argument name fixed
|
|
while changing its message binding. Names use letters, digits and `_`, cannot
|
|
start with a digit, and must be unique among the node's inputs or outputs. Two
|
|
messages that end in the same segment, such as `a.level` and `b.level`, get a
|
|
warning until one of them is named differently.
|
|
|
|
Renaming an output's message updates its consumers in the flow. Changing an
|
|
input binding points that input at a different message.
|
|
|
|
### Settings
|
|
|
|
Built-in nodes show forms for their configuration. Credential fields offer
|
|
stored [secrets](operations.md#secrets). JSON settings open a larger editor
|
|
and save only when the value parses.
|
|
|
|
Function nodes also let you add settings passed as arguments alongside the
|
|
ports. See [Where a node's values come from](../concepts/values.md).
|
|
|
|
**Timeout** on a Function node limits silence, not total duration. A node
|
|
yielding regularly can run longer than its timeout. Empty or `0` means no
|
|
limit, the default.
|
|
|
|
**Resources** selects a shared worker pool, a named flavor or custom CPU,
|
|
memory and GPU requirements. Placement by `worker` and `worker_policy` is
|
|
configured through the API or flow JSON; see [Remote workers](../code/workers.md).
|
|
|
|
An HTTP or WebSocket node whose URL is a path, such as `/tick`, is served by
|
|
the engine. The panel then shows the full **Webhook URL** (or **Socket URL**)
|
|
with a copy button. It sits under the flow's id, `/hooks/<flow id>/tick`, so it
|
|
keeps working whatever the flow is called. A stored secret is not shown. The
|
|
URL names it as the last segment for you to fill in.
|
|
|
|
### Code and reuse
|
|
|
|
Define `process(...)` in **Code**. If the file instead contains exactly one
|
|
public function, Fluksio uses that function.
|
|
|
|
Code saves as you type. ⌘S / Ctrl-S in the code editor saves immediately;
|
|
**Publish** applies ordinary node code to the running flow. Tab indents in the
|
|
editor; Ctrl-M (⇧⌥M on macOS) lets Tab move focus on to the next control
|
|
instead. Generated code
|
|
from `fluksio sync` is read-only: edit its source repository and sync again.
|
|
|
|
Only superusers can add or edit code-running nodes. Other users can read code
|
|
and configure permitted built-in nodes.
|
|
|
|
**Reuse** shares node code as a library entry. Saving shared code takes effect
|
|
immediately in every flow using it, so check its users before changing it.
|
|
|
|
## The flow panel
|
|
|
|
Open **Flow settings** from the pencil button in the dock.
|
|
|
|
| Setting | Purpose |
|
|
|---|---|
|
|
| **Identity** | shows the flow's key, the namespace of its messages, and its id with a copy button |
|
|
| **Running** | starts or stops the published live flow's subscriptions, schedules and webhooks |
|
|
| **Mode** | chooses continuous `live` operation or requested `batch` runs |
|
|
| **Inputs** | declares external messages, their starting values and whether a run or a panel writes them; run inputs become run parameters |
|
|
| **Result** | selects batch output messages |
|
|
| **Contents** | shows the node count and message namespace |
|
|
|
|
The id never changes. The editor's address, hook URLs and the API use it. A
|
|
flow that existed before ids were introduced kept its key as its id, while a
|
|
flow created now gets an opaque one such as `f_k3q7m2xa`. The tab and the
|
|
canvas show the title, or the key when there is no title.
|
|
|
|
For live inputs, **Publish this value now** sends the starting value immediately.
|
|
Changing a stored starting value alone does not replace an existing message.
|
|
|
|
### Renaming the key
|
|
|
|
A superuser renames a flow's key with the pencil on the **Key** row. Type the
|
|
new key and the dialog shows what the rename would change before anything
|
|
does: the flows and dashboards it rewrites, how much history, live state and
|
|
queued work moves, and anything that refuses it, such as a key already taken,
|
|
a queued or running run, or a flow declared in code (rename that one in its
|
|
repository and sync it). Type the current key to confirm.
|
|
|
|
Everything named under the key moves to the new one. Messages `old.x` become
|
|
`new.x` in every flow and dashboard bound to them, published and draft, along
|
|
with their history, live values, queued work and alert channels. The id, the
|
|
editor's address, hook URLs and device credentials stay as they were.
|
|
|
|
What lives outside Fluksio keeps the old name and has to be updated by hand:
|
|
calls to `/messages/old.x`, your own scripts, CLI, SDK and MCP calls that pass
|
|
the key, and bindings written by hand. A batch flow's `old_results` dashboard
|
|
keeps its name.
|
|
|
|
The whole engine pauses during a flow rename. It first waits for the work
|
|
running at that moment to finish, as long as that takes, and the dialog lists
|
|
what it is waiting for. Until the rename starts changing things you can call it
|
|
off, and nothing changes. Meanwhile pages keep reading, but changes anywhere
|
|
are turned away with a note to try again in a few seconds. Autosaves retry by
|
|
themselves.
|
|
|
|
Open editors, panels and lists follow the rename at the address they already
|
|
have. An editor whose flow or dashboard was rewritten reloads with the renamed
|
|
version, so neither undo nor a save still on its way can bring the old names
|
|
back. Edits it had not saved yet are dropped, and it says so.
|
|
|
|
## Inspecting an edge
|
|
|
|
Click an edge to see its latest payload, timestamp and recent numeric history.
|
|
Republish its value from the producer to run downstream nodes without waiting
|
|
for the next sensor reading.
|
|
|
|
## The dock
|
|
|
|
| Control | Action |
|
|
|---|---|
|
|
| **Add node** | opens the command palette |
|
|
| **Fit to screen** | fits the graph; desktop only |
|
|
| **Run** | executes the current live flow once; for batch flows, asks for run parameters |
|
|
| **Pause / Resume** | holds or releases pending work while values still arrive |
|
|
| **Step** | releases one held item while paused |
|
|
| **Flow settings** | opens the flow panel |
|
|
| **Publish** | puts the saved draft live |
|
|
| **Discard** | removes unpublished changes |
|
|
| **Issues** | lists problems by node |
|
|
| **Logs** | shows filterable node output |
|
|
|
|
**Run** uses the current draft when one exists without publishing it. It
|
|
executes real node code, including device and network actions. To try a single
|
|
value in a live flow, publish it from a flow input or edge inspector.
|
|
|
|
Pause and step are useful for inspecting held work. They do not make a draft
|
|
run a simulation.
|
|
|
|
## Shortcuts
|
|
|
|
Use ⌘ on macOS and Ctrl elsewhere.
|
|
|
|
| Shortcut | Action |
|
|
|---|---|
|
|
| ⌘P / Ctrl-P | command palette |
|
|
| ⌘S / Ctrl-S | publish the flow; inside the code editor, save code |
|
|
| Ctrl-M / ⇧⌥M | inside the code editor, make Tab move focus instead of indenting |
|
|
| ⌘Z / Ctrl-Z | undo a graph edit |
|
|
| ⌘⇧Z / Ctrl-Shift-Z | redo a graph edit |
|
|
| ⌘C / Ctrl-C | copy selected nodes |
|
|
| ⌘V / Ctrl-V | paste nodes, including into another flow |
|
|
|
|
Text fields and the code editor keep their own undo and clipboard behavior.
|
|
|
|
## Drafts, conflicts and issues
|
|
|
|
Edits are saved as drafts. The engine keeps running the published version until
|
|
you publish; shared code follows the exception above. **Discard** returns to
|
|
the published version. Delete a never-published flow to remove it.
|
|
|
|
If another editor saved the same flow, a stale save or publish returns a
|
|
conflict. Reload and review their changes before retrying.
|
|
|
|
The canvas reports unconnected inputs, missing starting values, cycles and
|
|
code-load errors. These prevent the affected flow from running. Unauthenticated
|
|
webhooks are advisory; runtime node-health problems clear when the node
|
|
recovers. A degraded node, such as a device node whose device is offline, is
|
|
marked amber: it is a warning, and the flow keeps running. See [Flow issues](../concepts/flows.md#when-a-flow-needs-attention).
|
|
|
|
## See also
|
|
|
|
- [Flows, nodes and messages](../concepts/flows.md)
|
|
- [Node types](../reference/node-types.md)
|
|
- [Writing node code](../code/nodes.md)
|