THE CHALLENGE OF ADMINISTERING WEBSITES OR APPLICATIONS THAT REQUIRE 24/7 ACCESSIBILITY As the constantly growing demands of businesses and organizations operating in a global economy cause an increased dependency on the always-on nature of the internet, the demand for website services and applications that are continually accessible increases at the same rapid pace. The challenge faced by most website or application administrators today is that of being able to provide continued service with minimal downtime in the face of a dynamic online environment that is known at times to respond in unexpected ways. Despite the increased system reliability and stability of today s secure websites, and advanced application architecture, there will always be occasions where unexpected downtime is a reality. By catering for these occurrences with an alert and monitoring system, it is possible to enable all traffic to be sent to other machines automatically when a server or system goes down and to notify the administrator about the situation immediately. Users can then continue to access website services and applications, enjoying uninterrupted service. SMS: A RELIABLE, SECURE, ALTERNATIVE SMS text messaging provides a simple, fast and low-cost method to send system alerts to system administrators, I.T. managers and any other party, despite their location. While email was previously virtually the only technology used to send system alerts, today s software developers are turning to a better alternative - SMS text messaging. SMS text messaging offers the following advantages over email: Push Technology It is not necessary for a cell phone to poll an SMS center constantly in order to receive new SMS text messages. SMS text message notifications will be pushed to pre-determined cell phones. Unlike SMS, email is a "pull" technology. To find out if an email server has any new messages, an email client needs to poll the email server regularly. Mobility SMS alerts can reach you anytime, anywhere and do not require the user to be in front of their computer. Cell phones that are capable of reading emails, are still reliant on "pull" technology, resulting in unnecessary data transmission fees to the network operator and the cell phone as it constantly checks for new messages. Simple set-up, rapid integration Sending emails from website and applications is a well known simple and relatively low cost method of delivery. What about SMS? Is it easy to enable SMS text messaging for a website or application? How much does it cost to send an SMS text message? SMS setup is simple and offers rapid integration with any website or application. Sending SMS text messages via Clickatell's HTTP API requires only a few lines of code. Clickatell also provides an SMTP API to developers. With the SMTP API, you can send ordinary emails to Clickatell, and Clickatell will convert them to SMS text 2
messages and deliver to mobile recipients. The same SMS text message notification can be sent to multiple cell phones, ensuring the SMS text alert can be acted upon quickly. While the exact price of sending an SMS text message varies from country to country, it generally costs no more than a few cents for the peace of mind of having a notification delivered directly to your mobile. Now let's see the 5 steps to get you started: DevelopersHome.com and Clickatell explain how to enable SMS text messaging for your system alerts Step 1: Check Requirements Following are the requirements for enabling your alert system with SMS messaging: First, register an account with Clickatell in order to send SMS messages via Clickatell's Bulk SMS gateway. Every new account has 10 free SMS credits which you can use for testing. Having some knowledge in server-side web programming is required. In this guide, the code examples are written in PHP, but it is not necessary for you to be proficient in PHP the principles will remain the same regardless of the programming language you use. The PHP code used in this guide is straightforward and it should not be difficult to apply the knowledge to other server-side web technologies, such as ASP.NET (C#, VB), ColdFusion, Java Servlet, JSP, Perl, Python, etc. In order to run the code examples on your PC, you will need the software below: A web server like Apache, which can be downloaded from http://httpd.apache.org/ free of charge, and PHP, which can be downloaded from http://www.php.net/ free of charge. If you have an account with a web hosting provider, you should upload the code to your web hosting account and run the code there. In this case, you do not have to install any software on your PC. 3
Step 2: Understand Your Alert System It is important to understand your alert system in order to know what modifications should be made to integrate SMS text messaging. Generally, an alert system works in the following way: 1. When a certain condition is met (for example, the monitoring system finds that one of the servers is not responding), the alert system triggers an event. 2. You assign an event handler to the event. Whenever the event occurs, the alert system runs the code in the event handler. As you can see, the event handler is where you would integrate SMS text messaging. While the actual steps will vary for different alert systems, for demonstration purposes we will create a very simple alert system that monitors the responsiveness of a web server. We will then demonstrate how to integrate this alert system with SMS text messaging. In general, if you need to modify an existing alert system, you would have to consult the documentation of your alert system for the specific instructions on how it can be done. First, we need to write a PHP function that checks whether the web server is responding to requests. The PHP function attempts to fetch the home page from the web server. Here's the code: <?php /* is_server_alive.php */ function is_server_alive($hostname) { $url = 'http://'. $hostname. '/'; $file = fopen($url, 'r'); if (!$file) return false; return true; }?> 4
The function is_server_alive() above takes one argument, $hostname. It contains the host name of the web server that you want to monitor (for example, www.developershome.com). The PHP function fopen() helps us fetch the file located at $url. Make sure the value of the allow_url_fopen directive in the php.ini file is On. If not, fopen() cannot handle HTTP URLs. The second argument, 'r', tells fopen() that we want to fetch the file for reading only. If the operation is successful, fopen() returns a file pointer, which can be passed to functions such as fgets() and fread() to read the file contents. At this point the file contents are not useful to us, since we simply need to know if the web server is responding to requests. If the web server is not responding or other errors occur, fopen() will return the boolean value false. More detailed information about using the PHP function fopen() to open remote files can be found from http://www.php.net/manual/en/features.remote-files.php and http://www.php.net/manual/en/function.fopen.php. Next, we need to write some code to call an event handler when we find that the web server is not responding: <?php /* monitor.php */ require_once('is_server_alive.php'); require_once('event_handler.php'); define('hostname_of_server', 'server1.developershome.com'); if (!is_server_alive(hostname_of_server))?> event_handler(hostname_of_server); To run the PHP script monitor.php regularly (for example, every three minutes), we need to use a feature called Cron, which enables the scheduling of tasks called Cron jobs. The steps to set up a Cron job for different web hosting providers vary slightly. 5
Visit your web hosting provider's website for the precise instructions. Normally the steps are similar to these: A. Create a new Cron job. Normally you can find a "Create a new Cron job" button by logging in to your web hosting account and then going to the control center. B. Enter the command to run. For example, "php /home/mydomain.com/monitor.php". C. Enter the time interval that the command should run. For example, every three minutes. D. Enter an email address for getting the output of the PHP script. This is useful for debugging your script. While this step is usually optional, if you do not enter an email address, the output of the PHP script will not be sent to you. Now we can edit the event_handler() function to add tasks that we want the alert system to perform when the web server goes down - for example, logging down the event or sending an email alert. Advanced users may want to remove the failed web server from the DNS system and distribute the load to other web servers. <?php /* event_handler.php */ function event_handler($hostname_of_server) { $text_message = 'Alert: '. $hostname_of_server. ' did not respond.'; send_email($text_message); }?> 6
Step 3: Register for a Clickatell Account and Get API ID Three values are required to connect your system to the Clickatell Bulk SMS gateway via the HTTP API the username of your account, the password of your account and the API ID (this can be found by logging in to your account.) If you do not have an account, you can register for one free of charge by following the simple steps below: A. Go to Clickatell's home page at http://www.clickatell.com/. B. Click the "My Account" button in the top right corner of the page. C. Click the "Product Selection" combo box and select the "Clickatell Central (API)" item. 7
D. Enter information into the registration form. Then click the "Continue" button. 8
E. Clickatell will send a verification email and a verification SMS to you. Enter the two verification codes into the form and then click the "VERIFY NOW" button. F. If the verification is successful, you will be logged in automatically. 9
To create your API ID, follow the steps below: A. Log in to your account and click the "Manage My Products" button in the menu at the top of the page. B. Click the "My Connections" combo box and select the "HTTP" item. 10
C. Enter a name to the "Name" field of the form. Then click the "Submit" button. You will find the API ID in the next page. Step 4: Write a Function to Send SMS Text Messages Next, we need to write a PHP function that sends an SMS text message to a cell phone via Clickatell's Bulk SMS gateway. Here is the PHP code: <?php /* send_sms.php */ function send_sms($user, $password, $api_id, $to, $text) { $text = urlencode($text); $url = 'http://api.clickatell.com/http/sendmsg?user='. $user. '&password='. $password. '&api_id='. $api_id. '&to='. $to. '&text='. $text; } $response = file_get_contents($url); echo $response;?> 11
The send_sms() function above takes five arguments. The first and second arguments, user and password, are the username and password of your Clickatell account. The third argument, api_id, is the API ID that we obtained previously. The fourth argument, to, is the cell phone number in the standard international format. The country code (Note: without the "+" character) should be included and there should be no leading zero to the cell phone number. For example, to send a text message to the UK number 07901234567, the to argument should be 447901234567. The fifth argument, text, is the text message to be sent. The code itself is straightforward. First of all, the PHP function urlencode() is called to encode special characters (if there are any) in the text message. This must be done because in the next step we will put the text message in a query part of a URL, and special characters must be encoded properly in order to follow the syntax of URL. The URL should be composed according to Clickatell's HTTP API specification, which can be downloaded from http://www.clickatell.com/downloads/http/clickatell_http.pdf. The PHP function file_get_contents() is used to fetch the file located at $url. It is very similar to fopen(). The main difference is that file_get_contents() returns a string that contains the file contents, while fopen() returns a file pointer. Like fopen(), file_get_contents() requires the value of the allow_url_fopen directive in the php.ini file to be set to On in order to open HTTP URLs. After calling file_get_contents(), if the operation is successful, the variable response contains the data that the SMS gateway sends back. We can use it to determine whether an error has occurred. If there is no error, the SMS gateway will send back a unique message ID, like this: ID: a37ad2e4090ea662fadec39f95a3a87e Otherwise, the SMS gateway will send back an error number, for example: ERR: 101 Error number 101 means the parameters are either invalid or missing. You can find the meanings of error numbers in Appendix A of Clickatell's HTTP API specification. 12
Step 5: Integrate SMS Text Messaging with Alert System together. We can now modify the event handler to integrate SMS text messaging and the alert system <?php /* event_handler.php */ require_once('send_sms.php'); require_once('stop_sms_sending.php'); require_once('increment_number_of_sms_sending.php'); function event_handler($hostname_of_server) { $user = 'xxx'; $password = 'xxx'; $api_id = 'xxx'; $to = '447901234567'; $text_message = 'Alert: '. $hostname_of_server. ' did not respond.'; if (!stop_sms_sending($hostname_of_server)){ send_sms($user, $password, $api_id, $to, $text_message); increment_number_of_sms_sending($hostname_of_server); } }?> 13
We've added two new functions, stop_sms_sending() and increment_number_of_sms_sending(). The purpose of these two functions is to limit the number of times that SMS alerts are sent. Without these two functions the alert system would send an SMS text message every 3 minutes until the failed server was fixed. Here's the code in the stop_sms_sending() function: <?php /* stop_sms_sending.php */ function stop_sms_sending($hostname_of_server) { define('max_num', 3); $num = file_get_contents($hostname_of_server. '.txt'); if ($num!=false){ if ($num >= MAX_NUM) return true; } }?> return false; 14
The stop_sms_sending() function attempts to read a plain text file that stores the number of times that SMS alerts have been sent. The file name depends on the host name of the web server that the alert system is monitoring. For example, if the host name is server1.developershome.com, the stop_sms_sending() function will attempt to read the file server1.developershome.com.txt. If SMS alerts have been sent three times, stop_sms_sending() will return true, which indicates no more SMS text messages should be sent. Below shows the code in the increment_number_of_sms_sending() function. It increments the number of times that SMS alerts have been sent and saves the new value to the plain text file. <?php /* increment_number_of_sms_sending.php */ function increment_number_of_sms_sending($hostname_of_server) { $num = file_get_contents($hostname_of_server. '.txt'); if ($num!=false) $num += 1; else $num = 1; file_put_contents($hostname_of_server. '.txt', $num); }?> To reset counting, just delete the text file that stores the number of times that SMS alerts have been sent. While there are more elegant ways to do this we will not discuss them further since the focus of this guide is on integrating SMS text messaging with an alert system. 15
ABOUT DEVELOPERS HOME DevelopersHome.com helps programmers who wish to extend their knowledge to the wireless world by introducing them to the skills needed to develop and maintain sites and applications for wireless devices. Code examples in tutorials and articles follow the standard of the corresponding technology ensuring that developers learn and understand how to build mobile applications using the latest technologies. ABOUT THE CLICKATELL GATEWAY Clickatell Gateway s Developer API Clickatell's Developer Solutions allow you to SMS enable your social networking website or application via a range of API's. Our SMS Gateway offers your website or application a hosted messaging platform to SMS-enable system. We give you the immediate capability to deliver and receive messages to and from any application, via our global operator coverage. We've gone to great lengths to ensure any developer who wants to interface an application, site or system with our messaging gateway can do so reliably and simply. Our APIs are fast, simple and reliable, and built in such a way that they are easily manipulated to fit with any system. And with our quick online registration you are able to get started and use them right away. A great extension to the API is the two-way (bidirectional) messaging capability, which is available in over a 100 countries. 16
Learn more about each of our API connectivity options below: SMPP API Our most robust connection, suitable for customers who send large volumes of traffic. Clickatell offers a global SMPP connection using the SMPP 3.3 standard. Customers are required to have SMPP client software in place, and unlike our other APIs there are minimum volume requirements when using SMPP. Sign up HTTP/S API Our most popular connection, HTTP is one of the simpler ways to connect to the Clickatell API. It is used as an HTTP/Internet Post. Sign up. FTP API Suitable for once off, high volume messaging. The FTP upload facility allows customers to upload text files to Clickatell's FTP site, and have the files automatically dispatched to message recipients. Sign up. SMTP [E-mail to SMS] API Another firm favourite, the SMTP API allows messages that are sent via e-mail to be converted to SMS. Popular with customers who already have an e-mail messaging system in place. Sign up. 17
XML API If you are familiar with XML, Clickatell offers an XML interface with its own set of DTDs. Currently supports XML over HTTP. Sign up. SOAP API SOAP is a protocol for exchanging XML-based messages using HTTP/HTTPS. SOAP forms the foundation layer of the web services protocol stack providing a basic messaging framework upon which abstract layers can be built. Sign up. 18