Workflows

A workflow is a versioned, declarative description of a sequence of operations to perform on network entities. Think of it as a recipe: it lists the steps, their order, the conditions under which they run, and how they connect to each other through data.

Anatomy

Every workflow is a YAML document with these parts:

Part	Purpose
Metadata (package, name, version)	Uniquely identifies the workflow (package/name:major.minor.patch).
Seed Entity (device, interface, group, client, global)	Defines the execution scope for contexts created at run time.
Acquire (optional)	Pulls additional entities into the execution context.
Steps	Ordered operations to run. Each step is a functionBlock, an embedded workflow, or a workflowReference.

Metadata identifies the workflow uniquely: a package namespace, a name, and a semantic version (major.minor.patch). The combination package/name:major.minor.patch is the workflow's identity.

Seed Entity declares what type of entity this workflow is designed to run on. When you execute the workflow, you provide IDs or queries for entities of this type. The engine creates one execution context per entity.

Acquire (optional) defines additional entities to pull into the execution context -- devices by Elasticsearch query, interfaces by expansion from the seed device, or references to other steps' results.

Steps are the operations. Each step is one of three types:

Type	What it does
functionBlock	Executes a registered function block
workflow	An inline (embedded) sub-workflow with its own steps
workflowReference	A reference to another workflow definition (by package/name/version)

Steps execute in order. Each step can have parameters (with JMESPath interpolation), conditions (skip if false), assertions (fail if false), retry configuration, and an acquire clause for additional entities.

A Minimal Workflow

# A minimal workflow that runs a single function block.
# Uses seedEntity: global so it works without CMS -- ideal for getting started.
label: hello_world
name: hello_world
package: wf.example.neops.io
majorVersion: 1
minorVersion: 0
patchVersion: 0
seedEntity: global
type: workflow

steps:
  - type: functionBlock
    label: echo
    functionBlock: "fb.examples.neops.io/echo:1.0.0"
    parameters:
      message: "Hello from the neops workflow engine!"

This workflow:

• Is identified as wf.example.neops.io/hello_world:1.0.0
• Runs with seedEntity: global (no specific device or CMS connection required)
• Has one step: execute the echo function block with a static message parameter
• Uses the simplest possible structure -- ideal for a first deployment test

Versioning

Workflows follow semantic versioning:

• Major version: breaking changes (different step structure, incompatible parameters)
• Minor version: backward-compatible additions (new optional steps, new parameters with defaults)
• Patch version: fixes (corrected parameter values, updated conditions)

When referencing a workflow, you can specify a full version (1.2.3), a partial version (1.2 or 1), or let the engine resolve the latest matching version. See Function Block Resolving for the resolution algorithm (it works identically for workflows).

Seed Entity Types

The seedEntity determines the execution scope:

Seed Entity	Execution scope	Typical use case
device	One execution context per device	Config backup, version collection, compliance checks
interface	One execution context per interface	Interface enable/disable, port security
group	One execution context per device group	Group-level aggregation, batch operations
client	One execution context per client	Client provisioning, access management
global	One execution context (no specific entity)	Subnet discovery, report generation

How seed entities drive execution

When you execute a workflow with seedEntity: device and provide deviceIds: [1, 2, 3], the engine creates three parallel execution paths -- one per device. Each path runs through all steps independently. This means device 1 might be on step 3 while device 2 is still on step 1, depending on worker availability and execution speed.