platform sdk threat levels

About threat levels

A ThreatLevel defines a configured response to an incident, such as a fire, building lockdown, emergency drill, or hostile event. An operator or SDK application can activate it on the system or on a specific area. Its activation and deactivation actions can affect access control, video, alarms, messaging, macros, and other supported action targets.

Activation and deactivation

A threat level can be activated on the entire system or scoped to a single area:

ThreatLevel level = engine.GetEntity<ThreatLevel>(threatLevelGuid);

// System-wide.
level.ActivateOnSystem();
// ...
level.DeactivateFromSystem();

// Area-scoped.
level.Activate(areaGuid);
// ...
level.Deactivate(areaGuid);

Security Center stores at most one active threat level per target. Activate(areaGuid) replaces the active threat level on the specified area without changing its child areas. Different areas can therefore have different active threat levels.

ActivateOnSystem() applies the threat level to SystemConfiguration and recursively to all areas, replacing the active threat level on every affected target. Deactivate(areaGuid) clears the active threat level on the specified area. DeactivateFromSystem() clears the active threat level on SystemConfiguration and all areas.

The deactivation methods reset the target. They do not verify that the ThreatLevel instance used to call the method is the threat level currently active on that target.

All four methods require a connected SDK engine. A disconnected call throws SdkException with SdkError.NotConnected. For an area-scoped call, a Guid that does not resolve to an Area causes SdkException with SdkError.UnableToRetrieveEntity. The logged-on user must have SdkPrivilege.SetThreatLevel for area-scoped activation and deactivation. System-wide activation and deactivation require SdkPrivilege.SetSystemwideThreatLevel.

These methods return void and do not report whether the configured actions completed successfully.

Activation and deactivation actions

ThreatLevel.ActivationActions contains the actions that Security Center runs when the threat level is activated. DeactivationActions contains the actions that Security Center runs when the threat level is deactivated. Examples include:

• Lock perimeter doors in the affected area.
• Boost the recording quality of selected cameras.
• Trigger an alarm.
• Send an email or message.
• Run a macro.

ActivationActions and DeactivationActions are separate action lists. Security Center does not automatically reverse activation actions or restore the state that existed before activation. Configure DeactivationActions for the state that Security Center must establish after deactivation.

When another threat level replaces the current threat level on a target, Security Center issues the previous level's deactivation actions before the new level's activation actions.

Reading ThreatLevel.ActivationActions, ThreatLevel.DeactivationActions, or Area.ThreatLevelMappings returns a list copy. To save changes, modify the returned list and assign the complete list back to the property.

Observing threat level changes

A connected SDK application receives threat level changes through Engine.EventReceived when its event filter allows EventType.ThreatLevelActivated and EventType.ThreatLevelDeactivated. In the handler, pattern match EventReceivedEventArgs against ThreatLevelActivatedEventArgs or ThreatLevelDeactivatedEventArgs.

Both event types expose ThreatLevel, which identifies the threat level, and Target, which identifies the root target of the operation. Target is SystemConfiguration.SystemConfigurationGuid for a system operation or the area Guid for an area operation.

A system operation changes area states recursively but does not raise a separate threat-level event for every affected area. These events identify the state transition; they do not indicate that the configured actions have finished.

private void OnEventReceived(object sender, EventReceivedEventArgs e)
{
    if (e is ThreatLevelActivatedEventArgs activated)
    {
        Console.WriteLine($"Threat level {activated.ThreatLevel} activated on {activated.Target}.");
    }
    else if (e is ThreatLevelDeactivatedEventArgs deactivated)
    {
        Console.WriteLine($"Threat level {deactivated.ThreatLevel} deactivated on {deactivated.Target}.");
    }
}

For how to subscribe to and filter Security Center events, see Working with Security Center events.

Operator display

ThreatLevel.Color is a read-write SolidColorBrush that defines the color Security Desk displays for the active threat level. Set this property when configuring the threat level.

Reading the active threat level

Use these properties to read the active threat level:

• SystemConfiguration.ActiveThreatLevel: The threat level active on the system target, or Guid.Empty when no threat level is active.
• Area.ActiveThreatLevel: The threat level active on the area, or Guid.Empty when no threat level is active.

Configuring area-specific actions

Area.ThreatLevelMappings is a read-write List<AccessPointGroupThreatLevelMapping>. Each mapping identifies a threat level through ThreatLevelId and contains ActivationActions and DeactivationActions.

Actions from an applicable area mapping are added to the actions configured on the ThreatLevel; they do not replace them. Different areas can therefore associate different actions with the same threat level.

For a nested area, an action from a matching parent-area mapping is inherited only when the action supports area-wide targeting and does not identify a specific recipient.

See also

• About access control: Door locking and access policy, possible action targets.
• About alarms: Alarm triggering, acknowledgement, investigation, and forwarding.
• About doors, areas, elevators, and access points: The Area entity reads ActiveThreatLevel and ThreatLevelMappings.
• About video: Recording boost and video protection, possible action targets.