platform sdk event to actions

Event-to-actions

An event-to-action links an action to an event: when the event occurs, Security Center executes the action. This page explains how to retrieve, create, update, and remove event-to-action rules through the Platform SDK, and which rule configurations the SDK cannot create.

Note

Use event-to-action rules when your integration must configure an event response through the Platform SDK. The Platform SDK cannot create event-based automations. For the product concept and the Config Tool procedure, find Creating event-to-actions on the Genetec TechDoc Hub.

Rules are stored on a configured source entity through the EventToActions collection exposed by every entity. A rule stored on a door can match events associated with that door and its access points, and a rule stored on an alarm can match events from that alarm. Security Center also evaluates related sources. For example, a rule stored on an area can match events from the area's access points, and a rule stored on a cardholder group can match events from its member cardholders, including nested groups. Rules stored on the SystemConfiguration entity are evaluated for every event (see Creating a system-wide rule).

Building an action

Build the action with ActionManager.BuildAction, and then attach it to a rule with EventToActions.Add on the source entity. The recipient is the entity the action targets (the alarm to trigger, the output to activate), and the schedule restricts when the rule applies:

public EventToAction CreateDoorForcedAlarmRule(
    Engine engine, Door door, Alarm alarm)
{
    Genetec.Sdk.Actions.Action action = engine.ActionManager.BuildAction(
        ActionType.TriggerAlarm,
        alarm.Guid,
        Schedule.AlwaysScheduleGuid);

    return door.EventToActions.Add(
        EventType.DoorOpenWhileLockSecure, action);
}

The door-forced-open condition is the DoorOpenWhileLockSecure event type; the DoorForcedOpen member is marked obsolete and fails compilation with a message that names DoorOpenWhileLockSecure as the replacement.

The event-to-action is enabled when created. Outside a transaction it takes effect without further calls; inside one it takes effect at commit (see Persistence and transactions).

Except for ActionType.CustomAction, the ActionType overload of BuildAction first checks the logged-on user's privileges. It throws SdkException with SdkError.UnsufficientPrivilege when the user cannot create the requested action type. After that check succeeds, it throws SdkException with SdkError.InvalidOperation if BuildAction does not support the requested action type (see Actions that BuildAction cannot create). The PtzCommandType overload does not perform this privilege check. ActionType.CustomAction requires BuildCustomAction; see Custom actions. Both overloads then validate the schedule argument. A non-empty GUID that does not resolve to an entity throws SdkException with SdkError.UnableToRetrieveEntity, and a GUID that resolves to something other than a schedule throws SdkException with SdkError.InvalidEntityType.

To set properties specific to an action class, cast the built action to its concrete type:

public EventToAction CreateMotionRecordingRule(
    Engine engine, Camera camera)
{
    var action = (StartRecordingAction)
        engine.ActionManager.BuildAction(
            ActionType.StartRecording,
            camera.Guid,
            Schedule.AlwaysScheduleGuid);
    action.RecordingLength = TimeSpan.FromMinutes(2);

    return camera.EventToActions.Add(
        EventType.CameraMotionOn, action);
}

Creating a system-wide rule

A rule attached to the SystemConfiguration entity is triggered by the matching event from any entity in the system. This is the same rule that Config Tool creates when the event source is All entities:

public EventToAction CreateSystemWideRule(
    Engine engine, Guid outputGuid)
{
    Entity systemConfiguration = engine.GetEntity(
        SystemConfiguration.SystemConfigurationGuid);

    Genetec.Sdk.Actions.Action action = engine.ActionManager.BuildAction(
        ActionType.TriggerOutput,
        outputGuid,
        Schedule.AlwaysScheduleGuid);

    return systemConfiguration.EventToActions.Add(
        EventType.DoorOpenWhileLockSecure, action);
}

Creating a rule for a custom event

Rules for custom events use the Add overloads that take the custom event id and, optionally, a condition string:

public EventToAction CreateCustomEventRule(
    Engine engine,
    Entity source,
    int customEventId,
    Guid outputGuid)
{
    Genetec.Sdk.Actions.Action action = engine.ActionManager.BuildAction(
        ActionType.TriggerOutput,
        outputGuid,
        Schedule.AlwaysScheduleGuid);

    return source.EventToActions.Add(
        EventType.CustomEvent, action, customEventId);
}

Add throws SdkException with SdkError.InvalidOperation when the custom event ID is missing or zero. Every overload throws the same exception when the action cannot be used in an event-to-action rule or the source entity does not support the rule's event type.

Enumerating and disabling rules

Each read of EventToActions returns a collection populated with the rules at that time. Do not rely on a previously retrieved collection or its EventToAction objects to represent the current configuration after any rule changes. Read EventToActions again before inspecting the current rules.

To disable a rule whose EventType is not CustomEvent, set IsEnabled, the only settable property of EventToAction, and call Update:

public void DisableDoorOpenRules(Door door)
{
    EventToActionCollection rules = door.EventToActions;
    List<EventToAction> doorOpenRules = rules
        .Where(r => r.EventType == EventType.DoorOpen &&
                    r.IsEnabled)
        .ToList();

    foreach (EventToAction rule in doorOpenRules)
    {
        rule.IsEnabled = false;
        rules.Update(rule);
    }
}

