Condition Monitoring System Installation

To install the Condition Monitoring System (CMS) module, you need to follow the steps outlined below.

Enabling CMS Services

The default MOPS 4.0 services (docker-compose.yml) configuration file contains definitions the CMS services. These services may be disabled if the core MOPS 4.0 installation was run without activating the CMS module. To enable CMS services, open the .ENV file in the MOPS 4.0 root folder and set the following variables as shown below:

ENABLED_CMS_IMAGE=true
ENABLED_CMS_NOTIF_IMAGE=true
ENABLED_CMS_EMAILCHANNEL_IMAGE=true
ENABLED_CMS_ALERTMGR_IMAGE=true
ENABLED_CMS_CONDITION_MONITOR_IMAGE=true

This will enable the CMS services in the MOPS 4.0 system. If you want to disable the CMS services, set these variables to false.

Creating CMS Database

To create the CMS database, please refer to the Create CMS Database manual.

Do not skip the step of adding CMS metadata to the directory service database. This is important for the CMS to function correctly. This step is described in the same manual.

Configuring CMS

CMS consists of several components that need to be configured before they can be used. These are:

  • Condition Monitor: This component is responsible for tank level monitoring.
  • Alert Manager: This component is responsible for managing alerts state and providing messages when alert state changes.
  • Notification Service: This component is responsible for sending notifications to users when an alert state changes.
  • Email Channel: This component is responsible for sending email notifications to users.

General Configuration for CMS

CMS services use shared configuration from the following configuration file:

conf/general/general-config.json:

{
    "baseUrl": "https://<servername>",
    "subPath": "/doc/",
    "auth": {
        "general": {
            "token_uri": "https://<servername:port>/realms/MOPS/protocol/openid-connect/token",
            "redirect_uri": "https://<servername>/callback",
            "VerifyCertificate": true
        },
        "mops_services": {
            "client_id": "mops-services",
            "client_secret": "Der0CDoU9HK7sZcseGqZMInehk...",
            "grant_type": "client_credentials",
            "scope": "openid"
        }
    }
}

The part that need to be verified in this configuration file is authentication details found under the auth section.

  • general.token_uri: This should point to the MOPS 4.0 authentication service URL, which is will be different for each installation and depends on the server name, port and which identity service is being used.
  • general.redirect_uri: This URL should be the URL returned to after a successful login on the authentication service. It is usually the same as the baseUrl but with /callback appended to it. Replace the <servername> with the actual server name or IP address where MOPS 4.0 is running.
  • mops_services.client_id: This should be set to mops-services, which is the client ID used for MOPS services authentication. If you choose to use a different client ID when setting up the identity service, you need to change this value accordingly.
  • mops_services.client_secret: This is the client secret used for MOPS services authentication. Replace the placeholder value with the actual client secret you set when configuring the identity service.
  • mops_services.grant_type: This should be set to client_credentials, which is the standard OAuth 2.0 grant type used for server-to-server communication.
  • mops_services.scope: This should be set to openid, which is the standard scope for OpenID Connect authentication. If you have configured additional scopes in your identity service, you can add them here. However, for CMS to function, only the openid scope is required.

See the Entra ID Configuration Manual for more information on how to configure the identity service for MOPS 4.0 CMS on Entra ID.

See the ADFS Configuration Manual for more information on how to configure the identity service for MOPS 4.0 CMS on AD FS.

Condition Monitor Configuration

The Tank Order Level Condition Monitor is connecting to the MQTT broker to receive tag update messages. It is also using the Directory service to get the list of tanks and their configuration. From the tank configuration, it is fetching the tags that are used to monitor the tank levels.

conf/mops-cms-conditionmonitor/config.json:

{
    "mqtt": {
        "protocol": "tcp",
        "host": "mops-event-broker",
        "port": 1883,
        "mqttVersion": 4,
        "reconnect": 1000,
        "timeout": 30000,
        "path": "/event",
        "rootPath": "{{messagePath}}"
    }
}

Set the rootPath to the base of the MQTT topic that provide tag update messages. Unless already set you can set this field to mops/historian/+/+/. There should be no need to change the other fields.

Alert Manager Configuration

The Alert Manager is connecting the MOPS Event Broker (MQTT broker) to condition monitoring messages. It is also using the Directory service to fetch configuration for Alerts. The Alert Manager is storing any Alert actions and state changes in the CMS alert database specified in this configuration.

The Alert Manager configuration file for receiving and sending MQTT messages is located at:

