SMS and ColdFusion MX 7

				
In a recent discussion about an upcoming project, the idea of “reaching beyond the browser” came up. We wanted to provide students (our target audience) with an avenue to provide feedback in addition to the web. After our meeting we had two questions to answer: What was the best way to provide interaction to mobile devices, and what could we use in our current infrastructure that would allow us to talk to mobile devices?


The answers were SMS (Short Message Service) and ColdFusion MX 7. Thanks to the awesome Macromedia MAX conference in November, I was aware that ColdFusion MX 7 was going to include a new Event Gateway that allowed a ColdFusion application to send and receive SMS messages. My next step was to set up a sample application, so our team members could see how it would work.


I was able to find a good overview of how a CF application and a mobile device communicate using SMS here: 


http://macromedia.com/software/coldfusion/event_gateways/
What I couldn’t find was a good step-by-step CF SMS example, so I pieced together what I could find and created this one. In this tutorial we will set up a CF gateway and create a sample application that will receive SMS messages as votes for candidates and send a confirmation message to the voter.
Step 1 - Locate your sms-test.cfg file in your CF installation directory under gateway\config\.
Step 2 - Copy this file and save it in the same directory as vote.cfg or a name of your choosing.
If you open this file you will see all of the settings that your Gateway Instance will use to send and receive messages. Since this is a test application, we will use the default settings that point the Gateway Instance to IP 127.0.0.1, port 7901, and phone number 5551212. 
Step 3 - Create a blank CFC called vote.cfc and save it under your web root in a folder of your choosing. This will be the file that processes all incoming SMS messages.
Step 4 - Login to CF Administrator and make sure the SMS Test Server is running under Event Gateways and Settings.
Step 5 - Create a new Gateway Instances in the CF Administrator under Event Gateways and Gateway Instances.
Gateway ID: SMS Vote - 5551212

Gateway Type: SMS Gateway

CFC Path: web root\subfolder\vote.cfc

Configuration File: cf rootdir\gateway\config\vote.cfg

Startup Mode: Automatic
Step 6 - Start the SMS Vote - 5551212 Gateway Instance and make sure it is the only SMS Instance running.
Step 7 - Now that your Gateway is up and running we will add our SMS processing code to our vote.cfc.
First, we create our component and define our only method with the name onIncomingMessage. This is the method that the gateway will call whenever there is an incoming message. The only argument supplied by the gateway is a structure called CFEvent that contains information about the incoming message.
<cfcomponent displayname="SMS Voting Listener" hint="Process SMS messages.">
<cffunction name="onIncomingMessage" output="no">
 <cfargument name="CFEvent" type="struct" required="yes" />
Next we pull the incoming message and the sender’s phone number out of the structure.
<--- Get message data and sender number--->
<cfset voterMessage=arguments.CFEvent.data.message />
<cfset voterNumber=arguments.CFEvent.originatorID />
We will also need to create a return structure to pass back to the gateway. The command value is set to submit which will send the return message, the gatewayid is set as the source address for the message, and the destination address is set as the voter’s phone number.
<--- Set up return struct with needed arguments--->
<cfset retValue=structNew() />
<cfset retValue.command="submit" />
<cfset retValue.sourceAddress=arguments.CFEvent.gatewayid />
<cfset retValue.destAddress=voterNumber />
Next we will use a switch statement to process the incoming message. If the message is “Carrie” or “Bo” then we will insert the vote and voter’s phone number into our database. We also set the return message that thanks our user for voting. If the incoming message wasn’t a candidate’s name then we return a “Not a voting option” message.
Note: Be sure to create a database and datasource (called “SMSVotes” in this example) for this code to use.
<--- Add vote to db if incoming msg is a name and set return msg --->
<cfswitch expression="#voterMessage#">
 <cfcase value="Carrie">
<cfquery datasource="SMSVotes">
 INSERT INTO Votes(Phone, Vote)
 VALUES ('#voterNumber#', 'Carrie')
cfquery>
<cfset retValue.shortMessage="Thank you for voting for " & voterMessage />
 cfcase>
 <cfcase value="Bo">
<cfquery datasource="SMSVotes">
 INSERT INTO Votes(Phone, Vote)
 VALUES ('#voterNumber#', 'Bo')
cfquery>
<cfset retValue.shortMessage="Thank you for voting for " & voterMessage />
 cfcase>
 <cfdefaultcase>
<cfset retValue.shortMessage="Not a voting option: " & voterMessage />
 cfdefaultcase>
cfswitch>
Lastly, we return our return structure with all the information the gateway needs to send our voter a confirmation message.
<--- Send the return struct to gateway --->
<cfreturn retValue />
cffunction>
cfcomponent>
Step 8 - Now we need to test our application and to do this we will use a cell phone emulator that is installed with CF 7. Go to Start -> Programs -> Macromedia -> ColdFusion MX 7 -> SMS Client Application. This will launch a command prompt window along with a Java popup that is pre-filled with default connection information, which we will use.
Once you connect, you will see a simulated cell phone interface useful for testing purposes. You can type your message by using the keypad on the cell phone or by selecting the text box and typing with your keyboard. Try voting for Carrie, Bo, and a non-candidate to see if your application is working properly. 
That’s it! That is all you need to do to get an example SMS application up and running. As laid out in the Macromedia link above, you will need to set up an account with a SMSC (Short Message Service Center) such as AT&T, Verizon, or Sprint to actually be able to send and receive SMS messages. This provider will receive all the incoming SMS messages over their mobile network and then forward that message over TCP/IP to your ColdFusion server. After the SMSC provides you with settings for your vote.cfg file, you will be SMS enabled. 
I hope you found this tutorial useful. Now go forth and start texting!
				
								
								
			<-- End article -->