Revision as of 12:55, 18 March 2015

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 version 1 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 a lot of functions. Please check the automatically generated API Documentation. LSRC2 offers the following functions:

Sessions

get_session_key

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

function get_session_key(string $username, string $password)

Return on success: (string) session key.

Return on error: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

release_session_key

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

function release_session_key(string $sSessionKey)

Parameter	Description
sSessionKey	Auth credentials

Return: Always 'OK' (string)

Site

get_site_settings

Function to query site settings. Can only be used by administrators.

function get_site_settings( string $sSessionKey, string $sSetttingName)

Parameter	Description
sSessionKey	Auth credentials
sSetttingName	Name of the setting to get

Return on success: (string) Setting's value

Return on failure: (string) Error message

Users

list_users

Function to return the ids and info of users.

function list_users(string $sSessionKey)

Parameter	Description
sSessionKey	Super-admin's auth credentials.

Return on success: (array) The list of users

Return on failure: (array) Failure status:

No users found
Invalid session key
No permission (super admin is required)

Surveys

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

function get_survey_properties( string $sSessionKey, int $iSurveyID, array $aSurveySettings)

Parameter	Description
sSessionKey	Auth credentials
iSurveyID	ID of the survey
aSurveySettings	An array of strings containing the properties to return

Return on success: (string) The requested value

Return on failure: (array) Failure status : Invalid survey ID, Invalid session key, No permission, No valid Data

Available properties
active	autonumber_start	emailnotificationto	nokeyboard	showwelcome
additional_languages	autoredirect	emailresponseto	owner_id	showxquestions
admin	bounce_email	expires	printanswers	sid
adminemail	bounceaccountencryption	faxto	publicgraphs	startdate
alloweditaftercompletion	bounceaccounthost	format	publicstatistics	template
allowjumps	bounceaccountpass	googleanalyticsapikey	refurl	tokenanswerspersistence
allowprev	bounceaccounttype	googleanalyticsstyle	savetimings	tokenlength
allowregister	bounceaccountuser	htmlemail	sendconfirmation	usecaptcha
allowsave	bounceprocessing	ipaddr	showgroupinfo	usecookie
anonymized	bouncetime	language	shownoanswer	usetokens
assessments	datecreated	listpublic	showprogress
attributedescriptions	datestamp	navigationdelay	showqnumcode

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

Allways
- sid
- language
- additional_languages
- active
When survey active
- anonymized
- datestamp
- savetimings
- 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) Survey's properties
On failure: (array) Failure status
- Invalid user
- Invalid session key
- No permission
- No surveys found

Survey's properties:

property	type
sid	integer
surveyls_title	string
startdate	date
expires	date
active	y/n

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 or 'all' to get an array of all statistics

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	token_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

Groups of Questions

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

Questions

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
subquestions	attributes	attributes_lang	answeroptions

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) - Optional 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

Tokens and Participants

Token Properties

The following properties of tokens can be read or set:

Property	Type	Description
tid	int	Token ID; read-only property
completed
participant_id
language	string
usesleft
firstname	String	Participant's first name
lastname	String	Participant's last name
email	String	Participant's e-mail address
blacklisted
validfrom
sent
validuntil
remindersent
mpid
emailstatus
remindercount

activate_tokens

RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added

public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)

Parameter	Type	Description
sSessionKey	string	Auth credentials
iSurveyID	int	Id of the Survey
additional_attributes	array of integer	Any additional attribute fields to create. Just give the attribute IDs.

Return on success: (array) Status OK

Return on failure: (array) Failure status

Invalid session key
No permission
Invalid survey ID
Token table could not be created

add_participants

Using this function you can add new entries to your token table. You can also set if for these new entries a unique token key is automatically created. Please note that this function does not check for duplicate content in any of the fields, except for token keys created by the function itself.

public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)

Parameter	Type	Description
$sSessionKey	string	Auth credentials
$iSurveyID	int	Id of the Survey
$participantData	(array)	2-dimensional array/structure containing your participants data. Example: [ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]
$createTokenKey	boolean	Set this to true if you want a token key created automatically for each entry - if your participant data already included a [token] field it will be overwritten

Return: array(struct) On success: Structure containing your participants data plus the token ID and (if applicable) the new token. Example:

[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]

