Custom Event Data Store

The Custom Event Data Store object allows the user to create and configure multiple event data stores in addition to the already existing System Event (A&E) DataStore. The object can be created in the I/O Model beneath the Core or a Data Store Group object.

A Custom Event Data Store will by default connect to the local MongoDB instance but can also be configured to connect to a different MongoDB historian. The Filter Options allow the user to choose the filter conditions for Alarms & Events to selectively store certain alarms and events in the Custom Event Data Store.

Quick Configuration

  1. Right click on the Core or a Data Store Group object and select Admin  New  Data Stores  Custom Event Data Store from the context menu to open the Create Object wizard.

  2. Give the object a unique name and enter a description if necessary. Leave the Processing Mode set to "Configuration"

  3. Click on the Custom Event Data Store options from the wizard sidebar to view the data store settings.

  4. The default database name can be changed here, along with data retention period and purge settings (what happens to the object data if the object is deleted). If the retention period is set to <null> then the event data will be retained permanently.

  5. If necessary, the MongoDB connection settings can also be changed (for example, if you wish to connect to a remote MongoDB instance or configure replication sets).

  6. Click Create to create the object in the I/O model tree.

  7. Select the newly created Custom Event Data Store in the I/O Model and look at the Object Properties panel. Open the Filter Options property compound to see all the options for filtering A&E for storage in the Custom Store.

    The Custom Event Data Store will only store event data that has been proactively selected by the user through configuration of the event filters. The System Event Data Store will archive all event data from Event Stream objects that have been configured to historize data.
  8. The Filter Options can be applied via a number of categories. Firstly, Event Stream objects can be added to the Stream Objects filter by opening the table and adding the path to an Event Stream Object (you can also drag and drop objects from the I/O Model into the table).

    The Stream Objects table also accepts RegEx strings of object paths. For a disambiguated path containing the caret escape character (^) such as:

    • ^/System/Core/object 1 ^/object 2

    Some valid regex expressions for would be:

    • \\^/System/Core/object 1 \\^/object 2

    • (\\^?)/System/Core/(.*)

  9. The following filters can also be applied by adding relevant string(s) entry to the tables

    • Messages

    • Sources

    • Categories

    • Conditions

    • SubConditions

      These filters all accept RegEx strings as entries and will then match them against the appropriate field in the event to filter them into the Custom Event Data Store.

      The Filter Options table properties are all generated as tab separated strings of RegEx patterns that are then processed internally. For this reason, and to avoid processing errors, users should avoid adding strings to the filter table that contain the following expression: ‘\t’(tab)
  10. Other Filter Options include adding different Severity ranges and various check boxes that can be applied to Event State Changes. It is also possible to add a custom Lua script to the Filter Script field to fully customize your filtering options.

  11. When all filtering options have been applied, return to the Common property compound and change the Processing Mode to "Operation" and click Apply to begin archiving.

  12. Event History Data can be retrieved selectively from a Custom Event Data Store using the Lua API geteventhistory function. The Custom Event Data Store object can be specified in the options table argument for the function.

Object Properties

Common

Object Name

The user-modifiable object name. This name overrides the name which has been supplied by the external system. It must be unique within the collection of objects of the parent object.

Object Description

This is the user-modifiable object description. This name overrides the description which has been supplied by the external system.

Display Alias

Alternate label for objects to be used for easier identification in the displays.

Processing Mode

Configure the processing mode of the object.

  • Configuration: In this mode no data is processed.

  • Operation: In this mode the object is operational.

Event Data Store

Custom event data store configuration.

Database

The user-defined database storing event data.

Retention Time

The maximum age of data in the archive.

Purge Size

The maximum number of BSON documents purged in a single batch operation.

Purge Mode

Controls what happens to an object’s data in the store after the object’s deletion.

  • Do not purge: Do not purge data of deleted objects from the store.

  • Purge when idle: Purge data of deleted objects from the store, only when it is idle.

  • Purge continuously: Purge data of deleted objects from the store, even if it is busy.

MongoDB Connection

This property compound combines the properties of the MongoDB Connection e.g. the connection strings to the mongoDB.

Connection String

The connection string for the external system; depending on the type of connection.

Replication Set Name

Configuration name for MongoDB Replica Set.

Replication Set 1

