LimeSurvey API use case

The following test case scenarios are presented as a simple usage guide for the XML-RPC API.

Each scenario is based on a handful of basic actions that could scale into more complex cases.

The client is implemented in PHP and is based on the Zend XML-RPC client, mainly for maintaining simplicity.

Exceptions are not going to be checked, as this is not part of our scope.

0. Basic includes

Autoloading all Zend framework classes and instantiate the new XML-RPC client object.

require_once 'Zend/Loader/Autoloader.php';
Zend_Loader_Autoloader::getInstance();
$client = new Zend_XmlRpc_Client('http://<domain>/<limesurvey_dir>/index.php/admin/remotecontrol');

1.Create a session key

In order to use every function in the API, user must have a session key. This session key is created by the get_session_key function, which actually performs the user authentication and creates a session for the user.

$sessionkey = $client->call(‘get_session_key’, array(‘<username>’,'<password>’));
Result: string(32) "tgv7xrudi8u4jjxjhq8bspmey2z4ea87"

2.Release session key

The session key is the basic authentication token for every function in the API. After the end of the usage, user can or should release this session key. In any case this session key is only valid for a limited period of time, defined by the session_lifetime parameter in the applications config.

$result = $client->call(‘release_session_key’, $sessionkey);
Result: string(2) "OK"

The most basic usage of the Api involves the creation of a survey. There are two ways of creating a survey, either by importing the individual groups or questions, or by importing the whole structure. The first scenario will do a complete import of a survey and the following will use individual imports.

3.Import survey

The native format for the surveys is the lss. Optionaly users can use csv, or zip files.

The file used for import is sample_survey.lss

$file_string=base64_encode(file_get_contents('sample_survey.lss'));
$format = 'lss';
$sNewSurveyName = 'A new title';
$iNewID = $client->call('import_survey', array($sessionkey,$file_string,$format,$sNewSurveyName));
Result: string(6) "685351"

4.Add survey, import content

An alternate way of creating a survey involves adding the empty placeholders, which can later have groups or question.

The following scenario involves the creation of an empty survey, the import of a group, the creation of an empty group and the import of questions on the second group. By this way all import functions are clarified.

The files to be used are sample_group.lsg, question1.lsq, question2.lsq

$group_string=base64_encode(file_get_contents('sample_group.lsg'));
$q1_string=base64_encode(file_get_contents('question1.lsq'));
$q2_string=base64_encode(file_get_contents('question2.lsq'));

Add Survey

$iWishID=15;
$sSurveyTitle  = 'A simple survey';
$slanguage = 'en';
$sFormat = 'G';
$iNewID = $client->call('add_survey', array($sessionkey,
                                                $iWishID,
                                                $sSurveyTitle,
                                                $slanguage,
                                                $sFormat));

Import group

$sImportDataType='lsg';
$sNewGroupName='Identity group';
$sNewGroupDescription='This is a group that has been imported';
$iNewGid = $client->call('import_group', array($sessionkey,
                                                $iNewID,
                                                $group_string,
                                                $sImportDataType,
                                                $sNewGroupName,
                                                $sNewGroupDescription));

Add group

$sGroupTitle = 'Container';
$sGroupDescription = 'This is a group to be used as a container';
$iGid2 = $client->call('add_group', array($sessionkey,
                                                $iNewID,
                                                $sGroupTitle,
                                                $sGroupDescription));

Import question

$sImportDataType = 'lsq';
$sMandatory='Y';
$sNewQuestionTitle1='First question';
$sNewqQuestion1='Tell us your gender';
$sNewQuestionHelp1='A simple question that asks for your gender';
$iQid1 = $client->call('import_question', array($sessionkey,
      								$iNewID,
      								$iGid2, 
      								$q1_string,
      								$sImportDataType,
      								$sMandatory, 
      								$sNewQuestionTitle1,
      								$sNewqQuestion1,
      								$sNewQuestionHelp1));

Import question

$sImportDataType = 'lsq';
$sMandatory='Y';
$sNewQuestionTitle2='Second question';
$sNewqQuestion2='Tell us your age';
$sNewQuestionHelp2='A simple question that asks for your age';
$iQid2 = $client->call('import_question', array($sessionkey,
									$iNewID,
									$iGid2, 
									$q2_string,
									$sImportDataType,
									$sMandatory, 
									$sNewQuestionTitle2,
									$sNewqQuestion2,
									$sNewQuestionHelp2));

echo " Results are:\n New survey: $iNewID\n Imported Group: $iNewGid\n Added Group: $iGid2\n Imported Questions: $iQid1 - $iQid2\n ";
 Results :
 New survey: 15
 Imported Group: 154
 Added Group: 155
 Imported Questions: 1581 - 1582

5.Listing and changing Surveys

Listing the surveys a user has created is a funcamendal functionality.

This scenario is enriched with the need to see properties of a survey and change them.

$sUser = 'admin';
$list = $client->call('list_surveys', array($sessionkey,$sUser));

Result:
array(2) {
  [0]=>
  array(5) {
    ["sid"]=>
    string(6) "944833"
    ["surveyls_title"]=>
    string(22) "Customer Satisfaction "
    ["startdate"]=>
    string(19) "2012-08-09 00:00:00"
    ["expires"]=>
    string(19) "2012-08-23 00:00:00"
    ["active"]=>
    string(1) "N"
  }
  [1]=>
  array(5) {
    ["sid"]=>
    string(2) "15"
    ["surveyls_title"]=>
    string(15) "A simple survey"
    ["startdate"]=>
    NULL
    ["expires"]=>
    NULL
    ["active"]=>
    string(1) "N"
  }
}

Selecting a random Survey, we use it for getting properties

$properties  = array('template','datecreated','showwelcome','bounce_email');
$result = $client->call('get_survey_properties', array($sessionkey,$random_sid,$properties));

Result:
array(4) {
 
  ["template"]=>
  string(7) "default"
  ["datecreated"]=>
  string(10) "2012-08-29"
  ["showwelcome"]=>
  string(1) "Y"
  ["bounce_email"]=>
  NULL
}

And Changing some properties:

$new_properties = array('admin'=>'George Smith','bounce_email'=>'george@example.com', 'htmlemail'=>'N', 'invalid_property'=>'empty');
$result = $client->call('set_survey_properties', array($sessionkey,$random_sid,$new_properties));

Result:
array(3) {
  ["admin"]=>
  bool(true)
  ["bounce_email"]=>
  bool(true)
  ["htmlemail"]=>
  bool(true)
}

The same applies to properties that are part of the language settings of a survey

$properties  = array('surveyls_title','surveyls_description');
$result = $client->call('get_language_properties', array($sessionkey,$random_sid,$properties));
Result:
array(2) {
  ["surveyls_title"]=>
  string(11) "A new title"
  ["surveyls_description"]=>
  string(53) "A survey for a checking the satisfaction of customers"
}

$new_properties = array('surveyls_title'=>'Changed title','surveyls_description'=>'A new description', 'invalid_property'=>'empty');
$result = $client->call('set_language_properties', array($sessionkey,$random_sid,$new_properties));
Result:
array(2) {
  ["surveyls_title"]=>
  bool(true)
  ["surveyls_description"]=>
  bool(true)
}

6.List groups-questions

The same listing actions can be performed on groups or questions.

$sid = 15;
$list = $client->call('list_groups', array($sessionkey,$sid));
Result: 
array(2) {
  [0]=>
  array(2) {
    ["id"]=>
    array(2) {
      ["gid"]=>
      string(3) "155"
      ["language"]=>
      string(2) "en"
    }
    ["group_name"]=>
    string(9) "Container"
  }
  [1]=>
  array(2) {
    ["id"]=>
    array(2) {
      ["gid"]=>
      string(3) "154"
      ["language"]=>
      string(2) "en"
    }
    ["group_name"]=>
    string(14) "identity group"
  }
}

Selecting a random gid from the result, we request a list of questions for a specific group

$qlist = $client->call('list_questions', array($sessionkey,$sid,$random_gid));
Result:
array(2) {
  [0]=>
  array(3) {
    ["id"]=>
    array(2) {
      ["qid"]=>
      string(4) "1576"
      ["language"]=>
      string(2) "en"
    }
    ["type"]=>
    string(1) "A"
    ["question"]=>
    string(16) "Employees rating"
  }
  [1]=>
  array(3) {
    ["id"]=>
    array(2) {
      ["qid"]=>
      string(4) "1577"
      ["language"]=>
      string(2) "en"
    }
    ["type"]=>
    string(1) "T"
    ["question"]=>
    string(28) "Please give us some comments"
  }
}

7.Read - Change question

The get and set functions are available for all the models taking part in the remotecontrol.

The changing of a question is almost identical to the usage of set_survey_properties.

Bear in mind that some of the properties(like the question_id and type of question) are not allowed to be changed, so there wont be any result for them.

$properties  = array('type','title','question','language');
$result = $client->call('get_question_properties', array($sessionkey,$qid,$properties));
Result:
array(4) {
  ["type"]=>
  string(1) "T"
  ["title"]=>
  string(2) "q3"
  ["question"]=>
  string(28) "Please give us some comments"
  ["language"]=>
  string(2) "en"
}

$new_properties = array('type'=>'L','title'=>'QQ3', 'mandatory'=>'Y', 'invalid_property'=>'empty');
$result = $client->call('set_question_properties', array($sessionkey,$qid,$new_properties));
Result:
array(2) {
  ["title"]=>
  bool(true)
  ["mandatory"]=>
  bool(true)
}

8.Activate Survey -Tokens

One important functionality for a Survey is the activation, which initializes the survey for the participants.

Optionally we can request for the survey to use tokens(closed survey), so an activation of tokens is necessary.

$result = $client->call('activate_survey', array($sessionkey,$sid));
Result: ["status"] =>  string(2) "OK"

$result = $client->call('activate_tokens', array($sessionkey,$sid));
Result: ["status"] =>  string(2) "OK"

9.Add participant, list participant

A closed Survey needs persons that are going to participate.

Adding and listing participants in the token table is strightforward, provided that the ParticipantData structure is properly defined.

$aParticipantData = array(
        'user1'=>array('firstname'=>'John',
                'lastname'=>'Smith',
                'email'=>'smith@example.com',
                'language'=>'en',
                'someinvalidfield'=>'this field and data will be ignored'),
        'user2'=>array('firstname'=>'George',
                'lastname'=>'Carlin',
                'email'=>'george@example.com'),
        'user3'=>array('firstname'=>'Christopher',
                'lastname'=>'hitchens',
                'email'=>'christopher@example.com',
                'language'=>'en',
                'someinvalidfield'=>'this field and data will be ignored',
                'emailstatus'=>'ok'),
        );
$result = $client->call('add_participants', array($sessionkey,$sid,$aParticipantData));
Result:
array(3) {
  ["user1"]=>
  array(6) {
    ["firstname"]=>
    string(4) "John"
    ["lastname"]=>
    string(5) "Smith"
    ["email"]=>
    string(17) "smith@example.com"
    ["language"]=>
    string(2) "en"
    ["tid"]=>
    string(1) "1"
    ["token"]=>
    string(15) "4b2s6gvrm2beg2p"
  }
  ["user2"]=>
  array(5) {
    ["firstname"]=>
    string(6) "George"
    ["lastname"]=>
    string(6) "Carlin"
    ["email"]=>
    string(18) "george@example.com"
    ["tid"]=>
    string(1) "2"
    ["token"]=>
    string(15) "y5cz7fs2jwjn9fa"
  }
  ["user3"]=>
  array(7) {
    ["firstname"]=>
    string(11) "Christopher"
    ["lastname"]=>
    string(8) "hitchens"
    ["email"]=>
    string(23) "christopher@example.com"
    ["language"]=>
    string(2) "en"
    ["emailstatus"]=>
    string(2) "ok"
    ["tid"]=>
    string(1) "3"
    ["token"]=>
    string(15) "hikhary6gj7sxms"
  }
}

And listing the participants results:

$result = $client->call('list_participants', array($sessionkey,$sid));
Result:
array(3) {
  [0]=>
  array(3) {
    ["tid"]=>
    string(1) "1"
    ["token"]=>
    string(15) "4b2s6gvrm2beg2p"
    ["participant_info"]=>
    array(3) {
      ["firstname"]=>
      string(4) "John"
      ["lastname"]=>
      string(5) "Smith"
      ["email"]=>
      string(17) "smith@example.com"
    }
  }
  [1]=>
  array(3) {
    ["tid"]=>
    string(1) "2"
    ["token"]=>
    string(15) "y5cz7fs2jwjn9fa"
    ["participant_info"]=>
    array(3) {
      ["firstname"]=>
      string(6) "George"
      ["lastname"]=>
      string(6) "Carlin"
      ["email"]=>
      string(18) "george@example.com"
    }
  }
  [2]=>
  array(3) {
    ["tid"]=>
    string(1) "3"
    ["token"]=>
    string(15) "hikhary6gj7sxms"
    ["participant_info"]=>
    array(3) {
      ["firstname"]=>
      string(11) "Christopher"
      ["lastname"]=>
      string(8) "hitchens"
      ["email"]=>
      string(23) "christopher@example.com"
    }
  }
}

10.Invitations

In certain cases it is advisable to sent invitations and reminders to the participants of a survey.

Invitations are sent the first time, a user has to be informed, and reminders follow.

$result = $client->call('invite_participants', array($sessionkey,$sid));
Result:
array(2) {
  [3]=>
  array(3) {
    ["name"]=>
    string(20) "Christopher hitchens"
    ["email"]=>
    string(23) "christopher@example.com"
    ["status"]=>
    string(2) "OK"
  }
  ["status"]=>
  string(14) "0 left to send"
}

Reminders can have optional parameters defining the minimum days between the last reminder and the maximum reminders a participant is allowed to receive.

$result = $client->call('remind_participants', array($sessionkey,$sid));
Result:
array(2) {
  [3]=>
  array(3) {
    ["name"]=>
    string(20) "Christopher hitchens"
    ["email"]=>
    string(23) "christopher@example.com"
    ["status"]=>
    string(2) "OK"
  }
  ["status"]=>
  string(14) "0 left to send"
}

11.Export

The actual goal of the whole process is to get results from a survey

Exporting responses and statistics will provide with a base64 encoded stream of data.

(Some of the optional parameters have been ommited)

$sid = 15;
$sDocumentType = 'pdf';
$sLanguageCode='en';
$sCompletionStatus='all';
$sHeadingType='full';
$sResponseType='long';
$iFromResponseID=null;
$iToResponseID=null;
$aFields=null;
$result = $client->call('export_responses', array($sessionkey,$sid,$sDocumentType,$sLanguageCode,$sCompletionStatus,$sHeadingType,$sResponseType));

Result: A pdf file.

And the statistics
$result = $client->call('export_statistics', array($sessionkey,$sid,$sDocumentType));

Result: A pdf file.

The test scenarios we presented do not cover every function of the API, but can provide you with the necessary experience to build and test your own real life cases.