Skip to content

Actions & Libraries

Actions and Libraries form the execution layer of Nexomatic. They define what code runs when an event fires and what happens next.


Understanding how these entities relate is key to building automations:

flowchart TD LIB["Library
(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
  1. Each Library (a specific version line) contains one or more Library Modules
  2. 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
  3. 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

A Library is a named collection of code modules in a specific version line.

FieldDescription
NameA human-readable label (e.g. nexo-shell, nexo-file)
VersionThe version line (e.g. 1.0.0)
LinkURL to the packaged code
DescriptionOptional free-text description
RequirementsDeclared runtime requirements its modules need (engine, minimum version, OS families) — an action’s needs fall out of these

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).

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).

Platform libraries are organized by capability family:

LibraryFamilyModules
Nexo Shell (nexo-shell)ExecutionShell (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 movementLocal (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.

A library packages three things, all browsable on the Libraries screen before you build an action on it:

PartWhat it is
Module filesThe executable code, one file per module, importable on the sink host under the module’s import name
ModulesThe named code units (Shell, Local, …) — each with an import name, a description, and its default parameters
Runtime requirementsPer-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.

A library declares, per module, what a sink host must provide to run it. Each declaration has three optional fields:

FieldMeaningExample
engineThe runtime engine the module needs — reported by the node as a tag (an attribute)pwsh
min_versionThe minimum version of that engine, compared component by component5.1
os_familiesAllowed 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.10 beats 5.9, and a node reporting 7.3 covers ≥ 5.1.
  • os_families — the node’s reported os must be one of the families. CmdScript declares win, 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.

Create your own library with New library (name, version, link, description) and declare its runtime requirements per module. In the editor, manage its modules:

FieldDescription
Import nameThe identifier the sink runtime resolves when the module runs
DescriptionOptional helper text, shown in module pickers

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).

FieldDescription
NameA descriptive label for this action
EnabledWhether the action is active. Disabled actions are skipped
ModuleThe Library Module to execute — pick a library (its declared requirements are shown at pick time) and a module
ParametersOrdered key/value pairs injected at runtime

Parameters inject values into the executing module at runtime. Each parameter has a type:

TypeBehaviour
DATAThe 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
STATICA fixed value baked into the Action definition
SECRETThe 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.

Two modules execute shell commands on Linux sink hosts. They differ in what may run:

ShellShellScript
CommandAny command — resolved from PATH or an absolute pathA bare filename that exists in the sink host’s SCRIPTS_FOLDER
PATH fallbackYes (echo, curl, …)No — PATH-only commands are refused
Path traversal (../, absolute paths)AllowedRefused
SCRIPTS_FOLDEROptional — bare names that match a file there are resolved to itRequired — the action fails without it
Blast radiusAny argv the action defines → arbitrary commands on the hostOnly 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_FOLDER setting (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.

Scripts narrate their own runs by printing marker lines. The runtime parses them from the script’s output:

MarkerWhat 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:

Terminal window
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 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.

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.

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 ✕.

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

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
flowchart TD EV["Webhook fires"] CP["copyfile"] PR["process"] SM["sendmail"] TK["open ticket"] EV --> CP CP -->|success| PR CP -->|failure| SM CP -->|failure| TK
  • If copyfile fails, both sendmail and open ticket run as independent branches
  • If copyfile succeeds, only process runs
  • All of them share one run id — one thread in Runs; open the run and its trace shows the whole chain

Before you can create Actions, you need:

  1. At least one Library (platform libraries are ready to use)
  2. At least one Library Module inside that Library