Actions

RemoteControl 2 API

From LimeSurvey Manual

Revision as of 20:02, 29 August 2017 by LimeAJ (talk | contribs) (→‎PHP Example)

Introduction

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers various API functions.

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 'Interfaces' 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)

Other functions

  For all other function , you have to refer to the online API . If your LimeSurvey version is outdated, you can publish your API and look at it directly.


Example and helper

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"
    }
}

This is an 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', 'https://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;

// instantiate 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").getAsString();
	 return result;
	}
	
	
    public static void main(String[] args) throws UnsupportedEncodingException {
      DefaultHttpClient client = new DefaultHttpClient();          
         
      HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
      post.setHeader("Content-type", "application/json");
      post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"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\": [ \""+sessionKey+"\", \"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 and glue

The following code runs with Python 2 and requires some adaptation to work with Python 3. 

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='https://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"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='https://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
                                    +',[\"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='https://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"release_session_key\",\"params\":[\"'+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='https://myurl/index.php/admin/remotecontrol',\
                          data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"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)

NodeJS example

This script require request, you can include easily with the command 

npm install request

This is a example how to connect to limesurvey: 

var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
  url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
  method: "POST",
  headers: {
    'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
    'host': 'xxxxxxxxxxxxxxxx',
    'path': '/index.php/admin/remotecontrol',
    'connection': 'keep-alive',
    'content-type': 'application/json'
  }
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
  if (!error && response.statusCode == 200) {
      body = JSON.parse(body);

    //*********KEEP THE KEY*********  
    if(SESSIONKEY==="") {
      console.log("NEW KEY -->"+body.result);
      SESSIONKEY=body.result;
      nextFonction();
    } 
  }
  else console.log("ERROR -->"+body);  
});

R example and helper

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client 

# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
  install.packages("devtools")
  library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################


# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
#    sid           surveyls_title startdate             expires active
#1  999999  XXXX               NA 2016-03-08 15:20:30      Y
#2  999998  XXXX               NA   <NA>      Y

#Read the data of the first survey (sid=999999) into a data.frame. 
#Notice that the default sLanguageCode = en, so maybe you have to 
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

JSON-RPC notes

The content-type of the HTTP request must be application/json.  Most formatting errors are a failure to set the content-type header. This 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=67

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

 Post body:

   {"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

 {"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}
Retrieved from "http://manual.limesurvey.org/index.php?title=RemoteControl_2_API&oldid=76499"