OGEMA Messaging Configuration

Last modified by David Nestle on 2019/03/01 16:52

Introduction

The OGEMA widgets repository contains a small messaging framework that allows apps to inform the user about important events, like bugs that occured or required actions to be taken. Messages are generated by the app in a technology-agnostic way, and can be forwarded via different service providers (implementing the MessageListener interface), like Email, SMS, XMPP, etc. The forwarding must be configured by the user via the message-forwarding app. Typically, every messaging service comes with its own configuration page, since the configuration for the different messaging technologies is quite specific. There is however a common configuration page available for the three basic services Email, SMS and XMPP (the message-settings app). 

As well as general fowarding the message in OGEMA System, it will be explained regarding to messages by email for gateway's state monitoring, because it is mostly used at managing the competition. Developing and Cofigurating the messaging app is also explained in order to create and modify the application.

For a very short introduction see OGEMA Utilily Classes and Concepts Reference .

Messaging Providers

In OGEMA System following messaging providers are available in the repository: Email, SMS(via Email), XMPP, Telegram, Pushover, OGEMA REST

Email: Managing an email will be written in the next part 'sending the message in OGEMA Server'.

SMS (via Email) : The sending of SMS works via email. Typically, it is necessary to create a paid account at an email2SMS service provider for this purpose. Again, the password for the email account needs to be stored on the box.

XMPP

Telegram: The connector for the telegram messenger works via a so-called Telegram bot, which acts as the sender for the messages. See also the bot API documentation: https://core.telegram.org/bots/api.

The service requries two main configuration parameters, the bot ID and the chat ID (to create the latter, you need to send a message from your account to the bot once, and use for instance the getUpdate-API of the bot to find out the chat id, as explained here: https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id). To start the service, the following system properties must be set:

  •     org.ogema.messaging.telegram.key -> bot id
  •     org.ogema.messaging.telegram.username -> bot name (just for display)

Then use the configuration page of the Telegram connector to add a user and set your chat id. Note: if the bot you are using is your private one (i.e. not shared by multiple users), you can configure the connector to automatically create the user once it receivces a message. For this purpose set the system property

  •     org.ogema.messaging.telegram.privatebot=true

TODO screenshot telegram connector config page.

Potential sources of error: If you delete the chat with the messaging bot, your chat id will be gone and message forwarding towards this chat id doesn't work anymore.

Pushover: TODO

OGEMA REST :TODO

Sending the message in OGEMA server

After creating user with the specific data you have to create a forwarding configuration. It is already programmed to send an email after auto-evaluation, but you can also do this manually in OGEMA server. You can also simulate sending messages in your local pc and it has no other difference with doing in server. Following steps are the general way to set sending messages in OGEMA and we mostly need everyday messages for monitoring in gateway's latest state, so the steps are explained as an example of receiving a message from dataqaulity-evaluation.

1. You should first set sender and receiver. In the Message Settings app you can first configure receiver. Click the Button 'Create new receiver', fill the receiver’s name and email-address. After Accepting the receiver will be set and shown on this page. You can any time edit this setting.

https://www.ogema-source.net/wiki/download/attachments/13467689/firefox_2018-12-10_12-54-48.png?version=1&modificationDate=1544443635341&api=v2

2. To configure the sender, go into 'Edit senders' under the Select page menu. Likewise, you can give sender’s name and email-address. But you also need to write password and server-URL and port.

https://www.ogema-source.net/wiki/download/attachments/13467689/firefox_2018-12-10_12-53-36.png?version=1&modificationDate=1544443547835&api=v2

How to configure your application to send a message to the configured receiver -> See the section ‘How to develop messaging configuration: OGEMA Utilily Classes and Configuration Application’

3. To be able to receive messages from one of the provider presentated above, you have to create a forwarding configuration. For every message sending App you can send configure how you get messages from it. By setting the dropdown option to a priority you choose to receive (LOW, MEDIUM, HIGH) or not receive (NONE) messages from this specific App, the default value is "NONE". If a value is selected, you will receive messages from this App with a priority equal or higher than the set one.Example (Here we want to receive Messages with a priority of LOW or higher (all messages) from the evaluation-offline-control via Email-connector):

image-20190301133142-1.png

4. Now go into the ‘evaluation-offline-control’ app and click the Start button on the line ‘basic-quality-eval-provider’ (or your evaluation page).

5. Still you can’t find ‘MultiKPI’ pages under the ‘Set Page’ menu, where you actually send mails. To create this page, you should click the button ‘Add KPI-pages offered by provider’ on right side at the bottom of the page. Then you will see the pages 'MultiKPI: basicQualityStd' and 'MultiKPI: rexoQualityStd'.