Update throws SdkException with SdkError.InvalidOperation when the rule's EventType is CustomEvent, when its Action is null, or when the rule no longer exists in Security Center. For a custom-event rule, set IsEnabled and call UpdateCustomCondition(rule, rule.CustomCondition). Pass a different condition string when you also need to change the condition. Call UpdateCustomCondition only on a rule read from EventToActions. Passing the EventToAction that Add returned has no effect: the call changes nothing and reports no error.

Rules created in Config Tool also appear in EventToActions. If the SDK cannot represent a rule's configured action, Action is null. You can remove that rule, but you cannot enable or disable it through the SDK. For a rule with a non-null Action, use Update when EventType is not CustomEvent, and use UpdateCustomCondition when it is. These updates preserve rule settings that the SDK does not expose (see Rule conditions and schedule evaluation).

Removing rules

Remove deletes the rule identified by its Id. Retrieve the rule from the same EventToActions collection on which you call Remove, as shown below. If the rule came from a different collection read, Remove can delete the Security Center rule but return false because that object was not in the collection instance. Clear deletes every rule on the entity:

Warning

Do not use Clear() for integration cleanup. It deletes every event-to-action rule on the source entity, including rules created in Config Tool and rules whose actions the SDK cannot represent. Clear() returns no result, and the SDK provides no undo operation. Read EventToActions again, identify only rules that your integration owns, and call Remove() on those rules.

public void RemoveRule(Entity source, int ruleId)
{
    EventToActionCollection rules = source.EventToActions;
    EventToAction rule = rules.FirstOrDefault(r => r.Id == ruleId);
    if (rule != null)
    {
        rules.Remove(rule);
    }
}

Persistence and transactions

Use the EventToActionCollection.Add overloads that accept an EventType, together with Update, UpdateCustomCondition, Remove, and Clear, to modify event-to-action rules. Call these methods on the EventToActionCollection type itself, and pass an EventToAction back to the same collection you read it from. The list operations that EventToActionCollection inherits, and calls made through an IList<EventToAction> reference, change only the retrieved collection and leave Security Center unchanged. Without an active entity transaction, each supported rule change is submitted before its method returns. To submit multiple rule changes as one batch, call these methods within ExecuteTransaction or ExecuteTransactionAsync. If the transaction commit fails, the SDK rolls back the transaction by default and applies none of its changes. After rollback, read EventToActions again before inspecting the rules. For commit exceptions and manual transaction handling, see About transactions.

Limitations

Config Tool can create rule configurations that the SDK cannot create. When a rule needs one of the following, create it in Config Tool. The SDK can enumerate and remove the rule afterward, but can enable or disable it only when Action is non-null.

Actions that BuildAction cannot create

BuildAction(ActionType, ...) does not support every action that can appear in an event-to-action rule created in Config Tool. For a logged-on user with the required privilege, unsupported values throw SdkException with SdkError.InvalidOperation. Examples include:

• SendEmail, SendMessage, PlaySound
• DisplayEntity
• AcknowledgeAlarm, ForwardAlarm
• SendEmailReport, SendEmailSnapshotReport, PrintReport

This list does not include every ActionType value that BuildAction rejects.

The ActionManager methods that perform some of these operations directly, such as SendEmail and PlaySound, execute once immediately; they do not create rules.

Action settings the SDK cannot configure

BuildAction can create the following action types, but the Platform SDK does not expose setters for their action-specific configuration:

• BlockUnblockVideoAction: all action-specific properties are get-only, so the SDK cannot choose block or unblock or configure the blocking settings
• EditBookmarkAction and DeleteBookmarkAction: BookmarkTime and Message are get-only
• SetTileContentAction: exposes no tile-specific configuration properties, so the SDK cannot set the monitor, tile, or content

PTZ actions supported in event-to-action rules

Of the PTZ actions that BuildAction(PtzCommandType, ...) can create, EventToActions.Add accepts only PtzCommandType.GoToPreset, PtzCommandType.RunPattern, and PtzCommandType.Home. Set PresetAction.PresetId or PatternAction.PatternId before adding a go-to-preset or run-pattern rule. For any other PTZ action that this BuildAction overload creates, Add throws SdkException with SdkError.InvalidOperation.

Rule conditions and schedule evaluation

Create a rule in Config Tool when it requires any of the following settings. EventToActions.Add cannot configure them, and EventToAction does not expose their configured values:

• An entity condition that restricts the rule to events involving a specified entity, such as a cardholder or cardholder group.
• An event-specific condition string for a video analytics, audio analytics, or license plate read event.
• Evaluation of the rule's schedule in the source entity's time zone.

The Add overload that accepts customCondition applies it only to EventType.CustomEvent. Custom-event conditions are returned through EventToAction.CustomCondition and can be changed with UpdateCustomCondition.

See also

• Receiving actions: Receiving actions directed at entities.
• Custom events: Defining and raising the custom events that rules react to.
• Working with Security Center events: Receiving operational events from Security Center.