Alarms, Audit and Notifications

About the Alarm Module

The Alarm Module is a crucial component for most projects, designed to monitor and manage alarm events within your projects. By leveraging the Alarm Module, you can create a comprehensive alarm management system tailored to your specific application requirements.

The documentation will guide you through the Alarm Module's functionalities, starting with an overview of the module's purpose and key concepts. It will then cover how the Alarm Module works, followed by sections on configuring and working with the module. Finally, the documentation will provide troubleshooting information and best practices to ensure optimal performance of your alarm management system.

By understanding and implementing the Alarm Module effectively, you can enhance your projects' responsiveness to critical events and ensure a high level of control and automation for your application.

Introduction to Alarm Module:

The Alarm Module is a complete solution for managing real-time alarms, notification events, and Audit-Trail information. It is a powerful tool that enables users to monitor and control their processes in real-time, by providing alerts for critical events, and storing data for future analysis.

The Alarm Module can be used in a wide range of industries, including manufacturing, energy, and transportation. It is an essential component of any modern control system, and is designed to help users achieve greater efficiency and productivity.

The key features and functionalities of the Alarm Module include:

Real-time Alarm States Processing: The Alarm Module is designed to process alarms in real-time, ensuring that critical events are identified and responded to as quickly as possible.

Agnostic storage on any Database provider: The Alarm Module can store data on any database provider, making it flexible and easy to use.

Store and Forward when archiving to remote databases: The Alarm Module is capable of storing and forwarding data to remote databases, ensuring that data is always available for analysis.

Automated replication in hot-stand-by scenarios: The Alarm Module is designed to work in hot-stand-by scenarios, ensuring that data is always available and up-to-date.

Organize and manage alarms hierarchically: The Alarm Module allows users to organize and manage alarms hierarchically, providing greater flexibility and control over their processes.

Define System AuditTrail event and Track Operator actions: The Alarm Module allows users to define system audit-trail events and track operator actions, providing greater visibility and accountability.

Send Notifications by SMS or e-mails: The Alarm Module is capable of sending notifications by SMS or e-mails, ensuring that users are always aware of critical events.

Universal Time and Daylight Saving always considered for accurate time-stamp: The Alarm Module always considers universal time and daylight saving, ensuring that timestamps are accurate and reliable.

Timestamps precision up to 0.1 ms: The Alarm Module provides high precision timestamps up to 0.1 ms, ensuring that data is always accurate and reliable.

Dynamic Language localization of alarm messages: The Alarm Module allows users to localize alarm messages dynamically, ensuring that they are easy to understand and relevant to their audience.

In summary, the Alarm Module is a powerful and versatile tool that enables users to monitor and control their processes in real-time, by providing alerts for critical events, and storing data for future analysis. It is an essential component of any modern control system, and can be used in a wide range of industries to improve efficiency and productivity.

Purpose and Key Concepts

Purpose and Key Concepts

AlarmGroup

Alarm groups allow you to configure common settings for a collection of alarms. For example, if the alarms in the groups require Acknowledgement.

Also, the query real-time informational automatically consolidating the alarm in the group.

AlarmArea

Adds more context information to the alarm, linking it to one Area in Tree structure.

The Hierarchical organization of the AlarmAreas allows to get information, filter or act, in all alarms of one area, or include its children alarms.

AlarmItem 

Any defined event that can create an alarm is an AlarmItem. For instance, if a Tag has the configuration to generate a HI alarm at 70, and a HiHi alarm at 90, we have two AlarmItems defined.

Each AlarmItem belongs to one AlarmGroup and one AlarmArea.

AuditTrail

Pre-defined AlarmGroup intended to track system events and Operations actions aiming to create records for auditing log.

AlarmHistorian

The alarm events can be logged using the database connection defined at Edit → Datasets → Dos → AlarmHistorian.

Alarm Module Settings

Some settings affects the behavior all alarm and the execution of Alarm Module.

Those fields are located above the header on Edit → Alarms → Groups table.

======================

Sure, here's a draft of the Audit-Trail Configuration section:

Audit-Trail Configuration

The Audit-Trail is a pre-defined AlarmGroup intended to track system events and operational actions with the goal of creating records for an auditing log. The Alarm Module provides a complete solution to manage real-time alarms, notification events, and Audit-Trail information.

