IActionPlugin

Interface in Oadm.Sdk.Actions · Oadm.Sdk.dll

An action of the event rules (“Set output”, “Run VAPIX command”, “Send email”). Registered by the loader like task plugins: a public class with a parameterless constructor in a plugin’s *.Server.dll, or contributed by a core plugin (IActionSource.ActionPlugins). Settings are declared with IActionPlugin.Fields; the client draws the form, so most actions need no client part.

public interface IActionPlugin : IPlugin

Extends IPlugin

Guide: Event rules

Properties

Description

string? Description { get; }

Default implementation

One short sentence for the action picker (optional).

Fields

IReadOnlyList<ActionField> Fields { get; }

The settings form, drawn by the rule dialog and checked on the server.

Group

string Group { get; }

Default implementation

Group of the action picker, e.g. “Devices”, “Notifications”. Default “General”.

NeedsDevice

bool NeedsDevice { get; }

True: the action acts on devices; the rule picks the targets (the device of the event, chosen devices, tags, all) and the action runs once per target with a pre-authenticated IActionContext.Vapix. False: it runs once per rule edge without a device (email, webhook).

SupportsTurnOff

bool SupportsTurnOff { get; }

Default implementation

True: the action has a “When the rule turns off” part (fields with ActionField.OffEdge, or the action undoes itself, e.g. “Follow the rule”), so it also runs on ActionEdge.TurnedOff.

UsesPlaceholders

bool UsesPlaceholders { get; }

Default implementation

True: the action’s texts are written for placeholders ({device}, {event}, the event’s values), so the rule dialog shows the Placeholders list next to it (email, webhook). False hides the list for this action.

Methods

Describe

string Describe(JsonElement settings)

Default implementation

One line for the rule list: “Pulse output 1 for 5 s”. Default: the display name.

ExecuteAsync

Task ExecuteAsync(IActionContext ctx, ActionInvocation invocation, CancellationToken ct)

Runs the action. Return normally for success; throw for a failure (the message goes into the event log). The host cancels ct after the action timeout (30 s) or when the server stops.

ListChoicesAsync

Task<IReadOnlyList<ActionChoice>> ListChoicesAsync(IActionQueryContext ctx, string fieldKey, CancellationToken ct)

Default implementation

The choices of a ActionFieldType.DynamicChoice field (read-only). Default: none.

MaxRunTime

TimeSpan? MaxRunTime(JsonElement settings)

Default implementation

How long one run may take with these settings when it needs longer than the host’s default (30 s), e.g. a pulse the device only answers after it ended. Null: the default. The host never uses less than its default.

RunsOn

bool RunsOn(ActionEdge edge, JsonElement settings)

Default implementation

Whether this edge needs a run with these settings (e.g. no “off” command chosen). Default: Fired and TurnedOn always, TurnedOff when IActionPlugin.SupportsTurnOff.

Validate

IReadOnlyDictionary<string, string> Validate(JsonElement settings, bool statefulRule)

Default implementation

Checks the settings before a rule is saved; returns errors per field key (“” for the whole action). The host has already checked required fields, numbers and choices. Default: no further errors.

Used by

• IActionSource.ActionPlugins