Dave's Blog

Recently we where posed this use case a faculty* here at UCT wanted to inform users that they had been offered places to study for the 2010 academic year.As each of the SMS's had to contain personalized information - their student number and the degree for which they had been accepted - the SMS user tool would not be practical as they where sending out 1500 of these. They also wanted the students to respond via SMS if they intend to take up the offer (we will cover that in part 2).

 

SO first some terminology for those who haven't used the Sakai SMS service:

SMS Task: a task is a message that can be sent to one or more users. The recipient list is expanded at processing time into individual SMS Messages that are submitted to the gateway. 

So in our case we need a script that will create an SMS task for each recipient containing the custom text.  Fortunatly the SMS service exposes its enteties via REST using the Entity Broker, simply go to /direct/ on an instalation with the SMS service installed and you will see REST endpoints for sms-taks and sms-account. I have chosen to do this in php, but it could eaqualy easily done in perl, python or any number of other scripting languages.The full script can be found here.

 So the first thing we need is a function that will submit the values to the REST using http POST and be able to perform basic authentification. This is easily done with php curl:

function post_it($datastream, $url) {
	global $username, $password;

// init curl handle

  $ch = curl_init($url) or die("couldn't init curl");
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_VERBOSE, 0);
      curl_setopt($ch, CURLOPT_HEADER, 0);
      curl_setopt($ch, CURLOPT_FOLLOWLOCATION,1);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $datastream);
      curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, false);
      curl_setopt($ch, CURLOPT_SSL_VERIFYHOST,  2);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
      // this line makes it work under https
      curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,0);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
      print "loging in as $username \n";
	  // perform post
	  $rr=curl_exec($ch);
	  curl_close($ch);
	  
	      #echo $rr;
	      if ($rr) {
		return $rr;
	      } else {
		echo "<br>error: ".curl_errno($ch)."---".curl_error($ch)."<br>";
		return $rr;
	      }

} 

 

This is generic code that could be used for any number of operations. It basialy expects an array of the form values to post, keyed by the form filed id, the url to post to and expects global variables containing the username and password its going to use.  The next part is trivial, we need t open a csv file and use the values in it to populat the message and then send the message to the rest endpoint. I'll asume your familiar with php file options and jump to the meaty part. I'll just pause to not tha the getcsv method on the filehandle will save you a couple of lines of code. Ok so the message we want to send is:

$message="Student No.$campusId: UCT Commerce has made you an offer for $degreeCode for 2010. Sms the words: offer COM $campusId accept OR decline to $return_number";

$return_number is the same for all recipients so we needn't get it from the SMS. So we need $campusId and $degreeCode as well as the students modile number. Once populated it should look something like:

Student No.HRWDAV004: UCT Commerce has made you an offer for Bcom for 2010. Sms the words: offer COM HRWDAV004 accept OR decline to 00000

Once we can build that we need to populate our required form fields:

    $data["attemptCount"]=0;
    $data["dateToSend"]=$dateToSend;
    print "Date to send ".$data["dateToSend"]."\n";
    $data["deliveryMobileNumbersSet"] = $number;
    $data["groupSizeEstimate"]=1;
    $data["messageBody"]=$message;
    $data["messageTypeId"]=0;
    $data["sakaiSiteId"]=$siteId;
    $data["sakaiToolId"]="sakai.sms.user";
    $data["senderUserId"]="dhorwitz";
    $data["senderUserName"]="01302922";
    $data["smsAccountId"]=$accountId;
    $data["statusCode"]="P";
    $data["creditEstimate"]="1";
 

Most fields are self explanetory, however dateToSend can be ommited if you want the messages sent imidiatly. Once you've done that all that remains is to post the form:

$ret = post_it($data,$url);
print "$ret \n";

if (!is_numeric($ret)) die("Non numeric response received\n");
 

The return value is the id of the newly created task so a non numeric response indicates that something went wrong. Next blog how to handle responses!

*In South African universities a faculty is an organisational unit, larger than a department, smaller then the university. More or less corresponds to the term school in US higher ed.

Topic

Text

Your name

Your email address (if any)

Your personal page (if any)

Please type what you see in the image in the above block