platform sdk alarms

About alarms

In Security Center, an Alarm is a configured entity that defines an alert: its recipients, default priority, the procedure operators must follow, and other policies. Triggering an alarm creates an alarm instance: a runtime occurrence that is sent to the alarm's configured recipients, where operators receive it, acknowledge it, investigate it, or forward it.

The Platform SDK exposes the alarm pipeline through Engine.AlarmManager:

AlarmManager manager = engine.AlarmManager;

To trigger or acknowledge an alarm, the connected user must have the Security Center privileges for that operation. GetActiveAlarms and IsActive require the AlarmReport privilege; without it, those calls return null and false, respectively.

Configuring alarm schedules

An Alarm entity carries one or more schedules that define when the alarm is active. Read the configured schedules through Alarm.SchedulesGuids, and modify them through AddSchedule and RemoveSchedule:

Alarm alarm = engine.GetEntity<Alarm>(alarmGuid);

ReadOnlyCollection<Guid> currentSchedules = alarm.SchedulesGuids;

bool added = alarm.AddSchedule(scheduleGuid);
bool removed = alarm.RemoveSchedule(scheduleGuid);

AddSchedule returns true when the schedule is added to the list, and false when the schedule is already present (no change made).

RemoveSchedule returns true when the schedule is removed, and false when the schedule is not in the list or when the alarm has only one schedule remaining: the SDK refuses to leave the alarm with no schedules.

Both methods first require scheduleGuid to resolve to a Schedule. If the GUID does not identify a schedule that the engine can load, the call fails without changing the schedule list, rather than returning false.

For the common case of a single-schedule alarm, two shortcut properties are available:

• Alarm.Schedule: gets or sets the first schedule as a Schedule entity.
• Alarm.ScheduleGuid: gets or sets the first schedule's Guid.

Setting either property replaces the alarm's current first schedule and keeps its other schedules. Do not use these properties on an alarm that has more than one schedule: SchedulesGuids is not ordered by assignment, so reading the property back afterwards can return one of the alarm's other schedules rather than the one you set. Use AddSchedule and RemoveSchedule for a multi-schedule alarm.

Alarm.IsScheduleReadOnly returns true when the alarm's schedules cannot be modified, which is the case for alarms imported from a federated external system.

Triggering an alarm

TriggerAlarm returns the new alarm instance ID, or -1 when the trigger failed. A common cause is the calling user lacking the privilege to trigger the alarm:

int instanceId = engine.AlarmManager.TriggerAlarm(alarmGuid);

if (instanceId == -1)
{
    // The trigger did not create an alarm instance.
    return;
}

When sourceEntityGuid is Guid.Empty on any overload, the connected user's Guid is used as the source. The TriggerAlarm(Guid alarm) and TriggerAlarm(Alarm alarm) overloads (no sourceEntityGuid) also use the connected user.

The Guid-based overloads progressively layer additional context:

• TriggerAlarm(Guid alarm): trigger by alarm Guid; the connected user is used as the source.
• TriggerAlarm(Guid alarm, Guid sourceEntityGuid): attach a source entity that represents the cause (a door, a camera, or any entity).
• TriggerAlarm(Guid alarm, Guid sourceEntityGuid, DynamicAlarmContent dynamicAlarmContent): attach runtime context such as a description, attached entities, or URLs.
• TriggerAlarm(Guid alarm, Guid sourceEntityGuid, int acknowledgementConditionId, bool userAcknowledgementRequired): bind the instance to an acknowledgement condition that must be cleared before the alarm can be acknowledged.
• TriggerAlarm(Guid alarm, Guid sourceEntityGuid, DynamicAlarmContent dynamicAlarmContent, int acknowledgementConditionId, bool userAcknowledgementRequired): combine dynamic content and an acknowledgement condition.
• TriggerAlarm(Guid alarm, Guid sourceEntityGuid, DynamicAlarmContent dynamicAlarmContent, GeoCoordinate location): attach a geographic location alongside the dynamic content.

The Alarm-typed overloads accept an Alarm entity instead of a Guid:

• TriggerAlarm(Alarm alarm)
• TriggerAlarm(Alarm alarm, Guid sourceEntityGuid)
• TriggerAlarm(Alarm alarm, Guid sourceEntityGuid, int acknowledgementConditionId, bool userAcknowledgementRequired)
• TriggerAlarm(Alarm alarm, Guid sourceEntityGuid, DynamicAlarmContent dynamicAlarmContent)
• TriggerAlarm(Alarm alarm, Guid sourceEntityGuid, DynamicAlarmContent dynamicAlarmContent, GeoCoordinate location)

The alarm GUID must be non-empty, an Alarm argument must be non-null, and any DynamicAlarmContent argument must be non-null. A call that does not meet these requirements does not create an alarm instance.

