RemoteControl 2 API
From LimeSurvey Manual
Introduction
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.
LSRC2 makes it possible for developers to control specific functionality of Limesurvey from any other application, without being restricted to PHP as a programming language.
The following features are planned:
- start a predefined survey (change titles and things)
- add predefined groups or questions
- activate the survey, restrict it to start and endtime
- make it closed,
- add participant data/tokens when you need them
- return the unused tokens to the main application
- get a fieldmap for a survey,
- invite or remind the participants of your survey
...and much more
Requirements
- libXML installed
Setup
How to configure LSRC2
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to Global settings, choose the tab 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.
Security
LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.
How to use LSRC2
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol
LSRC2 fully complies to the XML-RPC specification and JSON-RPC specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.
LSRC2 offers the following functions:
get_session_key
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.
Parameters: username (string), password (string)
Returns:
- On success: A session key (string)
- On failure: Error Code 1
release_session_key
Using this function you can close a previously opened XML-RPC/JSON-RPC session.
Parameters: session key (string)
Returns:
- Always: 'OK' (string)
get_site_settings
Function to provide with site settings only to administrators
Parameters:
sSessionKey (string) The session key
sSetttingName (string) - Name of the setting to get
Returns:
- On success: (string) Setting
- On failure: (string) Error message
add_survey
RPC Routine to add an empty survey with minimum details
Parameters:
sSessionKey (string) Auth credentials
iSurveyID (int), The wish id of the Survey to add
sSurveyTitle (string), Title of the new Survey
sSurveyLanguage (string), Default language of the Survey
sformat (string), Question appearance format (S|G|A)
Returns:
- On success: (int) $iNewSurveyID
- On failure: (array) Failure status
- Invalid session key
- No permission
- Faulty parameters
- Creation Failed
delete_survey
RPC Routine to Delete a survey
Parameters:
sSessionKey (string), Auth credentials
iSurveyID (int), The Survey to delete
Returns:
- On success: Status =>OK (array)
- On failure: (array) Failure status
- Invalid session key
- No permission
import_survey
RPC Routine to import a survey from lss,csv,xls or survey zip archive.
Parameters:
sSessionKey (string) Auth credentials
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive
sImportDataType (string), The format of the import file (lss,csv,xls or zip)
sNewSurveyName (string), The optional new name of the survey (base language)
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead
Returns:
- On success: (int) $iNewSurveyID
- On failure: (array) Failure status
- Invalid session key
- No permission
- Import error
get_survey_properties
RPC Routine to get properties of a survey
Parameters:
sSessionKey (string) Auth credentials
iSurveyID (integer) - ID of the survey
aSurveySettings (array), An array with the properties to return
Returns:
- On success: (string) the requested value
- On failure: (array) Failure status
- Invalid survey ID
- Invalid session key
- No permission
- No valid Data
Available properties:
| sid | savetimings | allowprev | tokenanswerspersistence | showgroupinfo | showwelcome |
| owner_id | template | printanswers | assessments | shownoanswer | showprogress |
| admin | language | ipaddr | usecaptcha | showqnumcode | allowjumps |
| active | additional_languages | refurl | usetokens | bouncetime | navigationdelay |
| expires | datestamp | datecreated | bounce_email | bounceprocessing | nokeyboard |
| startdate | usecookie | publicstatistics | attributedescriptions | bounceaccounttype | alloweditaftercompletion |
| adminemail | allowregister | publicgraphs | emailresponseto | bounceaccounthost | googleanalyticsstyle |
| anonymized | allowsave | listpublic | emailnotificationto | bounceaccountpass | googleanalyticsapikey |
| faxto | autonumber_start | htmlemail | tokenlength | bounceaccountencryption | |
| format | autoredirect | sendconfirmation | showxquestions | bounceaccountuser |
set_survey_properties
RPC Routine to set properties of a survey
Parameters:
sSessionKey (string) Auth credentials
iSurveyID (integer) - ID of the survey
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set
Returns:
- On success: (array) The result of the change for each property
- On failure: (array) Failure status
- Invalid survey ID
- Invalid session key
- No permission
- No valid Data
Available properties:
Properties available for changing are all those defined in get_survey_properties with the following exceptions
| properties not allowed to be modified | Properties not allowed to be modified when survey active |
| sid | anonymized |
| language | datestamp |
| additional_languages | savetimings |
| active | ipaddr |
| refurl | |
list_surveys
RPC Routine to list the ids and info of surveys belonging to a user.
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)
* Else only the syrveys belonging to the user requesting will be shown.
Parameters:
sSessionKey (string) Auth credentials
sUser (string) - The users surveys to list
Returns:
- On success: (array) The result of the change for each property
- On failure: (array) Failure status
- Invalid user
- Invalid session key
- No permission
- No surveys found
activate_survey
RPC Routine that launches a newly created survey (sets active -available for users)
Parameters:
sSessionKey (string) Auth credentials
SurveyID (integer) - ID of the survey
Returns
- On success: (array) The result of the activation
- On failure: (array) Failure status
- Invalid Survey ID
- Activation Error
- Invalid session key
- No permission
export_statistics
RPC routine to export statistics of a survey to a user.
Parameters:
sSessionKey (string) Auth credentials
SurveyID (integer) - ID of the survey
docType (string) - Type of document to generate
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)
graph (string) - Optional parameter to enable graphs (0|1)
Returns
- On success: (string) Base64 encoded string with the statistics file
- On failure: (array) Failure status
- Invalid Survey ID
- Invalid session key
- No permission
get_summary
RPC routine to get survey summary, regarding token usage and survey participation.
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - ID of the survey
sStatname (string) - The statistic to return
Returns
- On success: (string) Base64 encoded string with the statistics file
- On failure: (array) Failure status
- No available data
- No such property
- Invalid session key
- No permission
Available statistics:
| Survey stats | Token stats |
| completed_responses | token_count |
| incomplete_responses | token_invalid |
| full_responses | tokens_sent |
| token_opted_out | |
| token_completed | |
add_language
RPC Routine to add a language to an existing survey
Parameters:
session key (string) - The session key
SurveyID (integer) - ID of the survey
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.
Return values:
- On success: (array) status=>OK
- On failure: (array) Any other status
- Invalid survey ID
- Invalid language
- Error
- Invalid session key
- No permission
delete_survey_language
RPC Routine to delete a language of an existing survey
Parameters:
session key (string) The session key
SurveyID (integer) - ID of the survey
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.
Return values:
- On success: (array) status=>OK
- On failure: (array) Any other status
- Invalid survey ID
- Invalid language
- Cannot remove base language
- Error
- No permission
- Invalid session key
get_language_properties
RPC Routine to get survey language properties
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - ID of the survey
aSurveyLocaleSettings (array) - An array with the properties to return
slang (string) - The language to use
Returns:
- On success: (string) the requested value
- On failure: (array) Failure status
- Invalid survey ID
- Invalid session key
- No permission
- No valid Data
Available parameters:
| surveyls_survey_id | surveyls_url | surveyls_email_register_subj | email_admin_notification_subj |
| surveyls_language | surveyls_urldescription | surveyls_email_register | email_admin_notification |
| surveyls_title | surveyls_email_invite_subj | surveyls_email_confirm_subj | email_admin_responses_subj |
| surveyls_description | surveyls_email_invite | surveyls_email_confirm | email_admin_responses |
| surveyls_welcometext | surveyls_email_remind_subj | surveyls_dateformat | surveyls_numberformat |
| surveyls_endtext | surveyls_email_remind | surveyls_attributecaptions |
set_language_properties
RPC Routine to set survey language properties
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - ID of the survey
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.
sLanguage (string) - The language to use
Returns:
- On success: (string) Result for each parameter set
- On failure: (array) Failure status
- Invalid survey ID
- Invalid language
- Invalid session key
- No permission
- No valid Data
Allowed Parameters:
All those defined in get-language_properties except:
- surveyls_language
- surveyls_survey_id
add_group
RPC Routine to add an empty group with minimum details.
* Used as a placeholder for importing questions.
* Returns the groupid of the created group.
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - ID of the surveythat the group will be added
sGroupTitle (string) - Name of the new group
sGroupDescription (string) - Optional description of the group
Returns:
- On success: (int) The ID of the new group
- On failure: (array) Failure status
- Invalid survey ID
- Error:Survey is active and not editable
- Invalid session key
- No permission
- Creation Failed
delete_group
RPC Routine to delete a group of a survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - ID of the survey that the group belongs
sGroupID (int) - Id of the group to delete
Returns:
- On success: (int) The ID of the deleted group
- On failure: (array) Failure status
- Invalid Survey ID
- Invalid Group ID
- Error:Survey is active and not editable
- Invalid session key
- No permission
- Group deletion failed
import_group
RPC Routine to import a group - imports lsg,csv
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - The id of the survey that the group will belong
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)
sNewGroupName (string) - Optional new name for the group
sNewGroupDescription (string) - Optional new description for the group
Returns:
- On success: (int) The ID of the new group
- On failure: (array) Failure status
- Invalid survey ID
- Error:Survey is active and not editable
- Invalid extension
- Error: Invalid LimeSurvey group structure XML
- Invalid session key
- No permission
- Import Error
get_group_properties
RPC Routine to return properties of a group of a survey
Parameters:
sSessionKey (string) - Auth credentials
iGroupID (integer) - The id of the group to get properties of
aGroupSettings (array) - Array containing the properties to request.
Returns:
- On success: (array) The requested properties
- On failure: (array) Failure status
- Error: Invalid group ID
- No valid Data
- Invalid session key
- No permission
Available properties:
| gid | description |
| sid | language |
| group_name | randomization_group |
| group_order | grelevance |
set_group_properties
RPC Routine to set properties of a group of a survey
Parameters:
sSessionKey (string) - Auth credentials
iGroupID (integer) - The id of the group to set properties to
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.
Returns:
- On success: (array) The result of each set action
- On failure: (array) Failure status
- Error: Invalid group ID
- No valid Data
- Group with dependencies - Order cannot be changed
- Invalid session key
- No permission
Available properties:
| description | |
| language | |
| group_name | randomization_group |
| group_order | grelevance |
list_groups
RPC Routine to return the ids and info of groups belonging to survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (integer) - The id of the survey to get groups of
Returns:
- On success: (array) The list of the groups
- On failure: (array) Failure status
- Invalid Survey ID
- No groups found
- Invalid session key
- No permission
delete_question
RPC Routine to delete a question of a survey
Parameters:
sSessionKey (string) Auth credentials
iQuestionID (int) Id of the question to delete
Returns:
- On success: (int)id of the deleted Question
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid question ID
- Survey is active and not editable
- Cannot delete Question. Others rely on this question
- Error
import_question
RPC Routine to import a question - imports lsq,csv
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey that the new questions belongs
iGroupID (int) - Id of the group that the new questions belongs
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv
sImportDataType (string) - Format of the input stream (lsq,csv)
sMandatory (string) - Optional Mandatory question option (default to No)
sNewQuestionTitle (string) - Optional new title for the question
sNewqQuestion (string) - An optional new question
sNewQuestionHelp (string) - An optional new question help text
Returns:
- On success: (int) Id of the new Question
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- Invalid group ID
- Survey is active and not editable
- Invalid extension
- Invalid LimeSurvey question structure XML
get_question_properties
RPC Routine to return properties of a question of a survey
Parameters:
sSessionKey (string) Auth credentials
iQuestionID (int) Id of the question to get properties of
aQuestionSettings (array) The properties to get
sLanguage (string) Optional parameter language for multilingual questions
Returns:
- On success: (array) The requested properties
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid questionid
- Invalid language
- No valid Data
Available Properties:
| gid | type | help | language |
| parent_qid | title | other | scale_id |
| sid | question | mandatory | same_default |
| gid | preg | question_order | relevance |
set_question_properties
RPC Routine to set question properties
Parameters:
sSessionKey (string) - Auth credentials
iQuestionID (int) - Id of the question to get properties of
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question
sLanguage (string) - Optional parameter language for multilingual questions
Returns:
- On success: (array) The resilt of the set of each property
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid questionid
- Invalid language
- Questions with dependencies - Order cannot be changed
- No valid Data
Available Properties:
| help | ||
| title | other | scale_id |
| question | mandatory | same_default |
| preg | question_order | relevance |
list_questions
RPC Routine to return the ids and info of questions of a survey/group.
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to get questions of
iGroupID (int) - Id of the group to get questions of
sLanguage (string) - Optional parameter language for multilingual questions
Returns:
- On success: (array) The list of the questions
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid questionid
- Invalid language
- Invalid survey ID
- Missmatch in surveyid and groupid
- No questions found
activate_tokens
Activate tokens
Parameters:
session key (string) The session key
surveyid (string) The survey ID
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs
Returns:
- On success: (array) status OK
- On failure: (array) Any other status
add_participants
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically create
Parameters:
- session key (string) - The session key
- survey ID (string) - The survey id
- participant data (array) - 2-dimensional array/structure containing your participants data
- createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten
Returns:
- On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
delete_participants
RPC Routine to delete multiple participants of a Survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to get questions of
aTokenIDs (array) - IId of the tokens/participants to delete
Returns:
- On success: (array) Array of deletion status for each participant
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
get_participant_properties
RPC Routine to return settings of a token/participant of a survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the Survey to get token properties
iTokenID (int) - Id of the participant to check
aTokenProperties (array) - The properties to get
Returns:
- On success: (array) Array of requested values
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
- Invalid tokenid
- No valid Data
Available Parameters:
| tid | token | completed |
| participant_id | language | usesleft |
| firstname | blacklisted | validfrom |
| lastname | sent | validuntil |
| remindersent | mpid | |
| emailstatus | remindercount |
set_participant_properties
RPC Routine to set properties of a survey participant/token
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the Survey to set token properties
iTokenID (int) - Id of the participant to alter
aTokenData (array) - Key - value pair of the properties to set
Returns:
- On success: (array) Array of results of changing properties
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
- Invalid tokenid
- No valid Data
Available Parameters:
| token | completed | |
| participant_id | language | usesleft |
| firstname | blacklisted | validfrom |
| lastname | sent | validuntil |
| remindersent | mpid | |
| emailstatus | remindercount |
list_participants
RPC Routine to return the ids and info of token/participants of a survey.
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to list participants
iStart (int) - Start id of the token list
iLimit (int) - Number of participants to return
bUnused (bool) - If you want unused tokensm, set true
Returns:
- On success: (array) Array of Participants info
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
- No Tokens found
activate_tokens
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to list participants
aAttributeFields (array) - An array of integer describing any additional attribute fields
Returns:
- On success: (array) Status OK
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- Token table could not be created
invite_participants
RPC Routine to invite participants in a survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to send invitation to participants
Returns:
- On success: (array) Array of result of each email send action and count of invitations left to send
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
- No candidate tokens
remind_participants
RPC Routine to send reminder for participants in a survey
Parameters:
sSessionKey (string) - Auth credentials
iSurveyID (int) - Id of the survey to send invitation to participants
iMinDaysBetween (int) - Optional parameter days from last reminder
iMaxReminders (int) - Optional parameter Maximum reminders count
Returns:
- On success: (array) Array of result of each email send action and count of invitations left to send
- On failure: (array) Failure status
- Invalid session key
- No permission
- Invalid survey ID
- No token table
- No candidate tokens
add_response
Using this function you can add new responses to your survey response table.
Parameters:
- sSessionKey (string) - The session key
- iSurveyID (integer) - The survey id
- aResponseData (array) - array/structure containing your response data
Returns:
- On success: response_id (integer) - Returns the id of the inserted survey response
- On failure: (array) with error description
export_responses
Export response data to pdf,csv,xls,doc
Parameters:
sSessionKey (string) - Auth credentials
SurveyID (int) - Id of the Survey
DocumentType (string) - pdf,csv,xls,doc
sLanguageCode (string) - The language to be used
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'
FromResponseID (int) - Optional start number of response
ToResponseID (int) - Optional end number of responses
Return:
On success: Requested file as base 64-encoded string.
On failure: Array with error information
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.
Testing
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.
The test assumes that you still are using the standard user 'admin' with password 'password'.
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().
PHP Example
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from | jsonrpcphp.org
<?php
require_once 'jsonRPCClient.php';
define( 'LS_BASEURL', 'http://localhost/limesurvey/');
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );
// the survey to process
$survey_id=374699;
// instanciate a new client
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );
// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );
// receive all
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );
// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );
?>
Changes
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey
2.0b Added function add_participants
2.0RC5 Added import_survey, activate_survey, activate_tokens