CMS Interfaces Reference

DISCLAIMER: The initial release of CMS does not fully comply with the below specification. Coming releases will intruduce changes to bring CMS to comply with the specification.

This section describes interfaces between modules in the Condition Monitoring System. The diagram below show the primary modules of CMS and which modules are communicating.

NOTE: The diagram have been simplified by excluding the MOPS 4.0 Event Broker. Asynchronous communication on the MQTT protocol (I1, I2, I4) is instead drawn directly between CMS modules in order to provide a clearer presentation.

Condition Monitors Interface (I1)

Any service sending messages to the Alert Manager, via the Event Broker, is by the MOPS 4.0 system considered to be a Condition Monitor (CM). Condition Monitors are required to follow the defined format defined by I1 (Condition Monitor Interface) when communicating with the Alert Manager.

Messages from a condition monitor to the alert manager defines actions that operates on an alert. Alerts are defined in the MOPS 4.0 Directory and identified by its Id in the message.

The is defined as a JSON objects in the following format:

{
  "alertId": string,
  "identity": string,
  "action": string,
  "conditionRule": string,
  "entityReference": string,
  "user": string,
  "message": string,
  "payload": object,
}

^UUID A Universally Unique Identifier (UUID) is a 128-bit label used for information in computer systems. The term Globally Unique Identifier (GUID) is also used, mostly in Microsoft systems.

Actions

Actions may originate from different system componentsmodules and users as manual actions. The source column below lists valid sources of actions.

Example Condition Monitor Message

An example message following the above format:

{
  "alertId": "dcbb0dea-f198-4f2f-8a38-7bd7639be6d3",
  "identity": "FS-145-T1",
  "action": "escalate",
  "conditionRule": "TankOrderLevel",
  "entityReference": "/tanks/fennoside145-t1",
  "user": "system",
  "payload": {
    "unit": "m3",
    "volume": "11",
    "currentLevel": "3",
    "orderLevel": "2",
    "criticalOrderLevel": "1.5",
    "normalizationLevel": "3.5",
    "supplier": "Kemira Chemistry",
    "notesForDelivery": "South entrance",
    "location": "Harbourcreek Pulp Mill",
    "tankNo": "FS-145-T1"
  }
}

The payload field passed in the message is picked up by the alert manager and included in the message published as a response to an alert state change. The notification service receives the message and can use the payload data when formatting the notification sent to end users.

See link below for details.

Alert Manager Interface (I2)

The message published by the alert manager contains the information provided by the condition monitor and a few additional fields as described below.

{
  "alertName": string,
  "alertId": string,
  "identity": string,
  "alertInstanceNo": number,
  "action": string,
  "state": string,
  "severity": string,
  "time": string,
  "conditionRule": string,
  "entityReference": string,
  "user": string,
  "message": string,
  "acknowledgedBy": array,
  "payload": object
}

Alert States

An alert combined with an identity identifies an item that in the condition monitoring system that is given an alert state. Each alert/identity may enter and leave activate state more than once and each time the alert item is activated, an alert instance is created and logged by the alert manager. Note that only once instance may be active at a given time for an alert/identity pair. An alert instance that is active may have one of the following states.

In this diagram, text within parenthesis means:

• cm - Transition may be invoked by the condition monitor
• manual - Transition may be invokes by a user as a manual action
• am - Transition may be invoked by the alert manager

Example Alert Manager Message

An example message sent from the alert manager may look like:

{
  "alertName": "FENNOSIDE145-T1 Order Level",
  "alertId": "dcbb0dea-f198-4f2f-8a38-7bd7639be6d3",
  "identity": "FS-145-T1",
  "alertInstanceNo": 23,
  "action": "normalize",
  "state": "Deactivated",
  "severity": "Information",
  "time": "2023-10-26T08:32:55.938801",
  "conditionRule": "TankOrderLevel",
  "entityReference": "/tanks/fennoside145-t1",
  "user": "system",
  "message": "Level above normalization level",
  "acknowledgedBy": ["Michael Estwik", "Fredrik Widmark"],
  "payload": {
    "unit": "m3",
    "volume": 11,
    "currentLevel": 3,
    "orderLevel": 2,
    "criticalOrderLevel": 1.5,
    "normalizationLevel": 3.5,
    "supplier": "Kemira Chemistry",
    "notesForDelivery": "South entrance",
    "location": "Harbourcreek Pulp Mill",
    "tankNo": "FS-145-T1"
  }
}

Notification Service

The notification service have the responsibility to format messages given an input dataset. From this dataset, the notification service need to be able to deduce the following information:

• Recipients of the notification
• The template to use when formatting the notification
• The channel to use when sending the notification to a specific recipient
• The sending channel will also need channel-specific addressing information (i.e. e-mail, phone number)

The notification service currently supports the format received from the alert manager, as described above by I2. From an alert manager message, the notification service obtains the required information as:

1. Using the alertId provided in the message, notification service fetches alert configuration from the directory. This configuration include
   • Recepients defined as a list of accounts and roles and to what actions a notification should be sent.
   • Notification template to use when formatting the message.
2. The notification service recepients to accounts and formats a notification message for each account.
3. The notification service selects the notification channel(s) chosen by the user (user profile) and invokes the channel to send the notification message.

Note: An account may be created in MOPS 4.0, that can not be logged in to, but in its profile settings be given an e-mail that represents an e-mail distribution list. This way notifications can be targeting e-mail distribution lists.

Profile Settings related to Notification Service

TBD.

Notification Sender Interface (I4) (TBD)

Notification sender as described here represents a generic application that sends messages to end users that are not related to alerts. These messages will have a slightly different format.

The only required field in the message provided by a notification sender is the notificationId.

{
  "notificationId": uuid,
  "payload": object
}

Example Notification Sender Message

The below example dataset shows, although incomplete, a dataset not coming from the alert manager. This function may be used to distribute simple reports or notifications based on a schedule, events or manual actions.

{
  "notificationId": "186dc067-6216-4548-99ad-b1cfb1ea94c8",
  "payload": {
    "reportdata": [
      { ... },
      { ... },
      { ... },
      { ... },
        ...
      { ... }
    ]
  }
}

Notification Channel Interface (I3)

The notifcation channel interface is a REST interface defined as :

• POST http://mops-cms-notif/send

The endpoint takes no parameters.

The endpoint takes the following payload in JSON format:

{
  "recipients": [],
  "channelSettings": {
    // TBD
  },
  "notification":{
    "subject": "",
    "body": ""
  }
}

Manual Action Interface (I5)

A user can execute actions directly on an alert instance. These are referred to as manual actions. Available manual actions are:

• escalate — raise the alert level to Escalated to declare urgency or other requested attention.
• acknowledge — communicate to other recepients that you intend to act on this alert.
• deactivate — Close the selected alert instance.

For below endpoints:

• alertid — is the uuid of the alert entity
• identity — is the identity of the alert.

For all below manual actions, the server records action, time stamp and user from access token.

acknowledge

POST alerts/{alertid}/{identity}/acknowledge

{
  "message": "Message entered by user"
}

escalate

POST alerts/{alertid}/{identity}/escalate*

{
  "message": "Message entered by user"
}

deactivate

POST alerts/{alertid}/{identity}/deactivate

{
  "message": "Message entered by user"
}