How was the Get Started Phone call done?

The Get Started tutorial used a third party site named Twilio (www.twilio.com) to call your phone when an alert was generated on the platform.

In this tutorial, we will explain how it was done and how you can use Twilio for your applications.

What is Twilio?

Twilio provides a web-service API for businesses to build scalable, reliable communication apps. With Twilio's features, you can make voice calls, SMS, and other features described on their site.

Twilio provides documentation and sample codes to assist you in building your cloud application. The flow works like this: an application calls Twilio's API with a phone number to call. When someone answers the call, Twilio POSTs a call (REST style) to a URL you specify. This call returns the message to speak to the person.

 

Expression Rule and Groovy Scripts

We incorporated Twilio into our platform by using our custom objects (Groovy Scripting) functionality.

Two scripts are needed because one calls Twilio and the other handles the call back from Twilio.

Expression Rule: NotifyOnAlarm

In Get Started, you learned about Expression Rules. One of the Expression Rules was NotifyOnAlarm.
This Expression Rule executed a Groovy Script that would call you and notify you that an alarm had occured.

Let's take a closer look at the Rule and what it does.

The type of the Rule is Alarm. When an alarm's severity is greater than some threshold, it calls

ExecuteCustomObject("TwilioCallMe", "555-867-5309")

The ExecuteCustomObject will execute the Groovy Script named "TwilioCallMe" and then pass in the telephone number you entered to the Groovy Script's phoneNumber parameter.

Now that you understand how the Expression Rule calls a script, let's look at the two Groovy scripts.

Groovy Scripts

The groovy script named CallMe is executed by the Expression Rule above and connects to the Twilio Server passing in a list of parameters.

When you register with Twilio, you will be given an ACCOUNT SID (apiID) and an AUTH TOKEN (apiPass). These two strings need to be in the Groovy Script below:
String apiID = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'   
String apiPass = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' 
The "Caller" parameter below is configured within the Twilio site after you register and can be found when clicking on the Phone Numbers link in the Twilio site.
You will need to add an Outgoing CallerID Number (can be your cellphone, landline or any other valid telephone number)

The "Url" POST parameter is the URL that Twilio will fetch when the call is answered. The URL we configured tells Twilio to call an Axeda REST Web Service (called Scripto) which will call a Groovy Script called "TwilioVoiceResponse". This URL needs to authenticate, so you also need to put your username and password into the URL string.

Script 1: TwilioCallMe

// Add explicit phoneNumber parameter to script
import org.apache.commons.httpclient.Credentials
import org.apache.commons.httpclient.HostConfiguration
import org.apache.commons.httpclient.HttpClient
import org.apache.commons.httpclient.UsernamePasswordCredentials
import org.apache.commons.httpclient.auth.AuthScope
import org.apache.commons.httpclient.methods.GetMethod
import org.apache.commons.httpclient.methods.PostMethod
import org.apache.commons.httpclient.NameValuePair
import com.axeda.drm.sdk.data.Alarm

String twilioHost = 'api.twilio.com'
String apiID = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'  
String apiPass = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'  
HostConfiguration hc = new HostConfiguration()
hc.setHost(twilioHost, 443, "https")
def url = "/2008-08-01/Accounts/$apiID/Calls"

def client = new HttpClient()
Credentials defaultcreds = new UsernamePasswordCredentials(apiID, apiPass)
client.getState().setCredentials(null, null, defaultcreds)

PostMethod post = new PostMethod(url);

post.addParameter 'Caller', 'XXXXXXXXXX'
post.addParameter 'Called', parameters.phoneNumber
post.addParameter 'Url', "http://dev6.axeda.com/services/v1/rest/Scripto/execute
                                   /TwilioVoiceResponse?username=UUUUU&password=PPPPP"
client.executeMethod(hc, post);
post.releaseConnection();

Script 2: TwilioVoiceResponse

The second Groovy Script "TwilioVoiceResponse" creates the message that you hear in the phone call. It uses the Platform SDK to find new alarms and puts the alarm name and asset into the message. Because this script is called through a web service, the output must be returned with a content types and XML string. The message is formatted in TwiML.

import com.axeda.drm.sdk.Context
import com.axeda.drm.sdk.data.AlarmFinder
import groovy.xml.MarkupBuilder
import com.axeda.drm.sdk.data.Alarm
import com.axeda.drm.sdk.data.AlarmState

Context ctx = Context.create()
AlarmFinder af = new AlarmFinder(ctx)
af.setState(AlarmState.STARTED)

def writer = new StringWriter()
def xml = new MarkupBuilder(writer)
List alarmList = af.findAll()

def serial = ""
def alarmname = ""
def description = ""
  
if (alarmList.size() > 0) {
  Alarm alarm = alarmList[0]
  serial = alarm.device.serialNumber
  alarmname = alarm.name
  if (alarm.description!=null) description = alarm.description
} 

def response = """
<Response>
   <Say voice='man'>This is an automated voice message from the Axeda Platform.</Say>
  <Say voice='woman'>An alarm has occurred for asset $serial. </Say>
  <Say voice='woman'>$alarmname</Say>
</Response>
"""
return ['Content-Type': 'text/xml', 'Content': response.toString()]

As you can see, we have been able to incorporate cloud based services using the Platform's rules and scriping.

With a firm knowledge of the Platform SDK, you can build Groovy Scripts that interact with many cloud services.

For more information about Expression Rules and Groovy scripting, take a look at the following links:

Keywords: