Actions & Libraries
Actions and Libraries form the execution layer of Nexomatic. They define what code runs when an event fires and what happens next.
The Hierarchy
Section titled “The Hierarchy”Understanding how these entities relate is key to building automations:
(named collection of modules, one version line)"] MOD["Library Module
(a single importable code unit)"] ACT["Action
(a module + its parameters)"] FL["Flow step
(action + placement)"] LIB --> MOD MOD --> ACT ACT --> FL
- Each Library (a specific version line) contains one or more Library Modules
- An Action references a Library Module as its executable code, plus its runtime parameters — so an action is pinned to its library’s version line
- A Flow step runs an Action on a placement (a sink, any matching node, or platform) and defines the chain — what runs next on success or failure
Libraries
Section titled “Libraries”A Library is a named collection of code modules in a specific version line.
| Field | Description |
|---|---|
| Name | A human-readable label (e.g. nexo-shell, nexo-file) |
| Version | The version line (e.g. 1.0.0) |
| Link | URL to the packaged code |
| Description | Optional free-text description |
| Requirements | Declared runtime requirements its modules need (engine, minimum version, OS families) — an action’s needs fall out of these |
The Libraries screen
Section titled “The Libraries screen”Libraries live on their own screen (sidebar → Workspace → Libraries). The grid shows one row per version line, with All / Your libraries / Platform libraries filters:
- Platform libraries — pre-built, platform-maintained, available to all tenants. They are read-only in your tenant and consumed directly: actions reference their modules, bugfix patches are picked up automatically, and major/minor lines never auto-bump your flows.
- Your libraries — custom libraries your tenant creates and edits (name, version, link, description, and modules).
Creating or opening a library slides the full-screen editor in (the grid → editor pattern used across the app).
Version pinning
Section titled “Version pinning”Actions pin to a library row, not a name:
- Patch (bugfix) release — the platform updates the same row’s version and link in place; flows using its modules follow automatically, and sinks re-download the new zip.
- Major/minor release — a new row; existing flows stay on their line. Upgrading a flow is an explicit act: switch the action to the newer line (the action editor’s library picker, or the flow editor’s version-aware action labels —
Action — library v1.2.0).
Capability-family libraries (nexo-*)
Section titled “Capability-family libraries (nexo-*)”Platform libraries are organized by capability family:
| Library | Family | Modules |
|---|---|---|
Nexo Shell (nexo-shell) | Execution | Shell (bare command, OS-dispatching — Linux argv, Windows cmd /c), ShellScript (sh scripts-only), Powershell (pwsh -Command), PowershellScript (ps1 scripts-only), CmdScript (.bat/.cmd scripts-only) |
Nexo File (nexo-file) | File movement | Local (copy/move/append into a destination folder — a processing lock guards the source, moves are copy-then-remove, append tracks the transferred byte position in a .track file) |
The nexo-shell family declares its runtime requirements per module — Powershell needs pwsh ≥ 5.1, CmdScript needs Windows — which is exactly what placement matching checks. The legacy remotes-linux / remotes-windows libraries remain available for existing tenants.
The full register — every platform library and module, what each does, how it executes, its node requirements, and its parameters — lives in the Platform Libraries section.
What’s inside a library
Section titled “What’s inside a library”A library packages three things, all browsable on the Libraries screen before you build an action on it:
| Part | What it is |
|---|---|
| Module files | The executable code, one file per module, importable on the sink host under the module’s import name |
| Modules | The named code units (Shell, Local, …) — each with an import name, a description, and its default parameters |
| Runtime requirements | Per-module declarations of what a sink host must provide to run it (engine, minimum version, OS family) |
The library row itself carries the version line, the link to the packaged code, and a free-text description. Platform libraries (nexo-*) are built from a manifest declaring all of the above, so their full content — modules, requirements, and parameter defaults — is visible in read-only form.
Runtime requirements
Section titled “Runtime requirements”A library declares, per module, what a sink host must provide to run it. Each declaration has three optional fields:
| Field | Meaning | Example |
|---|---|---|
engine | The runtime engine the module needs — reported by the node as a tag (an attribute) | pwsh |
min_version | The minimum version of that engine, compared component by component | 5.1 |
os_families | Allowed operating-system families, against the node’s reported os (win or linux) | ["win"] |
How requirements participate in placement. An action’s needs fall out of its module’s library requirements. When the hub routes a step, a node qualifies only when its tags cover the union of the step’s needs and its sink’s constraints:
- engine — the node must report the engine as a tag. With a
min_version, at least one of its reported versions must be ≥ the minimum, compared numerically per component:5.10beats5.9, and a node reporting7.3covers≥ 5.1. - os_families — the node’s reported
osmust be one of the families.CmdScriptdeclareswin, so a Linux node never matches it. - A node reporting none of the needed engines never matches the step — the step is held until a matching node appears, never silently sent elsewhere.
Examples from the platform libraries: Powershell and PowershellScript declare pwsh ≥ 5.1; CmdScript declares win only; Shell, ShellScript and the file module declare no requirements and match any sink node.
The requirements are shown wherever you pick a module (the picker lists them), and you declare them per module when you create your own library.
Custom libraries and modules
Section titled “Custom libraries and modules”Create your own library with New library (name, version, link, description) and declare its runtime requirements per module. In the editor, manage its modules:
| Field | Description |
|---|---|
| Import name | The identifier the sink runtime resolves when the module runs |
| Description | Optional helper text, shown in module pickers |
Actions
Section titled “Actions”An Action is a reusable definition that ties a Library Module to runtime behaviour. It defines:
- Which module to execute
- What parameters to inject at runtime
Actions are reusable — the same Action can be linked to many flows (for example, a sendmail action used as a failure handler everywhere).
| Field | Description |
|---|---|
| Name | A descriptive label for this action |
| Enabled | Whether the action is active. Disabled actions are skipped |
| Module | The Library Module to execute — pick a library (its declared requirements are shown at pick time) and a module |
| Parameters | Ordered key/value pairs injected at runtime |
Action Parameters
Section titled “Action Parameters”Parameters inject values into the executing module at runtime. Each parameter has a type:
| Type | Behaviour |
|---|---|
DATA | The value names the key in the event’s JSON payload whose content is passed at runtime; leave it empty to use the parameter’s own key |
STATIC | A fixed value baked into the Action definition |
SECRET | The value is a secret key — at runtime it is resolved from the Secrets store |
Parameters are ordered — they are passed to the module in the order they appear. Use the drag handles to reorder them.
Default parameters. Modules ship their parameter list — key, type, order, and a default value (the file module’s Local starts with operation / source / destination; the shell modules each start with a single command or script entry). Creating an action from a module pre-fills that list; you keep, edit, delete, or reorder the entries and fill in the values. The list is the module’s own contract, so a module added to a library without defaults starts with an empty parameter list.
Shell vs ShellScript
Section titled “Shell vs ShellScript”Two modules execute shell commands on Linux sink hosts. They differ in what may run:
| Shell | ShellScript | |
|---|---|---|
| Command | Any command — resolved from PATH or an absolute path | A bare filename that exists in the sink host’s SCRIPTS_FOLDER |
| PATH fallback | Yes (echo, curl, …) | No — PATH-only commands are refused |
Path traversal (../, absolute paths) | Allowed | Refused |
SCRIPTS_FOLDER | Optional — bare names that match a file there are resolved to it | Required — the action fails without it |
| Blast radius | Any argv the action defines → arbitrary commands on the host | Only scripts placed in the folder by the operator, with chosen arguments |
When to use which:
- ShellScript (recommended for operator-owned scripts): the host administrator keeps a folder of vetted scripts, and the platform can only invoke them — it can never inject new code. Point the sink at the folder with the
SCRIPTS_FOLDERsetting (systemd installer flag or environment variable). The flow editor warns when a Shell action’s first parameter doesn’t look like a script name and suggests ShellScript. - Shell (flexibility): direct commands are convenient for ad-hoc composition, but the action definition is an arbitrary-argv channel. Use it only when you trust every flow author with shell access to the host.
The same scripts-only contract extends to the other interpreters: PowershellScript (ps1, with DATA params delivered as base64-decoded variables) and CmdScript (.bat/.cmd, with DATA params as positional %1 %2 … args). All script modules run with ParseOutput — scripts emit result markers themselves.
Script markers
Section titled “Script markers”Scripts narrate their own runs by printing marker lines. The runtime parses them from the script’s output:
| Marker | What it results into |
|---|---|
##[name="result.code" value="0"]## | The run’s exit code (0 = success) |
##[name="result.message" type="ERROR" value="boom"]## | A typed result message |
##[name="result.data.<key>" value="<value>"]## | A structured result field |
##[name="step" type="start" value="build image"]## … type="finish" | A named step in the run’s trace — the start reads ▶, the finish ■ with the step’s duration and result; the finish marker may carry result="success|failed" (a failed finish renders red) |
##[name="status" code="42" state="failed" label="payment declined"]## | The run’s outcome — code, state (failed fails the run even on exit 0, warning warns without failing) and a human label shown on the branch header; any subset of the attributes works |
##[name="log" level="WARNING" value="retrying"]## | A structured line inside the current step, rendered in its level’s color (italic) and added to the Traces search table |
##[name="progress" value="67"]## | The branch header’s live progress — the latest value (0–100), updating while the run executes and shown on completed runs |
The grammar needs the inner quotes — ##[name="…" attr="…"]##. In shell,
plain echo eats them (echo "##[name="step" …]"## emits ##[name=step …]##,
which the parser cannot see). Use printf, which keeps them intact:
printf '##[name="step" type="start" value="%s"]##\n' "deploy"./deploy.sh || { printf '##[name="step" type="finish" value="%s" result="failed"]##\n' "deploy" printf '##[name="status" code="42" state="failed" label="%s"]##\n' "deploy failed" exit 1}printf '##[name="step" type="finish" value="%s"]##\n' "deploy"Markers are recognized even when the module streams them through its logger. Unknown markers pass through as ordinary output lines, so typos are visible, never fatal. Result markers keep their old behavior unchanged, and the raw output log keeps the streamed output verbatim.
Chaining
Section titled “Chaining”Chaining lives in the flow, not in the action. Because the same action is reused across flows, what happens after it runs depends on which flow it ran in — copyfile can chain to process on success in one flow and to sendmail on failure in another.
Chain links
Section titled “Chain links”A chain link is: (from action, success|failure) → (to action, on …)
- Fan-out: one action can have several successors for the same outcome (e.g. two failure handlers). Each branch runs independently, in the order you set.
- On: a named sink, any matching node, or platform — every step carries its own placement.
- Depth: a chained action can itself chain further — the chain continues as deep as you define it.
Editing the chain
Section titled “Editing the chain”In the flow editor’s THEN section, each follow-up is one row: if an action succeeds or fails, run the next action on a placement. Add follow-ups with Add follow-up (also on the DO line), remove with the ✕.
How chaining executes
Section titled “How chaining executes”The sink reports “action finished (success/failure) + result data”. The Hub resolves the flow’s links and creates one chained event per matching link:
- Same flow, next action, on the link’s placement
- The result data becomes the chained event’s payload
- No matching link → the run ends
Tracing a run
Section titled “Tracing a run”Every event of a single trigger run shares a run id. Fan-out branches, parent links, and per-step logs all trace back to one run:
- Runs screen: one row per run — open the run to see its whole chain in the trace
- The log search (search all records): the Flow and Action columns show which step produced each log entry
- If
copyfilefails, bothsendmailandopen ticketrun as independent branches - If
copyfilesucceeds, onlyprocessruns - All of them share one run id — one thread in Runs; open the run and its trace shows the whole chain
Prerequisites
Section titled “Prerequisites”Before you can create Actions, you need:
- At least one Library (platform libraries are ready to use)
- At least one Library Module inside that Library
Next Steps
Section titled “Next Steps”- Getting Started — the full workflow to a running automation
- Core Concepts — detailed definitions of all entities
- Flows — UI reference for the Flows screen