6. In these pages you can find the Button 'Send Message'. Click the button and you will receive a mail in a few seconds. 

7. You can also check whether the message was sent in the ‘message-reader’ or right upper side box on the page of offline-evaluation-control. You can see the history of sent messages from the server.

image-20190301133354-1.png

Messaging Test

Send messages from the test app via its user interface. The messaging test app user interface.

image-20190301133429-2.png

In case of not comming the message

Because of the missing mail protocol, the generated email could not be sent. In this case check the email SMTP server settings.

E.g. when using web.de as sender email adress:

In the menu Einstellung go tinto E-Mail > Einstellung > POP3/IMAP Abruf > WEB.DE Mail über POP3 & IMAP

Check the box with the text "POP3 und IMAP Zugriff erlauben".

Alarming messages from OGEMA Server

The application Evaluation-Offline-Control provides KPI-results for the gateways executing automatic evaluation every day. This is the essential page for evaluating everyday values in gateways. About Evaluation-Offline-Control you can refer to this page: Evaluation Offline Control App. In this application the values are tabled after the type of values and the range of the gateways. If you have only a few gateways it will be not difficult to find changes of values in daily values, otherwise you will have to dedicate fairly your working time on looking for these and it could be not always exact. For this reason, automated alarming to monitor gateway’s state is necessary. This alarm message will be provided by emails once a day after executing daily evaluation in server.

After following the above steps in 'Sending the message in OGEMA Server', you will receive the mail. However, please note the sending messages should be done after daily evaluation. If you want to get an email before the auto-evaluation and send an email to your email account, you will receive an email with a lot of incorrect message lines, because this mailing service is for today’s evaluation, not for the yesterday’s. In the email with right information you can read changes, which values in which gateways are jumped up or fell down. From these alarms you have to consider what is the reason of occurring the errors and how can you fix it, if the alarm reports errors. More about the evaluation for occurring and resolving errors in a given period, e.g. a week, a month or a year, with the messages, refer to this page: [TODO: create a new page in intern site].

What information is contained in messages?

The alarming mail contains information of the variation, if there are some changes of values in a gateway between last two days. All the valid values should be maintained in transferring the data from gateway or databank to the server. E.g. the number of sensors of a gateway should be arrived to the server under total amount of sensors and furthermore their quality, so called good-data or gold-data, should be guaranteed. Sometimes they are related each other, so one deteriorated or improved data type leads to another value types changes. Mostly you will receive two mails, one is for the thermostat-data-quality and one for the electric meter, rexometer.

How to develop messaging configuration: OGEMA Utilily Classes and Configuration Application

You may have better ideas how we more efficiently monitor by messaging and want to edit settings or add some information. You should just modify the right codes on your local pc and adapt to the server. You can modify the code in the path [/timeseries-dataquality-analysis/src/main/java/org/ogema/timeseries/provider/tsquality]. After then replace the source in server. Replacement the source in server and update the server: [TODO: insert the link serverupdate-page]

Utility classes: Categories and current structure

Resource naming and Internationalization
  • Get name for resource for GUI / logging based on name resource or resource name: ResourceUtils.getHumanReadableName(Resource r)
  • An alternative, customizable way to retrieve a human-readable name for a resource representing for instance a device or a room: use the NameService, available from OgemaGuiService. The SDK comes with a default implementation (bundle name-service-impl), but this can replaced, for instance in order to provide names in additional languages, use different naming conventions, etc. Example: room-link-app (source code not public yet, accescible for OGEMA Alliance participants).
  • Get an icon for a resource, for display in a GUI: similarly to NameService, use IconService, also available from the OgemaGuiService. You can replace the implementation bundle icon-service-impl to change the icons used. Example: room-link-app (source code not public yet, accescible for OGEMA Alliance participants).

And here is a simple example how to configure your application to send a message to the configured receiver:

@Component(specVersion = "1.2", immediate = true)
@Service(Application.class)
public class SimpleMessagingApp implements Application {
 ApplicationManager appMan;

@Reference
private OgemaGuiService guiService;

@Override
public void start(ApplicationManager appManager) {
 this.appMan = appManager;
}

public void sendMessage(String subject, String body) {
  MessagePriority pr = MessagePriority.LOW;
  Message msg = new MessageImpl(subj, bod, pr);
 try {
   guiService.getMessagingService().sendMessage(appMan, msg);
 } catch (RejectedExecutionException e) {
   appMan.getLogger().warn("Message could not be sent: "+ e);
 }  
}
...
}

another similar example is:

image-20190301115951-1.png

Tags:
Created by Su Hyun Hwang on 2019/02/20 10:47