Skip to content

Workflow Definition

A workflow definition is a YAML document that describes a versioned automation pipeline. It is registered with the engine and can be executed multiple times with different parameters and entity scopes.

YAML authoring, JSON deployment

Workflows are authored in YAML for readability, but the REST API and Monitor App currently accept JSON. Convert with yq -o=json workflow.yaml or see the Getting Started guide for more options.

Root Structure

Every workflow has these required fields:

label: my_workflow          # Unique identifier (alphanumeric + underscore)
name: my_workflow           # Human-readable name
package: wf.example.neops.io  # Namespace (reverse domain)
majorVersion: 1
minorVersion: 0
patchVersion: 0
seedEntity: device          # device | interface | group | global
type: workflow              # Always "workflow" for the root
steps: [...]                # At least one step

Identity

The combination of package, name, and version forms the workflow’s unique identity:

wf.example.neops.io/my_workflow:1.0.0

This is used when referencing workflows from other workflows and when triggering executions.

Versioning

Workflows follow semantic versioning:

Version part What it signals
majorVersion Breaking changes to the step structure, runOn/seedEntity, or a step’s function block/workflow pin
minorVersion New optional steps, parameters, or acquire/assert rules (backward-compatible)
patchVersion Fixes to parameter values, conditions, descriptions, or retry/repeat config

These are conventions you still have to intend – the engine cannot know why you changed something. What it does enforce is a floor: publishing computes the smallest bump your changes honestly justify from the previous version, and refuses a declared version that bumps by less than that, unless you tell it explicitly that the floor is wrong. See Publishing & Versioning for the full classification and how to override it.

The engine stores all versions. When you reference a workflow by partial version (e.g., 1.0 or 1), the engine resolves it to the latest matching patch or minor version.

Seed Entity

The seedEntity determines what type of entity this workflow operates on:

Value What happens at execution
device Execution creates per-device context from the provided device IDs or query
interface Execution creates per-interface context
group Execution creates per-group context
global Single execution context, not tied to a specific entity

Optional Root Fields

Field Type Purpose
description string Human-readable description (max 1000 chars)
parameterSchema object JSON Schema for execution parameters
acquire array Entity acquisition rules (see Acquire)
config object Execution configuration (e.g., executionStrategy.parallel)
condition object Root-level condition (JMESPath, skip entire workflow if false)
assert array Root-level assertions (fail if any is false)
cron array Scheduled execution rules (see Scheduling)
continueOnError boolean Continue on step failure (default: false)
delay number Delay in seconds before starting (0-600)

Parameter Schema

Define the inputs your workflow accepts:

parameterSchema:
  type: object
  properties:
    timeout:
      type: number
      description: "Connection timeout in seconds"
      default: 30
    backup_type:
      type: string
      enum: ["running", "startup"]
      description: "Which config to back up"
  required:
    - backup_type

The schema is validated when the workflow is executed. It also drives parameter form generation in the UI.

Publishing to the Engine

Deploy a workflow definition with POST /workflow-definition/publish, sending the document itself with no envelope:

curl -X POST http://localhost:3030/workflow-definition/publish \
  -H "Content-Type: application/json" \
  -d @workflow.json

See Publishing & Versioning for the full request and response contract – the body and its options, every status code with example bodies, and how the engine decides whether your declared version is honest.

Or use the Monitor App’s workflow definition editor, which drives the same endpoint.

Schema validation

The engine validates workflow definitions against the RootWorkflow JSON Schema on publish. Invalid definitions are rejected with descriptive error messages. You can also validate locally before deployment – see Schema Reference.

The old routes are gone

POST /workflow-definition (create) and POST /workflow-definition/update have been removed in favor of /publish; both answer 404. See The old routes are gone for the payload mapping.