In this blog you will see an example on how to use ExternalControlBrokerRequests. The example describes how to set up CDP for sending alarm e-mails on some signal values.
Acquire SMTP account details for CDP
To send e-mails from CDP, first you have to choose the SMTP server and account you will be using to send e-mails from. Other options are to use some internal (corporate) SMTP server or to use some external (public) SMTP server. You may need to contact your network administrator for options.
In this example we will focus on using public Google SMTP server and your own e-mail account for sending mail.
To avoid exposing your personal Google e-mail password in the CDP configuration, we strongly recommend you to set up and use a special Google application password. For that, log into Google Account -> App Passwords (https://myaccount.google.com/apppasswords). When logged in, select application type Other, name it ex. CDP and press GENERATE. This generates a long and random password displayed on your screen. Please write it down or copy it securely as we will need it at a later stage.
Add signals you need to watch for sending e-mail
Usually you have signals to watch already existing in your system. But, for this example we create 2 CDPSignal output signals which we want to monitor and generate e-mails based on. Create the signals under ExternalControlBroker component, called Temperature and Humidity.
Furthermore, as we have many signals to watch and do not want an e-mail to be sent for every signal change we need some calculated alarm signal that triggers the e-mail sending. So you will need to create another CDPSignal output signal called AlarmCondition. To configure AlarmCondition click on the play button next to it, locate and add an Evaluate operator for alarm calculation with Temperature and Humidity Arguments (Routed from the Temperature and Humidity signals created earlier) and Expression like
Temperature > 40 || Humidity > 90
This expression causes the AlarmCondition signal to evaluate to true when there is an alarm situation (i.e. temperature value over 40 or humidity value over 90). Please see Operators and Evaluate operator manual for detailed instructions on how to add and configure operators.
Add ExternalControlBroker to your system
Follow these steps to add the SMTPRequest to your CDP system. First add ExternalControlBroker IOServer to your system:
- Click on application name
- Choose a ExternalControlBroker from Resource tree and click Add to add ExternalControlBroker to the application
Add SMTPRequest to ExternalControlBroker
Follow these steps:
- Click on added ExternalControlBroker component
- Set Debug property to 2 (to see informative log entries later, during system run)
- Choose a SMTPRequest from Resource tree and click Add to add SMTPRequest into the ExternalControlBroker IOServer
- Set URL to be Google SMTP server address smtps://smtp.googlemail.com
- Click on the play button next to SMTPRequest to enter for further configuration
Now that signals are set up we can continue to configure SMTPRequest
- Add one RequestSignalChannel<bool> and 2 RequestSignalChannel<int>‘s to RequestChannel table and name them AlarmCondition, Temperature and Humidity correspondingly.
- Set Routings for them to the corresponding signals we created earlier.
- Add 2 ValueMap<bool> elements into ValueMap table, for mapping true (checked) to string ALARM and false (unchecked) to string CLEARED
- Unset TriggerOnStartup property, Unset TriggerOnChange property and set TriggerRouting to the corresponding alarm signal you created earlier, so that only this signal change will trigger an e-mail to be sent
- Set To and From properties to your e-mail address and set Subject property to
%d: Temperature %d *C, Humidity %d %%
and set UserPwd property to your e-mail address + application password generated earlier in form of
Test e-mail sending
Now you are ready to run your system and test this SMTPRequest example. Run your system and connect to it. You can inspect e-mail sending like this:
- Locate and change Temperature signal to be higher than we set alarm level (f.e. 45).
- Inspect application output window to confirm the message was sent like this
ExternalControlBroker: SMTPRequest: Starting SMTP SEND request: smtps://smtp.googlemail.com
- Inspect your e-mail account for corresponding alarm e-mail received
You can easily customize the e-mail body, by adding FormatTranslator and setting suitable Pattern property, for example to:
Hi!\nThis is an automatic e-mail from CDP\nTemperature is now %1% *C\nHumidity is now %2%\nSituation is %0%\nBye!
Note: Please also remember to delete any unused Google application password you created for this test after you finished up with testing.