Configuring Audit-Trail in the Alarm Module allows you to track all system events and operator actions that can have an impact on system performance and operation. This section will guide you through the process of configuring the Audit-Trail in the Alarm Module.

Pre-defined Audit-Trail

The Alarm Module includes a pre-defined AlarmGroup called Audit-Trail. This AlarmGroup is intended to track system events and operational actions automatically. You can customize this AlarmGroup by editing its properties on the Alarms → Groups page.

Customizing Audit-Trail

To customize the Audit-Trail AlarmGroup, follow these steps:

Go to the Alarms → Groups page.

Select the Audit-Trail AlarmGroup from the list.

Edit the properties of the Audit-Trail AlarmGroup, such as Name, AckRequired, ActiveTimeDeadband, AckTimeout, AutoAckTime, Sound, Show, LogEvents, Colors, NotificationMethod, and Description, to fit your needs.

Save the changes.

Configuring Audit-Trail Properties

The following are the properties that you can configure for the Audit-Trail AlarmGroup:

Name: Enter a name for the AlarmGroup. The system allows you to know if the name is not valid.

AckRequired: If required, the alarm stays in the alarm list until someone acknowledges the alarm by double-clicking it in the application.

ActiveTimeDeadband: Enter a time deadband that will create a delay after an alarm occurs. The alarm will trigger again only after the deadband.

AckTimeout: Defines a timeout for acknowledging the alarm. If the alarm is not acknowledged after the specified time, the alarm becomes active again.

AutoAckTime: If the alarm is not acknowledged after the specified time, the system acknowledges the alarm.

Sound: Select the sound that will play when the alarm occurs.

Show: Select the list for the alarm to display in the alarm window in the application.

LogEvents: Select when you want the alarm to be logged to the alarm historian:

a. None - Alarms are not logged.

b. Active - Log when alarm is active.

c. ActiveAck - Log when the alarm is active and acknowledged.

d. ActiveNorm - Log when the alarm returns to normal.

e. All - Log all of the above conditions.

Colors: Select the colors you want to use for each state:

a. Active - Configured alarm is in the alarm state.

b. Normalized - Configured alarm was in the alarm state but is no longer in the alarm state and still needs to be acknowledged.

c. Acknowledged - Configured alarm has been acknowledged, but it is still in the alarm state.

NotificationMethod: Calls a Script → Class method that triggers a code when the alarm happens.

Description: Enter a description of the alarm group.

Conclusion

Configuring the Audit-Trail AlarmGroup in the Alarm Module allows you to track all system events and operator actions that can have an impact on system performance and operation. By following the steps outlined in this section, you can customize the Audit-Trail properties to fit your needs and ensure that your system is operating optimally.

The Alarm Database

The alarm database stores the events from the AlarmGroups and Audit Trail.

By default, it is mapped to a SQLlite database with name <project name>.tAlarm , defined at Datasets → Dos → AlarmHistorian.

You can change the Alarm Database to use any other SQL connection, following this steps:

• Go to Datasets → Dos.
• Rename or delete the AlarmHistorian object.
• Create a new DB connection with name AlarmHistorian connected to desired Database.

======================================

Alarms Database

The Alarms Database stores the events from AlarmGroups and Audit-Trail. By default, it is mapped to a SQLite database with name <project name>.tAlarm, which is defined at Datasets → Dos → AlarmHistorian.

You can change the Alarms Database to use any other SQL connection by following these steps:

Go to Datasets → Dos.

Rename or delete the AlarmHistorian object.

Create a new DB connection with name AlarmHistorian connected to the desired Database.

When you archive the alarms to the Alarms Database, the Alarm Module automatically creates and populates the necessary tables to store alarm and audit trail information.

Note that the Alarms Database is critical for logging and tracking alarms and events. It is important to ensure that the database is reliable and accessible, and that it has sufficient storage capacity.

Overall, the Alarms Database provides a central location for storing and managing real-time alarms and audit trail information, making it easier to monitor and troubleshoot system issues.

Configuring AlarmGroups

There are 3 pre-defined AlarmGroups:

• Warning (Warning messages that do not require acknowledgment).
• Critical (Critical Messages that require acknowledgment).
• AuditTrail (System Events log).

To configure alarm groups, you can customize the existing groups or add new ones. 