Return: string 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. All properties defined in #Token Properties can be read.

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

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. All writeable properties defined in #Token Properties can be written.

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

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
  aAttributes(bool|array) An array of extended attributes that can be requested, besides the default ones (default value to false)

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

Note:

If you provide the iLimit parameter it is required to provide the iStart parameter.

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

Responses

add_response

public function add_response($sSessionKey, $iSurveyID, $aResponseData)

RPC Routine to add a response to the survey responses collection.

Return: int|array On success: Returns the id of the inserted survey response. On failure array with error information

Parameter	Type	Description
$sSessionKey	string	Auth credentials
$iSurveyID	int	Id of the Survey
$aResponseData	array	The actual response

export_responses

public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
   $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)

RPC Routine to export responses. Returns the requested data in the specified format as base64 encoded string.

Return: array|string On success: Requested data in the specified format 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.

Note: Starting with version 2.0.5 the $iFromResponseID and $iToResponseID parameters refer to the minimum and maximum id's; prior to this version the parameters refered to the record's offset in the table

Parameter	Type	Description
$sSessionKey	string	Auth credentials
$iSurveyID	int	Id of the Survey
$sDocumentType	string	pdf,csv,xls,doc,json
$sLanguageCode	string	The language to be used
$sCompletionStatus	string	Optional 'complete','incomplete' or 'all' - defaults to 'all'
$sHeadingType	string	'code','full' or 'abbreviated' Optional defaults to 'code'
$sResponseType	string	'short' or 'long' Optional defaults to 'short'
$iFromResponseID	integer	Optional
$iToResponseID	integer	Optional
$aFields	array	Optional Selected fields

export_responses_by_token

public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
   $sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)

Export responses data of specific token. Returns the requested file as base64 encoded string.

Return: array|string On success: Requested file as base 64-encoded string. On failure array with error information

Parameter	Type	Description
$sSessionKey	string	Auth credentials
$iSurveyID	int	Id of the Survey
$sDocumentType	string	pdf,csv,xls,doc,json
$sToken	string	The token for which responses needed
$sLanguageCode	string	The language to be used
$sCompletionStatus	string	Optional 'complete','incomplete' or 'all' - defaults to 'all'
$sHeadingType	string	'code','full' or 'abbreviated' Optional defaults to 'code'
$sResponseType	string	'short' or 'long' Optional defaults to 'short'
$aFields	array	Optional Selected fields

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().

Ruby Example

There are some cool things that you can use with the RemoteControl2 API and this is an example of a production use of this. Basically, I, (kobaltz in the forums) have a third party site that I built that controls the users and level of access of each company and their users. From within this site, I have a daemon that will generate participants of the appropriate survey twice an hour. This will use LimeSurvey's Mail Function to send the end user a link to the survey. Administrators of the third party site will get statistical data of the end user filling out the survey as well as a link to review the surveys completed using the same template that the user used to fill it out. Reducing duplicate entry of data made possible with the RemoteControl2 API.

Load Requirements and Declare Values

You will first need to require the dependencies needed to establish communication with the API. Also, note that there is a username and password field that requires to be stored in plain text. I have a separate API User within my LimeSurvey to handle these calls.

#!/usr/bin/env ruby

require 'net/https'
require 'uri'
require 'json'

username = "api_user"
password = "api_user"

Module

The below code is used to define the module LimeSurvey. Within this module is an API class. We will use this to create an instance of this module and then call on the API call wherever needed.

module LimeSurvey
  class API
    def initialize(service_url)
      @uri = URI.parse(service_url)
    end
   
    def method_missing(name, *args)
      post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json
      resp = JSON.parse( http_post_request(post_body) )
      raise JSONRPCError, resp['error'] if resp['error']
      resp['result']
    end
   
    def http_post_request(post_body)
      http    = Net::HTTP.new(@uri.host, @uri.port)
      request = Net::HTTP::Post.new(@uri.request_uri)
      request.content_type = 'application/json'
      request.body = post_body
      http.request(request).body
    end
  end

  class JSONRPCError < RuntimeError; end
end

API Call

This code is used to create the instance of the LimeSurvey::API module and class. You will want to change the URL to that of your RemoteControl2 URL.

survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')

Examples

This example takes the above code and puts it into play. I create a new session with the RemoteControl2 API and store the session in the variable session_key. You will want to change the ID numbers to the appropriate Survey ID in the examples.

system("cls")
session_key = survey.get_session_key(username,password)
puts "Session Key: #{session_key}"
puts "\n"


