Custom actions add module-defined actions to Security Center's event-to-action system. They appear alongside built-in actions in event-to-action rules, hot actions, scheduled tasks, and other automation contexts. Implementing a custom action requires two parts:

• A server-side plugin that registers the custom action type in the system configuration and handles action execution when triggered
• A Workspace SDK module that provides the configuration user interface through a CustomActionBuilder and CustomActionView

Both parts must share the same custom action type GUID. Without the server-side plugin, the CustomActionBuilder in the Workspace SDK has no matching descriptor, and IsSupported() returns false. The custom action does not appear in the user interface.

Custom actions are designed for operations that require server-side plugin logic. Use custom actions when you need to:

• Execute plugin-specific logic on the server when an event-to-action rule triggers
• Provide operators with a configurable action that integrates into Security Center's automation rules
• Route actions to a specific plugin role with a custom payload

1. The module registers a CustomActionBuilder with the workspace during Load
2. When an operator configures an automation rule, the system calls IsSupported() with a CustomActionContext containing the action type and usage context
3. If supported, the system calls CreateView() to obtain a CustomActionView. The builder's CreateView() implementation must call Initialize(Workspace) on the view before returning it
4. The system sets the view's Usage, SourceEntityType, and TriggerEvent properties, populates Recipients from any previously saved configuration, and calls Deserialize() with the previously stored payload string
5. The system calls OnInternalInitializationDone() on the view. At this point, all context properties and deserialized state are available
6. The operator configures the action through the view's interface, setting the Recipients and any custom parameters
7. When the configuration changes, the view calls OnModified() to notify the system
8. When the operator saves, the system calls Serialize() to persist the action's configuration as a payload string
9. When the configuration dialog closes, the system calls Dispose() on the view

When the action triggers, the system sends the action to the recipients specified in the view's Recipients collection. The server-side plugin receives the action through the Engine.ActionReceived event. The ActionReceivedEventArgs provides:

The CustomAction object exposes:

Custom actions can also be triggered programmatically through Engine.ActionManager.SendCustomAction(). For more information, see Triggering custom actions programmatically.

The Recipients collection determines which entities receive the action when it triggers. At least one recipient is required for the action configuration to be valid. The recipient is typically the GUID of the plugin role that handles the action. To obtain the plugin role GUID from the workspace, query the entity that the plugin owns and read its OwnerRole property.

Recipients can be any entity GUID, but the system resolves each recipient to the application that owns it for delivery. If a recipient entity does not exist or its owning application is unavailable, that recipient is silently skipped.

Inherit from CustomActionBuilder and implement the abstract members:

public class MyActionBuilder : CustomActionBuilder
{
    public override Guid CustomActionType => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override CustomActionView CreateView()
    {
        var view = new MyActionView();
        view.Initialize(Workspace);
        return view;
    }
}

The context passed to IsSupported provides:

The ActionUsage flags enum indicates where the action is used:

CustomActionView inherits from UserControl. Define the configuration interface in XAML with CustomActionView as the root element:

<customAction:CustomActionView x:Class="MyPlugin.Views.MyActionView"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:customAction="clr-namespace:Genetec.Sdk.Workspace.Components.CustomAction;assembly=Genetec.Sdk.Workspace">
    <Grid>
        <!-- Configuration controls -->
    </Grid>
</customAction:CustomActionView>

Implement the code-behind to handle serialization and recipient selection:

public partial class MyActionView : CustomActionView
{
    private Guid m_targetId;

    public MyActionView()
    {
        ActionName = "My Custom Action";
        ActionDescription = "Performs a custom operation.";
        InitializeComponent();
    }

    public override void Initialize(Workspace workspace)
    {
        base.Initialize(workspace);
        // Set up data sources. Context properties (Usage, SourceEntityType, TriggerEvent)
        // are not yet available here.
    }

    protected override void OnInternalInitializationDone()
    {
        // All context properties and deserialized state are now available.
        // Use Usage, SourceEntityType, TriggerEvent, and Recipients here.
    }

    protected internal override string Serialize()
    {
        return m_targetId.ToString();
    }

    protected internal override void Deserialize(string payload)
    {
        if (Guid.TryParse(payload, out var id))
        {
            m_targetId = id;
        }
    }

    private void OnTargetSelected(Guid targetId, Guid pluginRoleId)
    {
        m_targetId = targetId;
        Recipients.Clear();
        Recipients.Add(pluginRoleId);
    }
}

The server-side plugin registers the custom action type in the system configuration and handles action execution.

In the plugin's OnPluginLoaded method, create a CustomActionTypeDescriptor and register it with the system configuration. Use AddOrUpdateCustomActionType to register the descriptor. If a descriptor with the same GUID already exists, it is replaced entirely with the new one.

protected override void OnPluginLoaded()
{
    var systemConfiguration = Engine.GetEntity<SystemConfiguration>(SystemConfiguration.SystemConfigurationGuid);
    var descriptor = systemConfiguration.GetCustomActionTypeDescriptor(CustomActionTypeId);

    if (descriptor == null)
    {
        descriptor = new CustomActionTypeDescriptor(CustomActionTypeId, "My Custom Action")
        {
            SupportedActionUsage = ActionUsage.All,
            Privilege = SdkPrivilege.TriggerAlarm,
        };

        systemConfiguration.AddOrUpdateCustomActionType(descriptor);
    }
}

The CustomActionTypeDescriptor defines the action type's metadata:

Subscribe to Engine.ActionReceived and filter for your custom action type:

Engine.ActionReceived += (sender, e) =>
{
    if (e.ActionType == ActionType.CustomAction && e.Action is CustomAction customAction && customAction.CustomActionType == CustomActionTypeId)
    {
        var payload = customAction.Payload;
        var recipient = customAction.Recipient;
        var sourceEvent = customAction.SourceEvent;
        // Execute the custom action logic
    }
};

If no handler is subscribed for a custom action type, the action is delivered and discarded without error.

Call RemoveCustomActionType to remove the descriptor from the system configuration. Existing event-to-action rules that reference the removed descriptor are not deleted. Those rules continue to exist but the custom action no longer appears in the configuration user interface.

systemConfiguration.RemoveCustomActionType(CustomActionTypeId);

Custom actions can be triggered programmatically through the SDK without event-to-action rules. Call Engine.ActionManager.SendCustomAction() with the descriptor GUID, a list of recipient entity GUIDs, and the payload string:

var recipients = new List<Guid> { pluginRoleGuid };
Engine.ActionManager.SendCustomAction(CustomActionTypeId, recipients, payload);

This method validates that the descriptor exists, the current user has the required privilege, at least one recipient is provided, and the payload is not empty. It throws an SdkException if any validation fails.

Register the builder in your module's Load method:

public class SampleModule : Module
{
    private MyActionBuilder m_actionBuilder;

    public override void Load()
    {
        m_actionBuilder = new MyActionBuilder();
        m_actionBuilder.Initialize(Workspace);
        Workspace.Components.Register(m_actionBuilder);
    }

    public override void Unload()
    {
        if (m_actionBuilder != null)
        {
            Workspace.Components.Unregister(m_actionBuilder);
        }
    }
}