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	When to increment
`majorVersion`	Breaking changes to the step structure or parameter schema
`minorVersion`	New optional steps or parameters (backward-compatible)
`patchVersion`	Fixes to parameter values, conditions, or descriptions

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.

Registering with the Engine

Deploy a workflow definition via the REST API:

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

Or use the Monitor App's workflow definition editor.

Schema validation

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