response = survey.get_survey_properties(session_key, "863224", ["owner_id"])
puts "Properties:  #{response}"
puts "\n"

response = survey.list_surveys(sSessionKey: session_key, sUser: "dkimura")
puts "Survey List:  #{response}"
puts "\n"

response = survey.add_participants(
    session_key, 
    "863224",
    [email:"james.bond@example.com",lastname:"Bond",firstname:"James"]
  )
puts "Add Participant:  #{response}"
puts "\n"

response = survey.invite_participants(
    session_key, 
    "863224"
  )
puts "Invite Participant:  #{response}"

response = survey.release_session_key(session_key)
puts "Release Session: #{response}"

# Grabs a Survey's list of participants and parses through them
# The response is in an array format.
# Each response within the array is in JSON format (How the survey is configured with RemoteControl2)
# Convert the participant response to JSON and then display the token.
response = survey.list_participants(session_key, "593987")
puts "\n"
response_participants = []
response.each do |part|
	resps = JSON.parse(part.to_json)
	puts "Participant: #{resps['token']}"
	puts "\n"
end

Example Return

From the above example, here is the return that I receive. Some of the items are returned as a hash and some items returned as an array of hashes.

Session Key: piadscbc94vyanxwkdy8f3xii4av2b2w

Properties:  {"owner_id"=>"1"}

Survey List:  [{"sid"=>"863224", "surveyls_title"=>"Statement of Work v0.12", "startdate"=>nil, "expires"=>nil, "active"=>"Y"}]

Add Participant:  [{"email"=>"james.bond@example.com", "lastname"=>"Bond", "firstname"=>"James", "tid"=>"7", "token"=>"pt5ztzxndibkz4j"}]

Invite Participant:  {"7"=>{"name"=>"James Bond", "email"=>"james.bond@example.com", "status"=>"OK"}, "status"=>"0 left to send"}

Participant: p7m5zmh38wi9mbk
Participant: nssu6ne6ii9wva9
Participant: r9kr2sahn7tfsv9
Participant: a28ci2z9m7ynfgg
Participant: 4ytt5axg9ebdazh
Participant: wswjv2t5v7vh4p7
Participant: fqvxeckgh6vgy3e
Participant: n5p2vfnh7dwx699
Participant: ycsmigup9pagm6z
Participant: 33ztf4g74k2kvx4

Release Session: OK

PHP Example

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the jsonrpcphp Github repository. The library can also get included by composer calling

composer require weberhofer/jsonrpcphp

or by inclusion of the following lines in your composer.json file:

{
    "require": {
        "weberhofer/jsonrpcphp": "2.1.0"
    }
}

This is a example how to connect to limesurvey:

<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'http://localhost/limesurvey/');  // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instanciate a new client
$myJSONRPCClient = new \org\jsonrpcphp\jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

JAVA example

To decode and code your json calls you can use the library gson as you can see in the following example:

import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {
	
    public static String parse(String jsonLine) {
	 JsonElement jelement = new JsonParser().parse(jsonLine);
	 JsonObject  jobject = jelement.getAsJsonObject();
	 String result = jobject.get("result").toString();
	 return result;
	}
	
	
    public static void main(String[] args) throws UnsupportedEncodingException {
      DefaultHttpClient client = new DefaultHttpClient();          
         
      HttpPost post = new HttpPost("http://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
      post.setHeader("Content-type", "application/json");
      post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": {\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\" }, \"id\": 1}"));
      try {
        HttpResponse response = client.execute(post);
        if(response.getStatusLine().getStatusCode() == 200){
            HttpEntity entity = response.getEntity();
            String sessionKey = parse(EntityUtils.toString(entity));
            post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": {\"sSessionKey \": "+sessionKey+", \"iSurveyID \": \"ID_SURVEY\" }, \"id\": 1}"));
            response = client.execute(post);
            if(response.getStatusLine().getStatusCode() == 200){
                entity = response.getEntity();
                System.out.println(EntityUtils.toString(entity));
                }
           }
       
       
      } catch (IOException e) {
        e.printStackTrace();
      }
    }}

Python example