• Go to Alarms → Groups.

• Add new rows or edit the table, setting the desired values to the fields.

======================================

Alarm Group Configuration:

Alarm Groups are collections of alarms that share common settings. They are used to define the behavior of alarms and their processing rules. The Alarm Module comes with three pre-defined Alarm Groups:

Warning: This group contains warning messages that do not require acknowledgment.

Critical: This group contains critical messages that require acknowledgment.

AuditTrail: This group is intended to track system events and operation actions, creating records for an auditing log.

Users can customize the existing groups or create new ones according to their needs. To configure Alarm Groups, follow these steps:

Go to Alarms → Groups.

Add new rows or edit the existing table, setting the desired values to the fields.

The configuration properties of Alarm Groups are as follows:

Name: Enter a name for the Alarm Group. The system allows you to know if the name is not valid.

AckRequired: If required, the alarm stays in the alarm list until someone acknowledges the alarm by double-clicking it in the application.

ActiveTimeDeadband: Enter a time deadband that will create a delay after an alarm occurs. The alarm will trigger again only after the deadband.

AckTimeout: Defines a timeout for acknowledging the alarm. If the alarm is not acknowledged after the specified time, the alarm becomes active again.

AutoAckTime: If the alarm is not acknowledged after the specified time, the system acknowledges the alarm.

Sound: Select the sound that will play when the alarm occurs.

Show: Select the list for the alarm to display in the alarm window in the application.

LogEvents: Select when you want the alarm to be logged to the alarm historian. You can choose from the following options:

None: Alarms are not logged.

Active: Log when the alarm is active.

ActiveAck: Log when the alarm is active and acknowledged.

ActiveNorm: Log when the alarm returns to normal.

All: Log all of the above conditions.

Colors: Select the colors you want to use for each state:
Active: Configured alarm is in the alarm state.

Normalized: Configured alarm was in the alarm state but is no longer in the alarm state and still needs to be acknowledged.

Acknowledged: Configured alarm has been acknowledged but is still in the alarm state.

NotificationMethod: Calls a Script → Class method that triggers a code when the alarm happens.

Description: Enter a description of the Alarm Group.

In summary, Alarm Groups are collections of alarms that share common settings. The Alarm Module provides three pre-defined Alarm Groups, which can be customized or new ones can be created. The configuration properties of Alarm Groups allow users to define the behavior of alarms and their processing rules, and include fields such as Name, AckRequired, ActiveTimeDeadband, AckTimeout, AutoAckTime, Sound, Show, LogEvents, Colors, NotificationMethod, and Description.

Configuring AlarmItems

The definition of an AlarmItem has 3 mandatory fields: TagName, Condition and AlarmGroup. 

That means, the Tag value that will be evaluated, the alarm condition to be verified, and if there is an alarm, which AlarmGroup will guide the tag processing behavior.

To create or modify AlarmItems:

• Go to Alarms → Items.
• Add new rows or edit the datagrid fields.

The conditions options are described in the following table:

======================================

Alarm Item Configuration:

Alarm Items are defined events that can create alarms. They are created by specifying a Tag value to be evaluated, the alarm condition to be verified, and the Alarm Group that will guide the tag processing behavior. Alarm Items can be created or modified by following these steps:

Go to Alarms → Items.

Add new rows or edit the datagrid fields.

The mandatory fields for creating an AlarmItem are:

TagName: Enter a tag name or click "..." to select a tag.

Condition: Select the condition you want to use for this alarm event.

AlarmGroup: Select the Alarm Group that should control what happens when this alarm occurs.

The configuration properties of Alarm Items are as follows:

Limit: Enter a value for the alarm limit to be used for the condition you selected.

Deadband: Sets the deadband value. For example, for a Hi alarm item with a limit of 100 and a deadband of 10, the limit value is now 110; for a Lo alarm item, setting the deadband as 10 means the limit value is 90.

Setpoint: Set a value or a tag that you want to compare other values to determine if there is a deviation.

SetpointDeadband: Set the deadband for the setpoint when compared with the deviation.

Group: Select the Alarm Group that should control what happens when this alarm occurs.

Area: Once created on Alarms → Areas, the areas will be displayed here and will be able to be chosen.

