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

Understanding how these entities relate is key to building automations:

flowchart TD ST["Sink Type
(e.g. REMOTE:LINUX)"] LIB["Library
(named collection of modules)"] MOD["Library Module
(a single importable code unit)"] ACT["Action
(a module + its parameters)"] FL["Flow
(trigger + target + action + chain)"] ST --> LIB LIB --> MOD MOD --> ACT ACT --> FL

1. A Sink Type has one or more Libraries attached to it
2. Each Library contains one or more Library Modules
3. An Action references a Library Module as its executable code, plus its runtime parameters
4. A Flow links a trigger (source type) to an Action and defines the chain — what runs next on success or failure

---

Libraries

A Library is a named collection of code modules grouped under a Sink Type. It represents a package or bundle of related functionality that sink agents of that type can execute.

Field	Description
Name	A human-readable label (e.g. base-utils, notification-modules)
Version	Optional version string for tracking changes
Link	Optional URL to the packaged code
Description	Optional free-text description
Sink Types	The sink types this library is attached to

The Libraries screen

Libraries live on their own screen (sidebar → Automation → Libraries). The screen shows:

• Platform templates — pre-built, platform-maintained libraries available to all tenants. They are read-only in your tenant.
• Your libraries — libraries your tenant owns, including copies you made of platform templates.

Filter the list with All / Your libraries / Platform templates, exactly like the type screens.

Platform template libraries: Make my copy

Instead of manually entering library details, use Make my copy on a platform template. The platform creates a tenant-owned copy:

• Name, version, link, and modules are copied
• The version stays pinned — a newer platform version is a separate copy, never an automatic upgrade
• The copy records where it came from (provenance), for future update tooling

Custom libraries and modules

Create your own library with New library (name, version, link, description). Expand a library to manage its modules — each module has:

Field	Description
Import name	The identifier the sink runtime resolves when the module runs
Description	Optional helper text, shown in module pickers

The module's import name must match the code packaged in the library's zip. Make sure the corresponding code is deployed alongside the agent or packaged in a way the agent can import it.

Attaching libraries to sink types

Attach/detach libraries to sink types from the library detail (Attach sink type, or the ✕ on a linked chip). An action’s module is only available on sink types its library is attached to — the flow editor’s module picker only offers modules that work on the flow’s sink type.

---

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 (selected from a dropdown; the library picker shows which sink types it is attached to)
Parameters	Ordered key/value pairs injected at runtime

Action Parameters

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

Type	Behaviour
DATA	The value is a key name — at runtime the value is read from the event’s JSON payload
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.

Actions are the **only** parameter surface. There are no separate flow-level parameters — everything the module receives comes from its action's parameters and the event payload.

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

Library pinning

When you Make my copy of a platform library, the platform records the exact content of the library zip at that moment — your copy is pinned:

• Your sink verifies every download of your copy against that recorded content. If the zip at your copy’s link ever changes, the sink refuses to extract it and reports an error naming the library (with the old and new links), instead of silently running different code.
• Legacy libraries without a recorded pin download without verification (they predate pinning).
• Adopting a newer library version means making a fresh copy — Make my copy of the newer platform line, which records the new pin. This matches how copies already stay on their pinned version; pinning makes any change to that version loud rather than silent.

If your sink reports a library rejection, make a new copy of the library to record the current content.

---

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

A chain link is: (from action, success|failure) → (to action, runs 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.
• Runs on: defaults to auto — the flow’s sink type. Pick another sink type when a step needs a different machine (e.g. sendmail on a MAIL:RELAY type that can reach the mail server). The next action’s module must be available on the chosen type.
• Depth: a chained action can itself chain further — the chain continues as deep as you define it.

Editing the chain

In the flow editor’s Chain section, each link is one row: when action finishes with success/failure, run next action on auto or a chosen sink type. Reorder with the arrows, remove with the ✕, and click Save chain.

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 target sink type (or the flow’s when auto)
• The result data becomes the chained event’s payload
• No matching link → the run ends

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:

• Events screen: the Run column shows a run badge — click it to filter to every event of that run
• Logs screen: 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 Events and Logs

Keep chains shallow where possible. Deep chains are harder to debug — use a single Action that orchestrates multiple steps internally when practical.

---

Prerequisites

Before you can create Actions, you need:

1. A configured Sink Type — see Sink Types & Configuration
2. At least one Library attached to that Sink Type
3. At least one Library Module inside that Library

---

Next Steps

• Getting Started — the full workflow from Sink Type to running automation
• Core Concepts — detailed definitions of all entities
• Event Types & Actions — UI reference for the Flows screen