Operations

Operations coordinate asynchronous work across a fleet. They are useful when you want to roll out a change, run diagnostics, collect results, or drive a maintenance workflow on many devices while keeping track of per-device progress.

An operation is not a script that runs once on the server. It is a server-side plan that Nexigon carries out over time. The plan selects target devices, divides the rollout into stages, applies ordered steps to each selected device, and records progress until every selected target has reached a terminal state.

Core Concepts

An operation belongs to a project and has a name, optional description, target selector, target mode, ordered steps, and one or more stages.

A target selector describes which devices the operation applies to. It can name explicit devices, match devices by device properties, or combine both. Property matching can look at the whole property value or at a field inside a JSON value using a structured JSON path.

A target mode is determined by whether the operation has an enrollment interval:

• Snapshot resolves matching devices once when the operation starts. Devices that match later are not added.
• Dynamic has an enrollment interval and re-evaluates matching devices while the operation is running, so devices that start matching later are picked up. Omitting the interval creates a snapshot operation. The current UI initially suggests one hour, but the API has no dynamic default.

Enrollment only ever adds devices. A device that stops matching keeps the work it already has, because abandoning a half-finished operation on a device is worse than finishing it.

A stage is a rollout ring, and it works as a gate rather than a batch. Each stage covers a percentage of matching devices, such as 1, 10, and 100 percent. Membership is deterministic for a given operation and device, so a device never drifts between stages, and because the percentages grow, a device is only ever run once: it belongs to the first stage that contains it.

Every matched device gets its work as soon as it is enrolled, tagged with the stage that gates it. A device in a stage the rollout has not reached yet is simply Pending: its work exists and is waiting for the gate to open. This is why the target table shows the whole rollout from the start, and why advancing a stage is immediate. It creates nothing; it opens a gate.

The active stage index is the rollout frontier: every stage up to and including that index is activated and can keep progressing. Advancing activates the next stage without waiting for targets in earlier activated stages to finish.

A step is one action in an operation. The same ordered step list runs for each target device selected by a stage. Nexigon currently supports steps that set, update, or remove a device property, wait for a device property to match a predicate, and ask a device to run an on-device command.

A guard controls whether a running operation can advance from the frontier stage to the next stage. Guards can require enough frontier-stage targets to succeed, limit failures, check device properties, or wait until a scheduled timestamp. Stages can also opt into automatic advancement once their guard passes.

When to Use Operations

Use operations for workflows that need coordination, progress tracking, or staged rollout control:

• roll out an OTA update to canary devices before expanding to the fleet;
• set configuration properties across a selected group of devices;
• run diagnostics and collect structured output from each device;
• wait until devices report that a desired state has actually been applied;
• stop a rollout when too many devices fail or do not report the expected property state.

For a one-off action on a single device, an on-demand device command is often enough. Operations build on the same command mechanism but add targeting, staging, progress, and guardrails.

Creating an Operation in the UI

Open your organization in Nexigon and select Operations from the fleet management sidebar. Choose a project, then click New Operation.

Operations must be enabled on the Nexigon Hub instance and, when subscriptions are enforced, included in the organization’s plan. The sidebar entry is hidden when the feature is unavailable.

The dialog provides templates for common workflows:

For template-based operations, you can set:

• Re-enrollment interval: leave blank for a snapshot, or set an interval to keep enrolling new matches.
• Stages: comma-separated rollout percentages such as 1,10,100.
• Target Property and Target Value: an optional property predicate that selects devices.
• Template-specific fields such as the command name, desired version, property name, JSON value, timeout, or maximum error percentage.

Creating an operation stores it as a draft. Click Start to run it: devices are selected and server-side work begins straight away. For multi-stage operations, use Advance to activate the next stage once the frontier guard passes. Stages with automatic advancement open the next gate on their own as soon as the same criteria pass.

Use Pause to halt a rollout without undoing it. Nothing is cancelled, no new devices are enrolled, and no new work is handed out, but a device that already took a work item can still report its result. Starting a paused operation resumes it exactly where it left off. Use Cancel to stop an operation for good.

Preparing Devices

Property steps are applied by Nexigon Hub and do not require special device-side operation code. Devices only need to publish the properties that the operation uses for targeting, waits, or guards.

Device command steps require Nexigon Agent support on the device:

[commands]
enabled = true
directory = "/etc/nexigon/agent/commands"

[operations]
enabled = true
poll-interval-secs = 60

Commands and operation polling are disabled by default and must be enabled explicitly. The polling interval is how long an idle agent waits between polls; once a poll returns work, the agent keeps going without waiting, so a multi-step operation is not paced by this interval. Every enabled device polls on it regardless of whether there is work, so shortening it costs the hub and that cost grows with the fleet.

For DeviceCommand steps, the command name in the operation must match a command published by the device in its command manifest. See Device Commands for the command definition format and handler protocol.

Designing a Rollout

A robust rollout usually has two parts: a desired-state step and an observed-state step.

For example, a property-driven OTA rollout can:

1. Set a protected desired-version property, such as dev.nexigon.ota.desired.
2. Wait until the device reports the matching current version in another property, such as dev.nexigon.ota.current.
3. Advance only if enough targets succeeded, enough devices report the expected state, and any scheduled stage time has arrived.

This pattern keeps the operation declarative. Nexigon records the desired state, the device applies it with its own update logic, and the operation waits for evidence that the device converged.

Use UpdateDeviceProperty when the desired state should preserve parts of an existing JSON property, such as adding one feature flag or merging rollout metadata. Use VersionRequirement predicate expressions when a rollout should select, skip, or wait on version ranges rather than exact version strings.

Command-driven workflows follow the same shape. A DeviceCommand step can trigger bounded local work, such as collecting diagnostics, and a later wait step can confirm the final device-reported state.

A DeviceTask step is intended for device-side work that runs through multiple phases, reports progress, and resumes after an interruption, such as an OTA handler that checkpoints before a reboot. It is not executable yet: nothing currently runs task work. See the Operations reference for details.

Monitoring Progress

The Operations page shows the operation queue, lifecycle status, activated stage frontier, progress, and target table. Each target records:

• the stage and step it is currently on;
• whether it is pending (its stage has not opened yet), running, succeeded, failed, timed out, or cancelled;
• the last error, if any;
• structured output reported by a device command.

An operation completes automatically once the final stage has been activated and all selected targets are terminal. Failed and timed-out targets are terminal too; they do not block completion after the final stage is active, but they are counted as failures and can block advancement through guards.

If the selector matches no devices, the target table stays empty. A snapshot operation then completes successfully. A dynamic operation remains available to pick up later matches only when it was created with closeWhenConverged set to false; the current UI does this whenever a re-enrollment interval is present.

Starting an operation, advancing a stage, and a device reporting a step all take effect immediately, so a rollout moves at the pace of the devices rather than of a scheduler. What runs in the background is only what nothing else triggers: enrolling newly matching devices, re-evaluating guards, noticing that a waited-for property has changed, and timing steps out. Those are noticed within a short interval rather than instantly, so a step times out shortly after its deadline rather than exactly on it.

Automation

Operations are also available through the Actions API. User-facing automation usually calls the project-level actions to create, query, start, advance, and cancel operations. Device agents use the device-only polling and reporting actions internally.

See the Operations reference for the full operation model, step types, status values, and API actions.