Priority: Enter a priority value that controls where the alarm displays in the list. The higher the number, the higher the priority. You can use the same priority for more than one alarm event. Enter 0 (zero) for alarms to be at the end of the list.

Message: Enter the text that displays in the alarm list.

PriorityOrder Property: It is also possible to set the priority using the PriorityOrder property in CodeBehind or in PropertyWatch. In this case, the LOWER the number, the HIGHER the priority. The default is 0 (highest priority).

The conditions options for Alarm Items are as follows:

Hi: Tag >= limit

HiHi: Tag >= limit (when acknowledged, a Hi alarm is automatically acknowledged for the same Tag)

Lo: Tag <= limit

LoLo: Tag <= limit (when acknowledged, a Lo alarm is automatically acknowledged for the same Tag)

RateOfChange: Tag rate of change >= limit

DeviationMinor: Absolute value (tag - Setpoint) > limit

DeviationMajor: Absolute value (tag - Setpoint) > limit

Equal: Tag = limit

GreaterThan: Tag > limit

GreaterEqual: Tag >= limit

LessThan: Tag < limit

LessEqual: Tag <= limit

Changed: Tag value changed

ChangedUp: Tag value increased

ChangedDown: Tag value decreased

NotEqual: Tag different from limit

In summary, Alarm Items are defined events that can create alarms by specifying a Tag value to be evaluated, the alarm condition to be verified, and the Alarm Group that will guide the tag processing behavior. The mandatory fields for creating an AlarmItem are TagName, Condition, and AlarmGroup. The configuration properties of Alarm Items allow users to define the alarm limit, deadband, setpoint, setpoint deadband, group, area, priority, message, and priority order. The available conditions options for Alarm Items include Hi, HiHi, Lo, LoLo, RateOfChange, DeviationMinor, DeviationMajor, Equal, GreaterThan, GreaterEqual, LessThan,

Notification Events 

In order to a apply custom action using .NET scripts, subscribe to notifications of alarms and events.

These notifications are typically used to send SMS or email warnings, execute custom calculations, add custom notification messages or audio alarms, text-to-speech audio alarms, and to perform any kind of action defined by custom programming.

To subscribe to alarm events, create a method in any Script Class of type Server, with the following prototype:

void Notification(AlarmEventInfo[] info)

Select the method in the Notification Method column on Alarms → Groups.

The name of the method can vary; The important is the expected parameters.

The AlarmEventInfo structure is defined in the namespace Alarm.

======================================

Notification Events:

The Alarm Module allows you to subscribe to notifications of alarms and events, which can be used to apply custom actions using .NET scripts. Notifications are typically used to send SMS or email warnings, execute custom calculations, add custom notification messages or audio alarms, text-to-speech audio alarms, and perform any kind of action defined by custom programming.

To subscribe to alarm events, create a method in any Script Class of type Server, with the following prototype:

void Notification(AlarmEventInfo[] info)

Select the method in the Notification Method column on Alarms → Groups. The name of the method can vary; The important is the expected parameters.

The AlarmEventInfo structure is defined in the namespace Alarm. This structure contains information about the alarm, such as the TagName, Condition, AlarmGroup, Limit, Deadband, Setpoint, and other properties.

Here's an example of a Notification method:

void OnAlarmNotification(AlarmEventInfo[] info)
{
    foreach (AlarmEventInfo alarm in info)
    {
        if (alarm.Condition == "HiHi")
        {
            // send SMS or email warning
            string message = "Alarm " + alarm.TagName + " HiHi limit reached.";
            //SendSMS("123-456-7890", message);
            //SendEmail("johndoe@example.com", message);
        }
        else if (alarm.Condition == "LoLo")
        {
            //execute custom calculations
            Calculate(alarm.TagName, alarm.Limit);
        }
        else
        {
            // add custom notification messages or audio alarms
            AddNotification(alarm.TagName, alarm.Condition);
            //PlayAudioAlarm("siren.wav");
        }
    }
}

In this example, the Notification method checks the Condition of each AlarmEventInfo object in the info array and performs a different action based on the Condition. For HiHi alarms, it sends an SMS and an email warning. For LoLo alarms, it executes custom calculations. For all other alarms, it adds custom notification messages and plays an audio alarm.

Overall, the Notification Events section provides a detailed guide on how to use .NET scripts to apply custom actions to alarm events and how to subscribe to notifications of alarms and events.

