Skip to content

Glossary

Key terms used throughout the neops Worker SDK documentation.

A

Acquire phase : The first phase of function block execution. Called before run() to request additional data from the CMS or lock shared resources. Every function block must implement acquire().

B

Blackboard : A job queue managed by the workflow engine. When a workflow executes, the engine writes jobs to the blackboard. Workers poll the blackboard for jobs they can execute.

Blocking detector : A runtime monitor that warns when synchronous (blocking) calls run inside the async event loop. Helps identify code that should use @run_in_thread.

C

Capability interface : An abstract base class that declares a set of methods a connection plugin can implement (e.g., DeviceInfoCapability with get_version()). Proxies inherit from capabilities to declare what they need.

CMS (Content Management System) : The neops core application. Stores devices, interfaces, groups, users, facts, checks, and configuration versions. Function blocks receive CMS data through WorkflowContext.

CMS documentation is forthcoming. For how the engine uses CMS data in workflows, see the
[Context concept](/neops-workflow-engine/docs/10-concepts/30-context/) and
[Glossary](/neops-workflow-engine/docs/99-appendix/#cms-content-management-system) in the
Workflow Engine docs.

Connection plugin : A class that implements capability methods for a specific platform and connection library. Registered via @register_connection_plugin().

Connection proxy : The user-facing object for device communication. Declares required capabilities via inheritance and delegates method calls to the resolved plugin at runtime.

D

Decorator : A Python construct (using the @ syntax) that wraps a class or function to add behaviour. The SDK uses decorators like @register_function_block and @register_connection_plugin for discovery and metadata attachment.

Device : A network device managed by neops. Has properties like hostname, IP, platform, credentials, and associated facts.

DTO (Data Transfer Object) : A plain data class used to pass structured information between systems. In the SDK, DeviceTypeDto (from the workflow engine client) carries device data through the WorkflowContext.

E

Entity : A CMS data object — Device, Interface, or DeviceGroup. Function blocks can read, modify, and create entities through WorkflowContext.

F

FAILED_SAFE : A job failure state assigned when all executed function blocks in the workflow were pure or idempotent. Indicates the workflow is safe to retry because no irreversible side effects occurred. See Pure and Idempotent.

FAILED_UNSAFE : A job failure state assigned when at least one non-pure, non-idempotent function block executed before the failure. The workflow cannot be automatically retried. See Pure and Idempotent.

Facts : Arbitrary JSON data associated with a device. Function blocks write facts (e.g., device.facts["version"] = {...}) and the SDK persists them to the CMS automatically via change tracking.

Function block : A reusable unit of automation logic. Takes typed parameters, receives a WorkflowContext, executes logic, and returns typed results. Composed into workflows.

I

Idempotent : A function block that can be safely re-executed with the same inputs without unintended side effects (e.g., pushing a configuration that replaces the current config). Enables automatic retry on failure.

J

Job : A unit of work on the blackboard. Contains a function block ID, parameters, and execution context. Workers poll for and execute jobs.

N

Neops workflow engine : The orchestration service that manages workflow definitions, function block registration, and job lifecycle (PENDING → POLLED → PUSHED).

See the [Workflow Engine documentation](/neops-workflow-engine/docs/) for workflow definitions,
execution lifecycle, retry logic, and the Blackboard API.

P

Parameters : Typed inputs to a function block, defined as a Pydantic model extending FunctionBlockParams. Uses extra="ignore" for forward compatibility.

Pydantic : A Python data-validation library that the SDK uses for parameter and result models. Define fields with type annotations, and Pydantic handles validation, coercion, and JSON schema generation automatically. See pydantic.dev.

Plugin resolution : The algorithm that selects a connection plugin based on platform, connection type, library, and required capabilities.

Pure : A function block with no side effects — it only reads data. A failed pure block always results in FAILED_SAFE, allowing the workflow to be retried.

Proxy → see Connection proxy

R

Registration : The metadata associated with a function block: name, package, version, description, run_on entity type, purity/idempotency flags, and parameter/result JSON schemas. Sent to the workflow engine at startup.

Remote lab : A FastAPI service that provisions Netlab/Containerlab topologies on demand for integration testing against real virtual devices. See Remote Lab Testing.

Result : Typed output of a function block, defined as a Pydantic model extending FunctionBlockResultData. Uses extra="forbid" for strict validation.

W

Worker : A running instance of the neops Worker SDK. Discovers and registers function blocks, then polls the blackboard for jobs to execute.

Workflow : A YAML-defined sequence of function block executions with conditions, retries, and error handling. Managed by the workflow engine.

WorkflowContext : The data context passed to a function block's run() method. Contains devices, interfaces, groups, and the entity the block runs on. Changes made to entities are automatically tracked and persisted.