Core Concepts
This page explains the core entities you will work with when building automations. Understanding these concepts makes the UI and configuration straightforward.
Events
Section titled “Events”An Event is a single unit of work. It is created when a Source fires and carries:
- A Flow — what kind of task should run
- A payload — a JSON document of data passed to the executing module
- A state — tracks where the event is in its lifecycle
Event States
Section titled “Event States”| State | Meaning |
|---|---|
QUEUED | Waiting for an available Sink |
RUNNING | A Sink is currently executing the task |
SUCCESS | Completed successfully |
WARNING | Completed with warnings |
ERROR | Failed |
TIMED_OUT | Superseded by a newer schedule firing — the event was queued but never dispatched |
Events are never deleted automatically. They accumulate as an audit trail and can be queried and filtered on the Events screen.
A Flow (the user-facing name for what the API calls an Event Type) is a named definition that describes:
- Which Sink Type should execute the task (e.g. a Python sink, a PowerShell sink)
- Which Source Type is allowed to fire it
- Which Action to run when the event dispatches
- The chain — what runs next on success or failure (see Chaining)
Think of a Flow as a template. One Flow can be triggered by many individual events over time. Flows are created and managed on the single Flows screen (sidebar → Flows): pick the trigger, the target, the action — and, once the flow exists, its chain.
Parameters are configured on the Action, never on the flow — see Actions.
Actions
Section titled “Actions”An Action defines the code that executes when a Flow fires. It is a pure, reusable definition:
- A module — a reference to a Library Module that contains the code to execute
- Parameters — ordered key/value pairs injected at runtime (
STATIC/DATA/SECRET)
Actions carry no chaining configuration — chaining is flow-scoped (see below). The same Action can be linked to many Flows, which makes it easy to share common tasks (e.g. a sendmail failure handler) across different triggers.
Chaining
Section titled “Chaining”Chaining is defined per flow, because the same action means different follow-ups in different flows. A chain link is:
(from action, success|failure) → (next action, runs on …)- Fan-out: an action can have several successors per outcome — each runs as an independent branch, in the order you set.
- Runs on: defaults to auto (the flow’s own sink type). Pick another sink type for steps that need a different machine; the next action’s module must be available on that type.
- Depth: a chained action can itself chain further.
When an action finishes, the sink reports the outcome and result data. The Hub resolves the flow’s links and creates one chained event per matching link — the result data becomes the payload. No matching link → the run ends.
See the Actions & Libraries guide for a full walkthrough.
Every event of a single trigger run shares a run id, stamped on the root event and inherited by every chained event — including fan-out branches. Click the run badge on the Events screen to see the whole run as one tree; the Logs screen shows the Flow and Action columns so each log entry points at its step.
The module-level Result.Next mechanism (modules naming the next event type) is deprecated — chaining is defined in the flow editor only.
Libraries
Section titled “Libraries”A Library is a named collection of code modules attached to one or more Sink Types. It represents a package or bundle of related functionality.
| 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 the library is attached to |
Libraries are managed on the Libraries screen (sidebar → Automation → Libraries): platform templates (multi-tenant, read-only, copied with Make my copy — the copy pins its version) and your libraries (created and edited by your tenant, including modules).
Library Modules
Section titled “Library Modules”A Library Module represents a single importable code unit within a Library. It is the entity that an Action references as its executable code.
A module’s import name is what the sink agent resolves at runtime (e.g. my_package.process_data). Modules can carry an optional description, shown as helper text in module pickers. One Library typically contains several related modules.
The relationship chain is:
SinkType → Library → LibraryModule → Action → FlowSee the Actions & Libraries guide for details on creating and configuring Libraries and Modules.
Sources
Section titled “Sources”A Source is a registered instance of a source client — for example, a specific webhook endpoint or a running EventGrid consumer.
Sources are associated with a Source Type, which defines what kind of source it is (webhook, scheduler, EventGrid, or custom).
Types vs instances vs nodes
Section titled “Types vs instances vs nodes”The three layers:
- Source Type — the definition. Either a platform template (Webhook,
Scheduler, EventGrid, MCP —
systemflag) or your tenant’s copy of one. Templates are inert: to use one, click Make my copy on the Types tab — the copy gets the template’s config params, secret, and node coverage verbatim, and shows “based on ”. One copy per template per tenant; every new tenant starts with a Scheduler copy already made.- Source — your tenant’s instance of a type (its own UUID, status, config). Creating or copying a type never creates an instance.
- Node — the deployed worker that runs the source (webhook node, scheduler node, …). Assignment is automatic; the Instances tab derives each source’s health chip (Awaiting node / Online / Offline) from the node’s heartbeats.
A Sink is a registered agent process running in your infrastructure. It connects outbound to the Hub and waits for tasks.
Sinks are associated with a Sink Type, which defines what code the agent can run (Python, PowerShell, custom).
The same types/instances/nodes layering applies: platform sink templates are copied with Make my copy (libraries & modules ride along; copies default to self-hosted on your machines), Sinks are the tenant’s instances, and nodes run them — with the same Awaiting node / Online / Offline health derivation on the Instances tab.
When you deploy a sink agent, it registers itself with the Hub and appears on the Sinks screen. From there you can see its status, last seen time, and send control signals.
Schedules
Section titled “Schedules”A Schedule is a cron expression linked to a Flow. The Scheduler source evaluates all active schedules and fires the corresponding Flow at the configured time.
Cron expressions follow standard 5-field format:
┌───── minute (0-59)│ ┌──── hour (0-23)│ │ ┌─── day of month (1-31)│ │ │ ┌── month (1-12)│ │ │ │ ┌─ day of week (0-6, Sunday=0)* * * * *Examples:
Expression Meaning 0 9 * * 1-5Every weekday at 09:00 */15 * * * *Every 15 minutes 0 0 1 * *First day of every month at midnight Schedules can optionally be pinned to a specific Sink so the task always runs on a particular agent.
Secrets
Section titled “Secrets”Secrets are tenant-scoped key/value pairs stored securely in Nexomatic. Values are write-only — they cannot be retrieved through the UI after creation.
Sink modules access secrets at runtime via the Hub. This means credentials never need to be embedded in code or passed in event payloads.
Reference a secret in an Action parameter by setting the parameter type to
SECRETand the value to the secret’s key name.
Every task execution produces a Log — structured records written by the module during execution, plus a raw log file containing full stdout output.
Logs are retained for a configurable period. Older logs are transparently archived to blob storage and remain queryable from the Logs screen.