Acknowledging Alarms

There are several methods for acknowledging alarms:

• Using the alarm visualization object in the displays.

• Tag properties.

• Alarm group or the alarm item's runtime properties.

Acknowledge All Alarms

You can use the <Alarm.AckAll> property that acknowledges all active alarms.

Acknowledge a Single Alarm or the Highest Priority Alarm 

The <Alarm.PriorityItem.UnAck> property allows the acknowledgment of the highest priority alarm configured in the "Priority" column on Alarms → Items if there is a pending ack alarm. 

Acknowledge a Specific Alarm 

To acknowledge a specific alarm, use the <Alarm.Items.IDxx.Unack> property. To check the contents of the IDxx alarm columns, go to the alarm item and add the ID column (right-click in the table and select "ID").

======================================

Acknowledging Alarms

The Alarm Module provides several methods for acknowledging alarms, allowing users to manage alarms efficiently. This section will discuss the various methods for acknowledging alarms.

Using the Alarm Visualization Object

One way to acknowledge an alarm is by using the Alarm Visualization object in displays. Users can view the alarms in the alarm list and acknowledge them by selecting the alarm and clicking the "Acknowledge" button. The alarm will then move to the Acknowledged state.

Using Tag Properties

Users can also acknowledge alarms using Tag properties. For example, users can acknowledge an alarm by setting the value of a Tag property to "1". When the property is set, the alarm will move to the Acknowledged state.

Using Alarm Group or Alarm Item's Runtime Properties

Another method for acknowledging alarms is by using the Alarm Group or Alarm Item's runtime properties. Users can select an Alarm Group or Alarm Item and view its properties in the Properties window. Users can acknowledge an alarm by setting the "Ack" property to "True". The alarm will then move to the Acknowledged state.

Acknowledging All Alarms

Users can acknowledge all active alarms using the <Alarm.AckAll> property. When this property is set, all active alarms will move to the Acknowledged state.

Acknowledging a Single Alarm or the Highest Priority Alarm

Users can acknowledge a single alarm or the highest priority alarm by using the <Alarm.PriorityItem.UnAck> property. If there is a pending Ack alarm, the highest priority alarm configured in the "Priority" column on Alarms → Items will be acknowledged. If there is no pending Ack alarm, the specified alarm will be acknowledged.

Acknowledging a Specific Alarm

To acknowledge a specific alarm, users can use the <Alarm.Items.IDxx.Unack> property. To check the contents of the IDxx alarm columns, users can go to the alarm item and add the ID column (right-click in the table and select "ID").

Conclusion

In conclusion, the Alarm Module provides several methods for acknowledging alarms, allowing users to manage alarms efficiently. Users can acknowledge alarms using the Alarm Visualization object, Tag properties, or Alarm Group or Alarm Item's runtime properties. Users can also acknowledge all active alarms, a single alarm, or the highest priority alarm.

Alarm Visualization

To visualize alarms and events, you can use the built-in object in your displays or reports.

======================================

Alarm Visualization:

The Alarm Module provides a built-in object for visualizing alarms and events in your displays or reports. This object displays real-time information about the alarms in your system and allows users to acknowledge or silence alarms as needed.

To use the Alarm Visualization object, simply drag and drop it onto your display or report. You can then configure the object to display the alarms and events you are interested in by selecting the appropriate Alarm Groups and Alarm Items.

In addition to the built-in Alarm Visualization object, the Alarm Module provides access to a number of properties and methods through the Alarm Namespace. These properties and methods allow you to interact with the alarms and events in your system programmatically, and can be used to create custom displays or reports.

For example, the Alarm.Group object provides a list of all defined alarm groups and their properties, while the Alarm.Item object provides access to all alarm items and their properties. The tag properties connected with the alarm module can be used to modify alarm conditions and configure custom notification events.

By combining the built-in Alarm Visualization object with the powerful programming capabilities of the Alarm Namespace, you can create customized displays and reports that provide real-time information about the status of your system's alarms and events.

The Alarm Namespace

The Alarm namespace has the properties of the alarm server.

The Alarm.Group object has the list of all defined groups and their properties.

The Alarm.Item object has all alarm items and their properties.

The tag properties are connected with the alarm module.

In this section...