conf/mops-cms-alertmgr/config.json:

{
    "mqtt": {
        "protocol": "tcp",
        "host": "mops-event-broker",
        "port": 1883,
        "mqttVersion": 4,
        "reconnect": 1000,
        "timeout": 30000,
        "path": "/event",
    }
}

The database configuration file for the Alert Manager is using the same format as the condition monitor configuration file. It is located at:

conf/mops-cms-alertmgr/db-config.json

{
  "database": "alertdb",
  "user": "u_alertdb",
  "password": "thisisnotthepassword",
  "host": "db",
  "port": "5432"
}

This configuration file defines the database connection parameters for the Condition Monitor.

  • database: The name of the database to connect to. In this case, it is alertdb.
  • user: The username to connect to the database. In this case, it is u_alertdb.
  • password: The password for the user. Replace thisisnotthepassword with the actual password you set when creating the CMS database.
  • host: The hostname of the database server. In this case, it is db, which is the name of the database service in the MOPS 4.0 Docker Compose configuration. If running an external database, replace this with the actual hostname or IP address of the database server.
  • port: The port number on which the database server is listening. In this case, it is 5432, the default port for PostgreSQL databases.

Notification Service Configuration

The Notification Service is responsible for sending notifications to users when an alert state changes. It is connecting to the MOPS Event Broker (MQTT broker) to receive alert state change messages. It is also using the Directory service to fetch configuration for Notifications.

conf/mops-cms-notif/.env:

BROKER_URL=ws://mops-event-broker:9001
CHANNEL1=http://mops-cms-emailchannel:4000/send

Unless the WebSocket port for the MOPS Event Broker has been changed, the BROKER_URL should remain as is. The CHANNEL1 variable defines the URL of the Email Channel service, which is responsible for sending email notifications. This URL should not be changed unless the Email Channel service is running on a different host or port.

Email Channel Configuration

The Email Channel is responsible for sending email notifications to users. It exposes a REST API that the Notification Service uses to send email notifications. The Email Channel configuration file is located at:

conf/mops-cms-emailchannel/config.yml:

sender: "MOPS 4.0 Notifications <no-reply@mopssys.com>"
smtp-server: "<smtp-server:port>"

logging: true
loglevel: "ERROR"

In this configuration file, you need to set the following parameters:

  • sender: The email address and name that will be used as the sender of the email notifications. You can change this to any valid email address and name.
  • smtp-server: The SMTP server and port that will be used to send email notifications. Replace <smtp-server:port> with the actual SMTP server address and port number. This information is usually provided by your IT department.
  • logging: Set this to true to enable logging of email notifications.
  • loglevel: Set the log level for the Email Channel service. You can set this to one of the following values: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

Notification Message Template Configuration

The Notification Service uses message templates to format the email notifications. The templates are defines as Directory entities and can be managed through the MOPS 4.0 UI. Select the system menu Condition Monitoring System > Notification Templates to manage the templates.

Create a copy of teh system-delivered template and make the following changes:

-----------------------------------------------<BR>
Tank: {{identity}}<BR>
Condition: {{conditionRule}}<BR>
Action: {{action}}<BR>
Alert state: {{state}}<BR>
Alert: {{alertName}}<BR>
No: {{alertInstanceNo}}<BR>
Severity: {{severity}}<BR>
User: {{user}}<BR>
Message: {{message}}<BR>
Acknowledged by: {{acknowledgedBy}}<BR>
-----------------------------------------------<BR>
 
{{#if payload}}
Level: {{payload.tankLevel.value}} m³<BR>
Level reported on: {{payload.tankLevel.timestamp}} <BR>
Tank volume: {{payload.entity.Volume}} m³<BR>
Order level: {{payload.entity.[Order level]}} m³<BR>
Order Escalation Level: {{payload.entity.[Order Escalation Level]}} m³<BR>
Notes for delivery: {{payload.entity.[Notes for delivery]}}<BR>
Location: {{payload.entity.Location}}<BR>
{{/if}}

<a href=https://server-name/entity/{{alertId}}?type=e7000000-0000-4000-8000-000000000300>Go to Alert Page</a>

In the above template you need to replace server-name with the actual server name or IP address where MOPS 4.0 is running. This template will be used to format the email notifications sent by the Notification Service.

The type parameter in the link to the alert page is set to e7000000-0000-4000-8000-000000000300, which is the entity type for alerts in MOPS 4.0. This will make the entity list show only alerts.