Sample Webservice Source Code

Description

The SOAP Webservice question type allows you to perform logic on survey responses while the respondent is taking the survey, and possibly integrate surveys with your own business processes or databases.

For a walk-through of how to use this question type, see Section 2.18 of the Survey Design tutorial.

When adding this question, the default value is a WSDL for a sample webservice that is compatible with our SOAP webservice type. This sample webservice only performs a simple logic test on the data receives: it responds with "accepted" if any of the responses provided were "yes"; otherwise it responds with "rejected". If the webservice responds with "accepted", and is called again during the course of a survey with answers that would warrant another "accepted" response, the webservice will instead say "accepted again"—this is to demonstrate that a webservice could possibly retain session state over multiple requests while taking a survey. (See the UPDATE note below for details.) The webservice you build can do possibly much more—store data into a database, retrieve data from a file, or send it via an email; it is completely up to how you build your SOAP service.

You should provide a WSDL for your SOAP service that specifies only one function named plumEval. This function will receive two arrays of strings: one with the text of each question on the current page, and the other with all the answers received on the current page. These arrays will be indexed in the same fashion, where each array's elements will be ordered so that the questions correspond with the answers. This function should return a string, which will be saved as the response for the question calling this webservice.

To ensure compatibility with the survey tool, your webservice function signature should read as follows:

plumEval($question_texts, $answers)

We are providing the code for our sample webservice so that you can have a reference implementation to build your own. If you are using PHP (version >5), the following code could easily serve as a template for your own webservice; just replace the contents of the plumEval() function with your own code. For other languages/architectures, the information on the contents of a compatible SOAP request and reply may be useful.

UPDATE (4/17/09): Our SOAP clients will now accept and store cookies you provide with HTTP Set-Cookie: headers. These cookies will be resent to you as specified by the cookie's domain and path. You can use the cookie capability to implement sessions, for instance if you want to associate data from requests across multiple pages. Cookies will be retained over the course of each individual's survey response session, whether over the phone or the web, and discarded upon completion/hangup. Each individual respondent will have their own cookie jar.

UPDATE (7/01/09): Our SOAP client will by default send along a cookie called either ani or ip with the ANI or IP address of the current respondent, respectively. You are free to override this cookie by sending back HTTP Set-Cookie: headers that overwrite or delete it. Additionally, an advanced question option for Advanced Skip Logic has been added, the details of which can be found in Section 6.4 of the Survey Design Tutorial.

UPDATE (1/25/11): We now have a SOAP Web Service tester that you can use to validate your web service against. For a link to this SOAP web service tester, see here.

Sample Webservice Source Code

sample-webservice.php:

<?php
/*************
* PLUM SURVEY SAMPLE WEBSERVICE
* This webservice demonstrates how to make a SOAP service for use with a
* 'SOAP webservice' question in a survey.
* (c) 2008 Plum Voice
*************/
$NAMESPACE = "http://survey.plumvoice.com";
$DEBUG = true;
include_once('../lib/WSDL_Gen.php');
$WS_DOC_CSS = "css/ws_doc.css";
$DESCRIPTION = "An example of a webservice that could be used by a \"SOAP webservice\" question in a survey.";
$LOGFILE = @fopen("/var/tmp/surveysamplewebservice.log", "a+");
function debuglog($str) {
global $LOGFILE, $DEBUG;
if ($LOGFILE && $DEBUG) {
fwrite($LOGFILE, $str);
}
}
class SampleWebservice extends Services_Webservice {
/**
* The WSDL that you use should specify only one function named "plumEval".
* This function will receive two arrays of strings: one with the
* text of each question, and the other with all the answers received
* on the current page. These arrays will be indexed in the same fashion,
* e.g., each array's elements will be ordered so that the questions
* correspond with the answers. This function should return a string,
* which will be saved as the response for the question calling this
* webservice. If there is a choice with skip logic that corresponds to
* this answer, it will be followed. ...
*
* This sample webservice returns "accepted" if any of the submitted answers
* were "yes", and "rejected" otherwise. To demonstrate that session
* cookies can be set and checked, after the webservice has "accepted" once,
* it will return "accepted again" for every future call within the same
* survey where any of the submitted answers were "yes".
*
* @param string[] $question_texts
* @param string[] $answers
* @return string
**/
function plumEval($question_texts, $answers) {
foreach ($answers as $answer) {
if ($answer == 'yes') {
if ($_SESSION['accepted-once']=='yes') {
return 'accepted again';
}
$_SESSION['accepted-once']='yes';
return 'accepted';
}
}
return 'rejected';
}
}
$myService = new SampleWebservice($NAMESPACE, $DESCRIPTION, array('uri'=>$NAMESPACE, 'encoding'=>SOAP_ENCODED));
session_start();
$myService->handle();
if ($LOGFILE) {
fclose($LOGFILE);
}