When an alarm is triggered with an acknowledgementConditionId, the resulting instance cannot be acknowledged until the condition is cleared with ClearSourceCondition or until ForceAcknowledgeAlarm is used to bypass the condition.

Dynamic alarm content

DynamicAlarmContent carries runtime context attached to a single alarm instance. The descriptive Context string is supplied through the constructor; everything else is optional:

var content = new DynamicAlarmContent("Server room breach")
{
    Priority = 50,
};

content.AttachedEntities.Add(cameraGuid);
content.AttachedEntities.Add(doorGuid);
content.ForwardedRecipients.Add(supervisorGuid);
content.Urls.Add("https://tickets.example.com/INC-100");

int instanceId = engine.AlarmManager.TriggerAlarm(
    alarmGuid,
    sourceEntityGuid,
    content);

Properties on DynamicAlarmContent:

• Context (string, read-only): freeform description shown with the alarm in Security Desk. Set through the constructor.
• Priority (byte): priority value for the alarm instance, in the range 1 (highest) through 255 (lowest). Only values within that range are accepted.
• AttachedEntities (List<Guid>): entities to attach to the instance, such as cameras showing the scene or doors involved. Mutate the returned list directly.
• ForwardedRecipients (List<Guid>): users to forward the instance to, in addition to the alarm's configured recipients. Mutate the returned list directly.
• Urls (List<string>): hyperlinks shown with the alarm. Mutate the returned list directly.

Acknowledging an alarm

Use the alarm instance ID returned by TriggerAlarm together with the alarm's Guid to acknowledge an instance. AcknowledgementType selects a positive (Ack) or negative (Nack) acknowledgement.

bool ok = engine.AlarmManager.AcknowledgeAlarm(
    instanceId,
    alarmGuid,
    AcknowledgementType.Ack);

To acknowledge multiple instances at once, pass a dictionary of instance ID to alarm Guid:

var alarms = new Dictionary<int, Guid>
{
    { instanceId1, alarmGuid1 },
    { instanceId2, alarmGuid2 },
};

bool ok = engine.AlarmManager.AcknowledgeAlarm(
    alarms,
    AcknowledgementType.Ack);

When an alarm instance has an outstanding source condition that prevents acknowledgement, call ClearSourceCondition with the source entity and the acknowledgement-condition ID supplied at trigger time:

engine.AlarmManager.ClearSourceCondition(
    sourceEntityGuid,
    acknowledgementConditionId);

ClearSourceCondition requires a non-empty sourceEntityGuid.

To bypass condition checks and acknowledge regardless, use ForceAcknowledgeAlarm:

bool ok = engine.AlarmManager.ForceAcknowledgeAlarm(
    instanceId,
    alarmGuid);

ForceAcknowledgeAllAlarms() force-acknowledges every active alarm instance.

Investigating, forwarding, and editing context

InvestigateAlarm marks an instance as under investigation. A dictionary overload is also available for batches:

bool ok = engine.AlarmManager.InvestigateAlarm(instanceId, alarmGuid);

bool batch = engine.AlarmManager.InvestigateAlarm(
    new Dictionary<int, Guid>
    {
        { instanceId1, alarmGuid1 },
        { instanceId2, alarmGuid2 },
    });

ForwardAlarm adds users or user groups to the instance's recipient list after it has been triggered:

engine.AlarmManager.ForwardAlarm(
    instanceId,
    new[] { supervisorGuid, supervisorGroupGuid });

ForwardAlarm requires a connected engine, a non-null recipients collection, and an instanceId that resolves to an existing alarm instance. If any of these is not met, the call does not forward the alarm.

EditAlarmContext replaces the descriptive context on an instance:

bool ok = engine.AlarmManager.EditAlarmContext(
    instanceId,
    alarmGuid,
    "Updated context after on-site check");

EditAlarmContext requires a non-empty alarmGuid.

Querying alarm state

Check whether an alarm currently has any active instance:

bool hasActive = engine.AlarmManager.IsActive(alarmGuid);

IsActive has an overload that accepts an Alarm entity directly. Both forms require the AlarmReport privilege; without it, the call returns false.

GetActiveAlarms() returns active-alarm records in a DataTable. Its query uses a fixed MaximumResultCount of 1,000 and a timeout of 30 seconds. The method returns null if the connected user lacks the AlarmReport privilege or the query fails.

DataTable activeAlarms = engine.AlarmManager.GetActiveAlarms();

For richer queries (acknowledgement and forwarding history, time ranges, alarm filters) and the result schema, see Platform SDK report manager query reference for AlarmActivityQuery.

See also

• Platform SDK report manager: Running queries against the Directory and processing results.