Alarm shelving API reference

This reference summarizes the alarm shelving, suppression, and out-of-service API functions that are available through the AlertServiceClient.ctl CTRL library.

Overview

The alarm shelving and suppression functionality is accessible via the AlertServiceClient.ctl CTRL library. All functions in this library are static and communicate with the Manager Service API (MSA)-based AlertService.

All modifying functions accept an optional reason parameter that is logged in the Security Event audit trail.

shelveAlerts function

Use shelveAlerts() to shelve one or more alert instances until a specified point in time, hiding them from the operator view.

bool shelveAlerts(dyn_atime alarmIdList, time until, string reason, dyn_mapping &shelvedAlerts, dyn_string &err)

Table 1. shelveAlerts parameters
Parameter	Type	Description
`alarmIdList`	`dyn_atime`	List of alert identifiers to shelve.
`until`	`time`	End timestamp for automatic unshelving. If set to zero time, the alert is not automatically unshelved.
`reason`	`string`	Operator comment logged in the audit trail.
`shelvedAlerts`	`dyn_mapping &`	Output: shelve state list for the input alerts.
`err`	`dyn_string &`	Output: list of error strings in case of an error.

Returns true on success, false on error.

Example

dyn_atime alarmIdList;
dyn_mapping shelvedAlerts;
dyn_string err;
alarmIdList[1] = makeATime("System1:ExampleDP:_alert_hdl.._value", getCurrentTime());
time until = getCurrentTime() + 3600; // shelve for 1 hour
bool ok = shelveAlerts(alarmIdList, until, "Maintenance window", shelvedAlerts, err);

unshelveAlerts function

Use unshelveAlerts() to remove the shelving from one or more alert instances.

bool unshelveAlerts(dyn_atime alarmIdList, dyn_mapping &shelvedAlerts, dyn_string &err)

Table 2. unshelveAlerts parameters
Parameter	Type	Description
`alarmIdList`	`dyn_atime`	List of alert identifiers to unshelve.
`shelvedAlerts`	`dyn_mapping &`	Output: updated shelve state list for the input alerts.
`err`	`dyn_string &`	Output: list of error strings in case of an error.

Returns true on success, false on error.

listShelvedAlerts function

Use listShelvedAlerts() to retrieve all currently shelved alert instances.

bool listShelvedAlerts(dyn_mapping &shelvedAlerts, string &err)

Table 3. listShelvedAlerts parameters
Parameter	Type	Description
`shelvedAlerts`	`dyn_mapping &`	Output: shelve state list for all currently shelved alerts.
`err`	`string &`	Output: error string in case of an error.

Returns true on success, false on error.

suppressAlerts function

Use suppressAlerts() to suppress alert handler configurations and prevent future alert generation on the target datapoint elements.

bool suppressAlerts(dyn_string dpeList, string reason, string &err)

Table 4. suppressAlerts parameters
Parameter	Type	Description
`dpeList`	`dyn_string`	Array of datapoint element paths to suppress.
`reason`	`string`	Reason applied to all datapoint elements in the operation.
`err`	`string &`	Output: error message on failure, empty string on success.

Returns true on success, false on error.

Example

dyn_string dpeList;
string err;
dynAppend(dpeList, "System1:ExampleDP:_alert_hdl.._value");
bool ok = suppressAlerts(dpeList, "Commissioning", err);

unsuppressAlerts function

Use unsuppressAlerts() to remove the suppression from alert handler configurations.

bool unsuppressAlerts(dyn_string dpeList, string &err)

Table 5. unsuppressAlerts parameters
Parameter	Type	Description
`dpeList`	`dyn_string`	Array of datapoint element paths to unsuppress.
`err`	`string &`	Output: error message on failure, empty string on success.

Returns true on success, false on error.

listSuppressedAlertHandlers function

Use listSuppressedAlertHandlers() to retrieve all currently suppressed alert handler configurations.

bool listSuppressedAlertHandlers(dyn_mapping &suppressedAlertHandlers, string &err)

Table 6. listSuppressedAlertHandlers parameters
Parameter	Type	Description
`suppressedAlertHandlers`	`dyn_mapping &`	Output: array of suppressed alert handler info mappings.
`err`	`string &`	Output: error message on failure, empty string on success.

Returns true on success, false on error.

setOutOfService function

Use setOutOfService() to place a datapoint or CNS node into out-of-service mode by swapping its alert classes to maintenance counterparts.

bool setOutOfService(string target, string reason, bool force, string updateStateDPE, anytype updateStateValue, string &err)

Table 7. setOutOfService parameters
Parameter	Type	Description
`target`	`string`	Datapoint or CNS node name to set out-of-service.
`reason`	`string`	Reason for the out-of-service action.
`force`	`bool`	If set to `true`, missing maintenance alert classes are created automatically by copying the original class configuration.
`updateStateDPE`	`string`	Optional DPE path used to store the out-of-service state. Use an empty string if not required.
`updateStateValue`	`anytype`	Value to write to `updateStateDPE` when the target enters out-of-service. Use `false` if not required.
`err`	`string &`	Output: error string in case of an error.

Returns true on success, false on error.

Example

string err;
bool ok = setOutOfService("System1:ExampleDP", "Planned maintenance", true, "", false, err);

resetOutOfService function

Use resetOutOfService() to remove the out-of-service mode from a datapoint or CNS node and restore its original alert classes.

bool resetOutOfService(string target, string updateStateDPE, anytype updateStateValue, string &err)

Table 8. resetOutOfService parameters
Parameter	Type	Description
`target`	`string`	Datapoint or CNS node name to reset from out-of-service.
`updateStateDPE`	`string`	Optional DPE path used to clear the stored out-of-service state. Use an empty string if not required.
`updateStateValue`	`anytype`	Value to write to `updateStateDPE` when the target leaves out-of-service. Use `false` if not required.
`err`	`string &`	Output: error string in case of an error.

Returns true on success, false on error.

listOutOfService function

Use listOutOfService() to retrieve all datapoints and CNS nodes currently in out-of-service mode.

bool listOutOfService(dyn_mapping &outOfServiceTargets, string &err)

Table 9. listOutOfService parameters
Parameter	Type	Description
`outOfServiceTargets`	`dyn_mapping &`	Output: array of out-of-service datapoint info mappings.
`err`	`string &`	Output: error string in case of an error.

Returns true on success, false on error.

getOutOfServiceState function

Use getOutOfServiceState() to query the out-of-service state of one or more datapoints or CNS nodes.

bool getOutOfServiceState(dyn_string targetList, dyn_mapping &outOfServiceStates, string &err)

Table 10. getOutOfServiceState parameters
Parameter	Type	Description
`targetList`	`dyn_string`	Array of datapoint or CNS node names to query.
`outOfServiceStates`	`dyn_mapping &`	Output: out-of-service state mappings for the queried targets.
`err`	`string &`	Output: error string in case of an error.

Returns true on success, false on error.

Security Events

All shelving, suppression, and out-of-service actions generate Security Events.

The events include the operator name, the action type, the affected datapoint elements, the reason text, and the timestamp.

Security Events provide a complete audit trail for IEC 62682 compliance.

System Dashboard KPIs

The AlertService provides KPI values for the System Dashboard.

Count of currently shelved alert instances.
Count of currently suppressed alert handler configurations.
Count of datapoint elements that are currently in out-of-service mode.