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., NetworkDeviceInformationCapability with get_information()). 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 workflow failure state: no side effects remain. Either no non-pure step ran that may have changed something (every attempt of the others said side_effects=False), or everything that may have was rolled back. The workflow is safe to retry. See Pure and Idempotent.

FAILED_UNSAFE : A workflow failure state: side effects may remain, because an irreversible non-pure step may have changed something or a rollback failed. The entity locks are kept until an operator remediates the run. 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 changes nothing on devices or in external systems. Changes it declares to the CMS through the WorkflowContext (db_updates) do not count, because the engine applies them itself. A pure step is never rolled back, and its failure is retried. See Pure and Idempotent.

Proxy → see Connection proxy

R

Registration : The metadata associated with a function block: name, package, version, description, run_on entity type, purity/idempotency/reversibility flags, and parameter/result/rollback-data 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. The SDK imports remote_lab_fixture directly as a stable public API. See Remote Lab Testing for the SDK-consumer view, and the Remote Lab project docs for the canonical reference (architecture, queue semantics, lab lifecycle, REST contract, deployment).

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

Retryable : The retryable field of a result, True by default. A failure with retryable=False is not retried, whatever the block’s flags; use it for a failure that would come out the same on every attempt.

Reversible : A function block registered reversible=True: the engine may undo it by dispatching a ROLLBACK job that calls its rollback(). See Rollback.

Rollback : Undoing the steps of a failed run that may have changed something, wave by wave in reverse order, through each block’s rollback(). It happens only when every such step is reversible. rollback() receives the forward result of the step, including its rollback data.

Rollback data : A snapshot a reversible block saves with save_rollback_data() in run(), before it changes anything, as an instance of its FunctionBlockRollbackData subclass. The engine stores it with the job result and hands it to the block’s rollback(). See Rollback data.

S

Side effects : Changes a function block makes outside the CMS declarations it returns: on a device, or in an external system. A result says side_effects=False when that attempt made none; the engine then leaves the step out of the rollback once every attempt of it said so. None, the default, means side effects are assumed. See Side effects of one attempt.

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.