The connection string for the core service to replication set 1.

Replication Set 2

The connection string for the core service to replication set 2.

Authentication Mode

Authentication mode to be used connecting the MongoDB instance.

  • No Authentication: No Authentication is performed when the System connects to a certain instance of MongoDB.

  • Challenge-Response: MONGODB-CR is the default authentication mechanism supported by MongoDB. Username and Password needs to be provided.

  • SCRAM-SHA-1 Authentication: Salted Challenge Response Authentication Mechanism (SCRAM) means that the password is never actually sent over the wire, but rather a computed proof that the client password is the same as the password the server knows.

  • X.509 Certificate: MONGODB-X509 mechanism authenticates a username derived from the distinguished subject name of a X.509 certificate.

  • LDAP (Lightweight Directory Access Protocol): Lightweight Directory Access Protocol (LDAP) service is used for MongoDB authentication.

  • SCRAM-SHA-256 Authentication: SCRAM-SHA-256 authentication means that the password is never actually sent over the wire, but rather a computed proof that the client password is the same as the password the server knows (non-ASCII characters in passwords are not supported).

  • Auto: Detect the default authentication mechanism for users with stored SCRAM-SHA-1 and SCRAM-SHA-256 credentials (requires MongoDB 4.0 or newer).

User Name

User Name.

Password

Password.

Compression

Compress MongoDB data on the wire.

Secure connections

Enable TLS for MongoDB connections.

Allow Invalid Hostnames

Allow invalid hostnames in the server certificate for TLS connections.

Allow Invalid Certificates

Allow invalid server certificates for TLS connections.

MongoDB URI

If not empty, the MongoDB URI takes precedence, overriding all other MongoDB connection settings. The string needs to be URL-encoded.

Effective MongoDB URI

The actual MongoDB URI used for current connection.

Filter Options

Options to filter events.

Stream Objects

List of event stream object paths.

Sources

List of RegEx strings (eg. '\\^/System/Core/obj1 \\^/obj2') which will be evaluated against the event source field.

Messages

List of RegEx strings which will be evaluated against the message field.

Event Types

Event type filters to select one or multiple event types.

  • Filter Simple Events: If switched on, simple events (OPC_SIMPLE_EVENTS) will be filtered by the server and not acquired by the EventStream object.

  • Filter Condition Events: If switched on, condition events (OPC_CONDITION_EVENTS) will be filtered by the server and not acquired by the EventStream object.

  • Filter Tracking Events: If switched on, tracking events (OPC_TRACKING_EVENTS) will be filtered by the server and not acquired by the EventStream object.

Categories

List of RegEx strings which will be evaluated against the event categorie field.

Severities

Allows to filter for multiple severity ranges.

Severity From

Lower limit for the severity filter of events.

Severity To

Upper limit for the severity filter of events.

Conditions

List of RegEx strings which will be evaluated against the event conditions field.

Sub-Conditions

List of RegEx strings which will be evaluated against the event sub-conditions field.

New States

Event new state filters to select one or multiple new event states.

  • Enabled: Enabled.

  • Active: Active.

  • Acknowledged: Acknowledged.

State Changed

Event state change filters to select one or multiple event state changes.

  • Change Active State: Change Active State.

  • Change Acknowledge State: Change Acknowledge State.

  • Change Enable State: Change Enable State.

  • Change Quality: Change Quality.

  • Change Severity: Change Severity.

  • Change Subcondition: Change Subcondition.

  • Change Message: Change Message.

  • Change Attribute: Change Attribute.

Filter Script

A Lua script returning true or false when passed in a event document.

Custom Options

Compound to hold various structures to customize the object and to be read and written to by Lua-Script code or external interfaces.

Custom String

A generic string buffer to be used programmatically for custom purposes.

Custom Properties

This is an extensible set of named strings which can be used programmatically for custom purposes.

Property Name

A custom property name which can be used programmatically.

Property Value

The value of the custom property which can be read and written programmatically.

Custom Tables

This is an extensible set of named tables which can be used programmatically for custom purposes.

Table Name

A custom table name which can be used programmatically.

Table Data

Handles an entire table organized in columns and rows. The data can easily (cut, copy and paste) be exchanged with table-oriented data of other software products, e.g. MS Excel.