Example Notification from a Command Line Program

An interesting tool for notifications that we've found is iPing (http://www.iping.com/). This tool gives you several ways of generating by computer a notification that iPing will read to the recipient over the phone. You can use this tool in any version of InterMapper by making an email notifier where the email address is ping.<yourAccountName>@iping.com.

However, iPing also has an API, one method of which allows more control over how the notification is carried out. This method, putnotification, is invoked via http. With a command-line tool like "curl" and InterMapper's command-line notifiers, you can create a powerful and tailored iPing notifier for InterMapper.

Implementing an iPing Notifier

The curl utility is already available on many Unix systems. If it is not available on yours, or if you are using Windows, you can find out more about it and download a copy from http://curl.haxx.se/. You can find out more about the putnotification API method for iPing from http://www.iping.com/ipingv2/PutNotification.aspx. The rest of this command-line notifier tutorial assumes that curl is installed and that you have an iPing account.

First, make sure that curl or an alias or soft link to it is in the Tools directory on the InterMapper server. The Tools directory is a subdirectory of the InterMapper Settings directory. If you do not have a Tools directory, you will need to create one. For security reasons, only executables in this directory may be executed as notifiers.

Open the Server Settings dialog box and click on the Notifier List entry. Click on the Add... button and choose a type of Command Line. Give it a name.

In the "Command" field, enter the iPing notification command you want to use. A simple example to send a message to a phone number immediately would be:

curl 
"https://www.iping.com/services/iping.asp?method_name=putnotification
&user_name=testdriver
&password=12345
&phone_number=8448675309
&notification_dt=now
&msg_text_body=${ESCAPED_MESSAGE}"

Note: All the text above should be on a single line, with no blank spaces in the URL.

The parameters to the iPing message are:

• method_name must be "putnotification"
• user_name the name of your iPing account
• password the password of your iPing account
• phone_number the phone number to dial
• notification_dt Valid notification date/time (see the iPing documentation) or "now"
• msg_text_body The text of the message to be spoken.

Note 1: The msg_text_body must be in a form suitable for inclusion in a URL. In particular, the text should not contain spaces, ampersands (&), question marks (?) or a number of other characters. InterMapper provides two macros that make it easy to enter the text:

• ${URLESCAPE: xxxxx} This macro returns a string that contains the text ("xxxxx") with all the URL special characters escaped properly.
• ${ESCAPED_MESSAGE} This macro is a special case facility that performs the URL escaping function on the notifier's ${MESSAGE} string, as entered by the user. Click the "Edit Message" button to modify the default message. The default message is fairly short, as is appropriate for command-line notifications.

Note 2: The curl command generally exits with a code of zero. This avoids InterMapper log messages warning of unsuccessful notifications.