Action Plan Executor

The Action Plan Executor runs action-plan scripts that guide the response to an alarm -- automated steps, such as pulling up video, interleaved with points where an operator decides what to do next.

Overview

An action plan (APSL) is a script for handling an alarm: it can take automatic actions and pause for the operator to choose how to proceed. The Action Plan Executor runs these scripts, keeps track of where each one has got to, and waits for operator input wherever the plan calls for it.

1. Runs: When configured. Work is shared across instances.
2. Required: Only if you use action plans. Alarms are handled normally without it.
3. Depends on: NATS; the services an action's steps use (for example video and detection); and, when scripts are loaded from SBN, the SBN Frontend.

Prerequisites

The executor is an SBN Media service, so it needs a working SBN Media platform underneath it -- chiefly a running NATS cluster, which every service uses to communicate and which the executor also uses to share execution state across instances. Set that up first; see NATS Configuration for SBN Media and Installing and Configuring SBN Media.

How an incident reaches the executor

The executor does not poll for alarms itself — incidents are fed to it by the auto-queue (the SBN APSL service):

1. The auto-queue polls the SBN alarm queue on an interval for alarms routed to the APSL terminal. Polling is enabled per host; with it off, the executor simply runs nothing until something starts a plan.
2. When it finds one it takes it (exactly‑once, so no other operator or instance double-takes it), fetches the incident's context, and validates the script.
3. It then hands the incident to the executor, which begins running the plan and acknowledges the alarm — the moment it shows up as an active plan.

So the chain is SBN alarm queue → auto-queue takes and validates → executor runs the plan. If incidents are not reaching the executor, check the auto-queue first: is polling enabled, and does the APSL operator have access to those alarms (correct branch/dealer, and the alarms actually routed to the APSL terminal)?

Configuration

The Action Plan Executor is configured under the apslexecutor namespace. The most useful settings:

After changing settings in sbn-media.local.yaml, apply them with ./sbn-media config reload.

Monitoring active plans

Check that the executor is up:

sbn-media watch health streams live health updates. Point it at the executor and include diagnostics to see the plans running right now:

The diagnostics report three things:

Watch activeExecutions for the live load: entries appear when the auto-queue starts a plan and drop off when an incident resolves. If the count sits at maxConcurrent and new plans are not starting, the instance is at capacity. Operators also see the plans that belong to their own terminal in the operator UI; the watch health view is the node-wide picture for administrators.

For detail on a specific incident, tail the log -- every action, intervention, and resolution is logged with the incident ID:

When an incident gets stuck

If an action fails (an unreachable downstream system, a timeout, a connection drop) the plan does not silently stall -- the executor raises an action-failed intervention and hands the decision to the operator:

In-progress plans are checkpointed, so a service restart does not lose an in-flight incident: on restart, any action that was interrupted is surfaced to the operator as an action-failed intervention (Action @<action> was interrupted by system restart), and orphaned resources are cleaned up. (State survives a restart only when apslexecutor.state.backend is nats.) An incident that needs an external event -- a guard or police arrival, say -- leaves the operator's active view while it waits and returns to the queue when the event arrives or the timeout expires.

Operational notes

1. @auto video failures currently raise an operator intervention rather than soft-failing, so a plan can pause on a video problem; if you see plans stalling at a video step, check video connectivity for that site.
2. Completed-incident state cleanup depends on the state store's expiry; on long-lived deployments keep an eye on state-store growth.
3. Instruction layers (dealer/installation/temporary overrides) are not yet applied at run time -- the executor runs a single plan per incident today.

FAQ

What is an action plan? A script for responding to an alarm -- automatic steps plus points where the operator makes a decision. See the APSL Specification for the language.

Where do the scripts come from? Each incident's action plan is stored in SBN; the auto-queue fetches it together with the incident and hands the script to the executor to run.

Can plans run across instances and survive a restart? Set apslexecutor.state.backend to nats so in-progress plans are kept centrally rather than in one instance's memory.

Related pages

1. SBN Media Overview
2. Installing and Configuring SBN Media
3. NATS Configuration for SBN Media
4. APSL Specification
5. SBN APSL
6. Watchdog