The problem
Many BMS systems rely on email to notify users of alarms and a lot of people use cell carrier SMS gateways to receive those via text message. In the past this has been great but as email spam wars progress we are finding a lot of notifications are going missing or have a significant delay. Also bulk mailing limits are lower than some realize; Gmail for example is very popular but did you know if you send events via SMTP to four people per message you might see messages cut off if you send more than 25 in a day?
A solution: Pushover
Pushover is a popular app that handles notifications and delivers them to an Android app, iPhone app or desktop web browser notification. The key part is it is reliable and fast utilizing the push messaging platforms built into Android, iOS and browsers. The apps are designed with critical alerting capabilities. A fast and simple integration to Pushover would have your BMS send SMTP straight to the Pushover email address and let it handle delivery to users. If you had control of your own SMTP server and know it to be reliable, quick, and not subject to spam filtering issues this would be a quick solution. What I would prefer though is to remove email from the alarm notification path completely to make it faster and more reliable.
To get started with Pushover you need to create a free Pushover account and create a application API token for your BMS script use. You also need to get the Pushover app on your phone.
Cost
Small/low end solution; The app has a free trial period and is only $5 to purchase after that. The API servers are free for the first 7500 messages per month and you can purchase more if you need it but that works out to about 250 messages a day. If you really need more than than maybe fix what’s wrong, each of these is an alert on a users phone.
If you want to have different servers deliver to different groups of people you can look into the Groups feature. In theory each user would need an account and the server would have it’s own account with a group of users for each application distribution list. At the sending API level you would be sending to a group user key, not an individual user key.
Teams/high end solution; Pushover has a teams solution that is $5 per user/per month and solves the problems above plus doesn’t require users to individually purchase and expense the app purchase. It also pushes the message limit up to 25,000 per month no additional cost and offers SMS fallback delivery in the event push messaging goes down for whatever reason.
Web service request – the easy way for apps that support it
The WebCTRL system I work with supports the reporting action web service request and it is very easy to set up and get working with pushover. The API is documented on Pushovers site and has some interesting additional parameters you might be interested in like device, sound, or priority.
Destination address is; https://api.pushover.net/1/messages.json
You need to do HTTPS POST to that address with content type JSON and at a minimum have token, user, and message parameters.
Scripting – The hard way for apps that don’t support web service request
Fire up a text editor, create a new file with the contents below and save it somewhere easy to get to. I put mine in C:\temp. Edit the file and replace the token and user keys with the values from your Pushover account. The message field has two pieces, $event will be replaced by the string we will send to the script via the command line. The example URL I’ve put here gives the user something to tap on and open the front end of your BMS app, this is optional but really handy.
param (
[string]$event = "Event Is Empty!"
)
$uri = "https://api.pushover.net/1/messages.json"
$parameters = @{
token = "your application API token here"
user = "your user key here"
message = "$event https://demo.example.com/"
}
$parameters | Invoke-RestMethod -Uri $uri -Method Post
From here you need to fire up powershell and do some checks. First off do a version check;
echo $PSVersionTable
You will need version 3 or greater. As it’s now 2020 I anticipate no real problems here for anyone.
Next step is to try to send a message using powershell
.\pushover.ps1 -event "test event"
Unfortunately you should get an error here, scripting is disabled by default and this page explains it. In my case I’m logged onto the server as the user our BMS application service runs under so I chose to allow scripting for the current user by running this below. You need to make a choice on what app is going to call your script in the end and what account that is running under and set up scripting execution appropriately.
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
After that when you check execution policy you should get this back;
Get-ExecutionPolicy -List
After getting permissions try again to send your test event, hopefully you get a status request back and the event ends up on your phone.
From here most BMS systems will have a way to run an external program, the problem is it’s similar to running something from the DOS prompt and not powershell. So we need to do a test and see if we can call the powershell script from a command prompt. You should see a similar confirmation to what you saw in powershell. Note that I am sending a full path here and the use of the single quotes inside the double quotes.
powershell "C:\Temp\pushover.ps1 -event 'example event text'"
Finally I’ve got all the pieces necessary and ready on the server to send messages straight to Pushover and avoid email completely. From here on I’m going to detail what that looks like inside WebCTRL.
Note; WebCTRL 7 and higher requires you to run the application in design mode to add or edit a “run external program” reporting action. On top of that the event simulator will not work in design mode so you can’t see the results which means a lot of switching back and forth to experiment. I’m going to suggest starting with the “write to file” reporting action and playing with the field codes to get nice legible messages to a text file first and then copying those field codes to the run external program reporting action. This syntax worked pretty well for me;
powershell "C:\Temp\pushover.ps1 -event 'State: $to_state$ Short MSG: $short_message$ Long MSG: $long_message$ At: $location_path$'"
Note; you might need to edit some alarm/event text or templates to get rid of any single quotes. The alarm template proof for example has some single quotes that will mess up our command line messages.
From here simulating an alarm in a piece of equipment should result in an instant alert on the phone.