import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions 


        
def get_session_key():
    req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"get_session_key\",\"params\":{\"username\":\"admin\",\"password\":\"mypassword\"},\"id\":1}')
    req.add_header('content-type', 'application/json')
    req.add_header('connection', 'Keep-Alive')
    try:
        f = urllib2.urlopen(req)
        myretun = f.read()
        #print myretun
        j=json.loads(myretun)
        return j['result']
    except :
        e = sys.exc_info()[0]
        print ( "<p>Error: %s</p>" % e )
		
def get_question_properties(skey,QuestionID):
    req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"get_question_properties\",\"params\":{\"sSessionKey\":\"'+skey+'\",\"iQuestionID\":'+QuestionID+',\
\"aQuestionSettings\":[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]},\"id\": 1}')

    req.add_header('content-type', 'application/json')
    req.add_header('connection', 'Keep-Alive')
    try:
        f = urllib2.urlopen(req)
        myretun = f.read()
        #print myretun
        j=json.loads(myretun)
        return j['result']
    except :
        e = sys.exc_info()[0]
        print ( "<p>Error: %s</p>" % e )

		
def release_session_key(relkey):
    req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"release_session_key\",\"params\":{\"sSessionKey\":\"'+relkey+'\"},\"id\":1}')
    req.add_header('content-type', 'application/json')
    req.add_header('connection', 'Keep-Alive')
    try:
        f = urllib2.urlopen(req)
        myretun = f.read()
        #print myretun
        j=json.loads(myretun)
        return j['result']
    except :
        e = sys.exc_info()[0]
        print ( "<p>Error: %s</p>" % e )


def export_responses2(skey,sid):
    req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"export_responses\",\"params\":{\"sSessionKey\":\"'+skey+'\",\"iSurveyID\":\"'+sid+'\",\
\"DocumentType\":\"csv\",\"sLanguageCode\":\"de\",\"sHeadingType\":\"full\"},\
"id\": 1}')
    req.add_header('content-type', 'application/json')
    req.add_header('connection', 'Keep-Alive')
    try:
        f = urllib2.urlopen(req)
        myretun = f.read()
        #print myretun
        j=json.loads(myretun)
        return j['result']
    except :
        e = sys.exc_info()[0]
        print ( "<p>Error: %s</p>" % e )		

		
mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)

JSON-RPC notes

The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

Request:

 HTTP headers:

   content-type=application/json

   connection=Keep-Alive

   host=mylimesurveyhost.com

   content-length=65

   user-agent=Apache-HttpClient/4.2.2 (java 1.5)

 Post body:

   {"method":"get_session_key","params":{"username":"admin","password":"mypassword"},"id":1}

Response body:

 {"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}

@@ Line 98: / Line 98: @@
 == Users ==
-===list_users===
+=== list_users ===
-RPC Routine to return the ids and info of users
+Function to return the ids and info of users.
-Parameters:
+<source lang=php>
+function list_users(string $sSessionKey)
+</source>
-sSessionKey (string) - Auth credentials
+{| class="wikitable"
+! Parameter !! Description
+|-
+| sSessionKey || Super-admin's auth credentials.
+|-
+|}
-Returns:
+'''Return on success''': (array) The list of users
-*On success: (array) The list of users
-*On failure: (array) Failure status
+'''Return on failure''': (array) Failure status:
-**No users found
+*No users found
-**Invalid session key
+*Invalid session key
-**No permission (super admin is required)
+*No permission (super admin is required)
 == Surveys ==

RemoteControl 2 API: Difference between revisions

From LimeSurvey Manual

Revision as of 12:55, 18 March 2015

Introduction

Requirements

Setup

How to configure LSRC2

Security

How to use LSRC2

Sessions

get_session_key

release_session_key

Site

get_site_settings

Users

list_users

Surveys

add_survey

delete_survey

import_survey

get_survey_properties

set_survey_properties

list_surveys

activate_survey

export_statistics

get_summary

add_language

delete_survey_language

get_language_properties

set_language_properties

Groups of Questions

add_group

delete_group

import_group

get_group_properties

set_group_properties

list_groups

Questions

delete_question

import_question

get_question_properties

set_question_properties

list_questions

Tokens and Participants

Token Properties

activate_tokens

add_participants

delete_participants

get_participant_properties

set_participant_properties

list_participants

invite_participants

remind_participants

Responses

add_response

export_responses

export_responses_by_token

Testing

Ruby Example

Load Requirements and Declare Values

Module

API Call

Examples

Example Return

PHP Example

JAVA example

Python example

JSON-RPC notes