LimeSurvey Manual - User contributions [en]

Optional settings

2022-10-17T09:18:18Z

Jweberhofer: Documented maxLoginAttemptParticipants and timeOutParticipants

<languages /> <translate>


__TOC__


The following section is addressed to those of you who would like to edit those configuration settings that could not be modified with the help of the GUI (Graphical User Interface) of the LimeSurvey installation. Please bear in mind that all the changes from the LimeSurvey root directory are done at your own risk. Nevertheless, in the case in which you are experiencing problems/need further guidance, join the [https://www.limesurvey.org/forum discussion forums] or the [irc://irc.freenode.net/limesurvey|IRC IRC channel] for help from the LimeSurvey community.

=Introduction= 


To modify the configuration settings of the installation, you have to edit the optional settings. They can be found in the /application/config/'''config-defaults.php''', which is located in the LimeSurvey root directory. The default settings of the standard installation can be found in config-defaults.php. Some of them can be overridden by using the [[Global settings|global settings]] dialog, while the others will have to be manually edited.


{{Alert|If you want to change these settings, please do not change them in config-defaults.php, but copy the particular setting/line to /application/config/'''config.php''' in <nowiki>'config'=>array( )</nowiki> and change it there. All the newly modified/introduced settings from the config.php file will override the default values from config-defaults.php.}}


When an upgrade occurs, only the config-defaults.php settings are changed. Therefore, editing the config.php file will save your customized settings.


To update/add the LimeSurvey settings in /application/'''config/config.php''', you have to update the config array:
<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>0,
'debugsql'=>0,
'LimeSurveySetting'=>'New value', // Update default LimeSurvey config here
)
</syntaxhighlight>

=Yii settings= 


LimeSurvey uses the Yii framework, which has its own configuration parameters in application/config/'''internal.php''' and application/config/'''config.php''' file. You can also access some specific configuration settings of LimeSurvey via the Yii configuration.


Since config.php array is merged to the whole config, you can replace any Yii params in the config.php file.


The Yii specific settings are set in the components array:
<syntaxhighlight lang="php" enclose="pre">
'components' => array(
'db' => array(
....
),
'Specific settings'=>array(
....
),
),
</syntaxhighlight>


{{Note|For more information about the Yii framework, please access the [http://www.yiiframework.com/doc-2.0/guide-index.html following link.]}}

==Database settings== 
The database settings are written to config.php by the installer file when you install LimeSurvey for the first time. If needed, you can update this part of the config.php file. Please remember that you do this at your own risk!
See also the [http://www.yiiframework.com/doc/blog/1.1/en/prototype.database#establishing-database-connection Yii documentation] and please remember that LimeSurvey supports only the following types of database: mysql, pgsql, dblib, mssql, and sqlsrv.

==Session settings== 


You can set some session parameters in config.php (check the two examples from below). You can uncomment/add the part needed in config.php. See the [http://www.yiiframework.com/doc/api/1.1/CHttpSession Yii Documentation] for other settings.


{{Alert|If you need to update session settings to have multiple LimeSurvey instances running on the same server, check if you don't have to update [[Optional_settings#Request_settings|request settings]] for crsf cookie.}}

===Use table-based sessions=== 


LimeSurvey can use table-based sessions, you find a commented part on the default config.php generated file. To use table-based session, remove the // before each line.


<syntaxhighlight lang="php" enclose="pre">
'session' => array (
'class' => 'application.core.web.DbHttpSession',
'connectionID' => 'db',
'sessionTableName' => '{{sessions}}',
),
</syntaxhighlight>


{{Alert|Table-based sessions are currently not supported on MSSQL server.}}

===Other sessions update=== 


If you use SSL ('https') for your LimeSurvey installation, adding the following lines to your config.php will increase the security of the session:
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie via SSL
'session' => array (
'cookieParams' => array(
'secure' => true, // use SSL for cookies
'httponly' => true // Cookies may not be used by other protocols - experimental
),
),
</syntaxhighlight>


If you want to fix the domain for a cookie, use the following syntax in config.php:
<syntaxhighlight lang="php" enclose="pre"> // Set the domain for cookie
'session' => array (
'cookieParams' => array(
'domain' => '.example.org',
),
),
</syntaxhighlight>


If you have mutiples installation on the same server, it can be more quick and easy to set different session name for each LimeSurvey instance. This can be need for IE11 in some condition (see [https://bugs.limesurvey.org/view.php?id=12083#c42892 issue 12083])
<syntaxhighlight lang="php" enclose="pre"> // Set the name of the session
'session' => array (
'sessionName' => "LimeSurveyN1",
),
</syntaxhighlight>

==Request settings== 
The request settings are important, but the default settings are already optimized for LimeSurvey usage. To read more about them, see the [http://www.yiiframework.com/doc/api/1.1/CHttpRequest Yii Documentation].


For example, the LimeSurvey request settings configuration may be modified in the following way (at your own risk) :
<syntaxhighlight lang="php" enclose="pre"> // Disable CSRF protection
'request' => array(
'enableCsrfValidation'=>false,
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Enforce a certain URL base
'request' => array(
'hostInfo' => 'http://www.example.org/'
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie domain name and path for CSRF protection, path is used if you have different instance on same domain
'request' => array(
'csrfCookie' => array(
'domain' => '.example.com',
'path' => '/limesurvey/',
)
),
</syntaxhighlight>


If you need to update only the url for token emails, set your [[Optional_settings#Advanced_path_settings|publicurl]] in your config.php file.

==Allow usage of session and Csrf Validation in iFrame {{NewIn|v=3.24.3}}== 


After allow [[Global_settings#Security|Iframe embedding]] you need to update some configuration part. Attention, even with all settings : allow form in iframe can broke on some browser. This settings was tested with Firefox 81.0.2 and Chromium 85.0.4183.121.

===Allow session start in iframe=== 


The session need to be secure (valid https) , httponly and samesite to None. All settings must be sent all lowercase.


<syntaxhighlight lang="php" enclose="pre"> 'session' => array (
'sessionName'=>'LS-VBXZZORFJZCAKGYI',
// Uncomment the following lines if you need table-based sessions.
// Note: Table-based sessions are currently not supported on MSSQL server.
// 'class' => 'application.core.web.DbHttpSession',
// 'connectionID' => 'db',
// 'sessionTableName' => '{{sessions}}',
'cookieParams' => array(
'secure' => true,
'httponly' => true,
'samesite' => 'None',
),
),
</syntaxhighlight>

===Allow csrf cookie in iframe=== 


Same than session: must be secure and samesite to None. Whole array must be added at same level than session


<syntaxhighlight lang="php" enclose="pre"> 'request' => array(
'enableCsrfValidation'=>true,
'csrfCookie' => array(
'sameSite' => 'None',
'secure' => true,
),
),
</syntaxhighlight>

==URL settings== 


{{Alert|If you need to update only the url for token and other emails, set your [[Optional_settings#Advanced_url_settings|publicurl]] in your config.php file.}}


To change the default URL settings, update the urlManager:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'showScriptName' => false,
),
</syntaxhighlight>


You can also add .html after the survey id in the following way:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'rules' => array (
'<sid:\d+>' => array('survey/index','urlSuffix'=>'.html','matchValue'=>true),
),
'showScriptName' => false,
),
</syntaxhighlight>
For more information, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.url Yii documentation].

==Logging settings== 


Yii provides different solutions to generate logs. To find out more about them, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.logging logging special topic]. LimeSurvey uses '1' or '2' by default, which allows every web user to see the logs. You can create your own settings using Yii directly.


For example, a quick solution to log errors and warnings in files is:
<syntaxhighlight lang="php" enclose="pre">
return array(
'components' => array(
/* Other component part here 'db' for example */
'log' => array(
'routes' => array(
'fileError' => array(
'class' => 'CFileLogRoute',
'levels' => 'warning, error',
'except' => 'exception.CHttpException.404',
),
),
),
/* Other component part here 'urlManager' for example */
),
/* Final part (with 'runtimePath' 'config' for example) */
);
</syntaxhighlight>


{{Hint|Text=The file is saved by default to <code><nowiki>limesurvey/tmp/runtime/application.log</nowiki></code>, which is located in the LimeSurvey root folder.}}
{{Alert|Yii uses runtime path. By default, the logs are web accessible. They may contain a lot of information from your server. It is better to use a directory that cannot be accessed via the web. You can set it in routes or by updating the [[Optional settings#Yii settings#Runtime path|Runtime path]].}}.

==Runtime path== 


[http://www.yiiframework.com/doc/guide/1.1/en/basics.convention#directory The runtime path] must be a readable and writable directory for the “web user”. However, the runtime path contains files with potential security information that are located in the public web access area. LimeSurvey collects these files in the temp directory of the LimeSurvey root directory. In order to eliminate the access to such important data, you can set the runtime path outside the public web access by editing the respective lines in the /application/config/config.php file:


<syntaxhighlight lang="php" enclose="pre">
return array(
'components' => array(
[…]
'runtimePath'=>'/var/limesurvey/runtime/',
'config'=>array(
[…]
)
)
)
</syntaxhighlight>

=General settings= 


*'''sitename''': Gives your survey site a name. This name will appear in the survey list overview and in the administration header. The default value is 'LimeSurvey' and it can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''siteadminemail:''' This is the default email address of the site administrator and it is used for system messages and contact options. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog.
*'''siteadminbounce:''' This is the email address where bounced emails will be sent to. This setting is used only as default value and can be overridden by the [[Global settings|global settings]] dialog.
*'''siteadminname:''' The real name of the site administrator. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog).
*'''proxy_host_name:''' This is the host name of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).
*'''proxy_host_port:''' This is the port of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).

= Security= 


* '''maxLoginAttempt''': This is the number of attempts a user has to enter the correct password before he or she gets her or his IP address blocked/locked out. The default value is 3 and it can be modified from config.php.
* '''timeOutTime''': If the user enters the password incorrectly for <maxLoginAttempt>, she or he gets locked out for <timeOutTime> seconds. The default value is 10 minutes and it can be modified from config.php.
* '''maxLoginAttemptParticipants''': This is the number of attempts a participant has to enter a valid token before he or she gets her or his IP address blocked/locked out. The default value is 3 and it can be modified from config.php.
* '''timeOutParticipants''': If the participant enters the token incorrectly for <maxLoginAttemptParticipants>, she or he gets locked out for <timeOutParticipants> seconds. The default value is 10 minutes and it can be modified from config.php.
* '''surveyPreview_require_Auth''': Set to true by default. If you set this to 'false', any person can test your survey using the survey URL, without logging in to the administration panel and without having to activate the survey first. This setting is a default value and can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
* '''usercontrolSameGroupPolicy''': Set to true by default. By default, non-admin users defined in the LimeSurvey management interface will only be able to see users they create or users that belong to at least one same group. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''filterxsshtml:''' This setting enables the filtering of suspicious html tags located within surveys, groups, and questions and answer texts in the administration interface. Leave this to 'false' only if you absolutely trust the users you created for the administration of LimeSurvey and if you want to allow these users to be able to use Javascript, Flash Movies, etc.. The super admins never have their HTML filtered. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''demoMode:''' If this option is set to 'true' in config.php, then LimeSurvey will go into demo mode. The demo mode changes the following things:
** Disables admin user's details and password changing;
** Disables the upload of files on the template editor;
** Disables sending email invitations and reminders;
** Disables the creation of a database dump;
** Disables the ability to modify the following global settings: site name, default language, default HTML editor mode, XSS filter.
*'''forcedsuperadmin:''' Array of user id whith all rights on all LimeSurvey. This settings can only be updated in config.php file. This user's rights can not be edited in [[Manage_users#Set_global_permissions_for_a_user|global permissions for a user]] even by other forced super administrator. By default : user with this rights is user with id : 1. The first user created just after installation.
*'''force_ssl:''' forces LimeSurvey to run through HTTPS or to block HTTPS. See [https://manual.limesurvey.org/Global_settings#Security Force HTTPS] in global settings admin GUI.
*'''ssl_emergency_override:''' This setting forces SSL off. If You've turned HTTPS/SSL on in the global settings but your server doesn't have HTTPS enabled, the only way to turn it off is by changing a value in the database directly. This allows you to force HTTPS off while you change the global settings for Force Secure. This should always be false except in emergencies where you change it to true until you fix the problem. This setting can be only set via config.php file.
*'''ssl_disable_alert:''' Disable alert for super-admin about unforced SSL, if you really can not or don't want to force ssl. This setting can be only set via config.php file.

= Resources= 
*'''sessionlifetime:''' Defines the time in seconds after which a survey session expires. It applies only if you are using database sessions. If you do use database sessions, change the parameter in config.php or override the default value from the [[Global settings|global settings]] dialog.
*'''memorylimit:''' This determines how much memory LimeSurvey can access. '128 MB' is the minimum (MB=Megabyte) recommended. If you receive time out errors or have problems generating statistics or exporting files, raise this limit to '256 MB' or higher. If your web server has set a higher limit in config.php, then this setting will be ignored.


<div class="warningbox">'''Please bear in mind that such local settings can always be overruled by the changes done in the global settings dialog'''.</div>


To increase the memory limit to 128M you could also try adding:
*memory_limit = 128M to your server's main php.ini file (recommended, if you have access)
*memory_limit = 128M to a php.ini file in the LimeSurvey root
*php_value memory_limit 128M in a .htaccess file in the LimeSurvey root


*'''max_execution_time:''' Set the number of seconds a script is allowed to run. If this is reached, the script returns a fatal error. To be allowed to export big survey data and statistics, LimeSurvey try to set it by default to 1200 seconds. You can set a bigger time or a lower time if needed. Only accessible via php config file.

=Appearance= 
*'''dropdownthreshold'''{{ObsoleteIn|2.50}}: When "R" is selected for <code>$dropdowns</code>, the administrator is allowed to set a maximum number of options that will be displayed as radio buttons, before converting back to a dropdown list. If there is a question that has a large number of options, displaying all of them at once as radio buttons can look unwieldy, and can become counter-intuitive to users. Setting this to a maximum of, say 25 (which is the default) means that large lists are easier to be used by the administrators for the survey participant.
*'''repeatheadings:''' With the Array question type, you'll often have a lot of subquestions, which - when displayed on screen - take up more than one page. This setting lets you decide how many subquestions should be displayed before repeating the header information for the question. A good setting for this is around 15. If you don't want the headings to repeat at all, set this to 0. This setting is overridden in the [[Global settings|global settings]] dialog {{NewIn|2.05}}.
*'''minrepeatheadings:''' The minimum number of remaining subquestions that are required before repeating the headings in Array questions. The default value is 3 and it can be edited in config.php.
*'''defaulttemplate:''' This setting specifies the default theme used for the 'public list' of surveys. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''defaulthtmleditormode:''' Sets the default mode for the integrated HTML editor. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php. The valid settings are:
** 'inline' - Inline replacement of fields by an HTML editor. Slow but convenient and user friendly;
** 'popup' - Adds an icon that runs the HTML editor in a popup if needed. Faster, but HTML code is displayed in the form;
** 'none'- No HTML editor;
*'''column_style:''' Defines how columns are rendered for survey answers when using [[QS:Display_columns|display_columns]]. It can be edited in the config.php file. The valid settings are:
** 'css' - it uses one of the various CSS methods to create columns (see the template style sheet for details);
** 'ul' - the columns are rendered as multiple floated unordered lists (default);
** 'table' - it uses conventional-tables-based layout;
** NULL - it disables the use of columns.

=Language & time= 
*'''defaultlang:''' This should be set to the default language to be used in your administration scripts, and also the default setting for language in the public survey list. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''timeadjust:''' If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia, but I use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.

=Survey behavior= 
*'''deletenonvalues:''' Use this feature with caution. By default (a value of 1), irrelevant questions are NULLed in the database. This ensures that the data in your database is internally consistent. However, there are rare cases where you might want to hold onto irrelevant values, in which case you can set the value to 0. For example, you ask a male person his gender, and he accidentally says 'female' and then answers some female-specific questions (questions that are conditioned on being female, so are only relevant for women). Then, he realizes his mistake, backs up, sets the gender to 'male', and continues with the survey. Now, the female-specific questions are irrelevant. If <code>$deletenonvalues==1</code>, those irrelevant values will be cleared (NULLed) in the database. If <code>$deletenonvalues==0</code>, his erroneous answers will not be deleted, so they will still be present in the database when you analyze it.
*'''shownoanswer:''' When a radio button/select type question that contains editable answers (i.e.: List, Array questions) is not mandatory and 'shownoanswer' is set to 1, an additional 'No answer' entry is shown - so that participants may choose to not answer the question. Some people prefer this not to be available. This setting can be overridden from the [[Global settings|global settings]] dialog or edited in config.php. Valid values are:
**'0': No;
**'1': Yes;
**'2': The Survey admin can choose.
*'''printanswershonorsconditions:''' This setting determines if the printanswers feature will display entries from questions that were hidden by conditions-branching (Default: 1 = hide answers from questions hidden by conditions).
*'''hide_groupdescr_allinone:''' This setting is relevant for all-in-one surveys using conditions . When this is set to 'true', the group name and description is hidden if all questions in the group are hidden. The default value is 'true' - hides group name and description when all questions in the group are hidden by conditions. It can be edited in config.php.
*'''showpopups:''' Show popup messages if mandatory or conditional questions have not been answered correctly:
** '2' = defined by Theme option (default)
** '1'= show popup message;
** '0'= show message on page instead;
** '-1'= do not show the message at all (in this case, users will still see the question-specific tips indicating which questions must be answered).

== Numerical question type behavior == 


*'''bFixNumAuto:''' Numeric fields can be automatically filtered to remove all non numeric values. By default this is enable, you can disable it globally. This settings is related to ''Fix automatically numeric value'' in core theme options. It was enable for ''Yes'', disable for ''Only for expression'' and ''No''.
*'''bNumRealValue:''' Numeric fields used in expression manager can be fixed or not. It's fixed by default. If NUMERIC is a numerical question : disable or 0 : {NUMERIC} with bad caracters send <nowiki>''</nowiki>, enable or 1 : {NUMERIC} send all character entered. This settings is related to ''Fix automatically numeric value'' in core theme options. It was enable for ''Yes'' and ''Only for expression'' and disable for ''No''.

=Development and debugging= 
*'''debug:''' With this setting, you set the PHP error reporting to E_ALL. This means that every little notice, warning or error related to the script is shown. This setting should be only switched to '1' if you are trying to debug the application for any reason. If you are a developer, switch it to '2'. Don't switch it to '1' or '2' in production since it might cause path disclosure. The default value is '0' and it can be edited in config.php.
*'''debugsql:''' Activate this setting if you want to display all SQL queries executed for the script on the bottom of each page. Very useful for the optimization of the the number of queries. In order to activate it, change the default value to '1' from the config.php file.
*'''use_asset_manager:''' By default : debug mode disable asset manager, you can allow you to use asse manager with debug mode enable.


In the case in which you experience an error in the application, we strongly recommend to activate the debug setting in order to get a more detailed error that you can submit with the bug report:


<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>2,
'debugsql'=>0,
)
</syntaxhighlight>


If you work on plugin and need a quick way to dump variables on screen : you can use traceVar function. If debug is set : this function use CWebLogRoute to be shown on HTML page. Usage <code>traceVar($MyVariable)</code>

= Email settings= 


All the settings from below can be overridden in the [[Global settings|global settings]] dialog.
*'''emailmethod:'' This determines how email messages are being sent. The following options are available:
**'mail:' it uses internal PHP mailer;
**'sendmail:' it uses sendmail mailer;
**'smtp:' it uses SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
*'''emailsmtphost:'' If you use 'smtp' as <code>$emailmethod</code>, then you have to put your SMTP-server here. If you are using Google mail you might have to add the port number like $emailsmtphost = 'smtp.gmail.com:465'.
*''emailsmtpuser:'' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*''emailsmtppassword:'' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*''emailsmtpssl:'' Set this to 'ssl' or 'tls' to use SSL/TLS for SMTP connection.
*''maxemails:'' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button from the token control toolbar (not the button situated on the right of each token) sends the <maxemails> number of invitations, then it displays a list of the addresses of the recipients and a warning that ''there are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent.'' and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log out and come back at a later time to send the next batch of invites.

= Statistics and response browsing= 
*'''filterout_incomplete_answers:''' Control the default behavior of filtering incomplete answers when browsing or analyzing responses. For a discussion on incomplete responses see our [[Responses & statistics#Responses summary|browsing survey results wiki]]. Since these records can corrupt the statistics, an option is given to switch this filter on or off in several GUI forms. The parameter can be edited in the config.php. The following options are available:
**'show': Allows you to visualize both complete and incomplete answers;
**'filter': It shows only complete answers;
**'incomplete': Show only incomplete answers.
*'''strip_query_from_referer_url''': This setting determines if the referrer URL saves the parameter or not. The default value is 'false' (in this case, the referrer URL saves all parameters). Alternatively, this value can be set to 'true' and the parameter part of the referrer URL will be removed.
*'''showaggregateddata:''' when activated, additional statistical values such as the arithmetic mean and standard deviation are shown. Furthermore, the data is aggregated to get a faster overview. For example, results of scale 1+2 and 4+5 are added to have a general ranking like "good" (1/2), "average" (3) and "bad" (4/5). This only affects question types "A" (5 point array) and "5" (5 point choice).
* '''PDF Export Settings:''' This feature activates PDF export for printable surveys and Print Answers. The PDF export function is totally experimental and the output is far from being perfect. Unfortunately, no support can be given at the moment - if you want to help to fix it, please get in touch with us.
**'usepdfexport': Set '0' to disable and '1' to enable;
**'pdfdefaultfont': It represents the default font that will be used by the pdf export function. The default value is 'auto'. To change it, you have to set it to one of the [https://tcpdf.org/docs/fonts/ PDF core fonts].
**'alternatepdffontfile': It's an array with language keys and their corresponding font. The default font for each language can be replaced in the config.php file;
**'pdffontsize': it shows the font size for normal texts; For the title of the survey, it is <pdffontsize>+4, while for the group title is <pdffontsize>+2. It can be edited in the config.php file or from the [Global settings|global settings]] dialog;
**'notsupportlanguages': it includes a list with the languages for which no PDF font was found. The list includes Amharic ('am'), Sinhala ('si'), and Thai ('th'), and it can be found in the config-defaults.php file;
**'pdforientation': Set 'L' for Landscape or 'P' for portrait format. It can be edited from the config.php file.
*'''Graph setting'''
**'chartfontfile': Sets the font file name that is used to create the statistical charts. The file has to be located in the fonts directory, located in the LimeSurvey root folder. It can be edited in the config.php file;
**'alternatechartfontfile': It's an array with language keys and their corresponding font. It can be edited in the config.php file.
*'''showsgqacode:''' This setting is used at the printable survey feature and defaults to 'false''. If you set showsgqacode = 'true';, the IDs of each question - and answer if applicable - will be shown. These IDs match the column heading at the Lime_survey_12345 table, which holds the answer data for a certain survey. These IDs can be used for a code book for manual database queries.

= [[LDAP settings]]= 


As this is an extensive topic we have moved [[LDAP settings]] to [[LDAP settings|another page.]]

= Authentication= 


Starting with LimeSurvey 2.05, authentication will be handled by plugins. As a result, the information below might be outdated. See [[Plugins|the plugins wiki]] for most up to date information.

== Authentication delegation to the webserver== 


System administrators may want to have their '''survey administrators''' authenticated against a central authentication system (Active Directory, openLdap, Radius, ...) rather than using the internal LimeSurvey database. An easy way to do this is to setup your web server software to use this external authentication system, and then ask LimeSurvey to trust the user identity reported by the web server. In order to enable this feature, you have to:
* set '''auth_webserver''' to 'true' in config.php;
* enable authentication from the web server side.


Please note that:
* LimeSurvey will then bypass its own authentication process (by using the login name reported by the web server without asking for a password);
* this can only replace the LimeSurvey GUI authentication system, '''not the survey invitation system''' (participant interface).

== Authentication delegation with no automatic user import== 


Please note that Authentication Delegation doesn't bypass the LimeSurvey authorization system by default - meaning that, even if you don't have to manage passwords in LimeSurvey, you still need to define the users in the LimeSurvey database and assign them the correct set of rights in order to let them access the administration panel.


A user is then granted access to LimeSurvey if and only if:
* he has been authenticated to the web server;
* his login name is defined as a user in the LimeSurvey user database (the user is then granted the privileges of the user defined in the LimeSurvey user database).

== Authentication delegation with automatic user import== 


When managing a huge user database, it is sometimes easier to auto-import users in the LimeSurvey database:
*'''auth_webserver_autocreate_user''': If set to 'true', LimeSurvey will try to auto-import users authenticated by the web server but not already in its users DB.
*'''auth_webserver_autocreate_profile''': An array describing the default profile that will be assigned to the user, including the full (fake) name, email, and privileges.


If you want to customize the user profile so that it matches the logged-in user, you'll have to develop a simple function called '''hook_get_autouserprofile''' - with this function you can retrieve from a central user account database (for instance, from a LDAP directory) the true full name, names, and email of a particular user. You can even customize his privileges on the system based on the groups he is allocated in the external database.


The '''hook_get_auth_webserver_profile''' function takes the user login name as the only argument and can return:
* False or an empty array - in this case the user is denied access to LimeSurvey;
* an array containing all common userprofile entries as described in the <code>$WebserverAuth_autouserprofile</code>

</translate><syntaxhighlight lang="php">function hook_get_auth_webserver_profile($user_name)
{
// Retrieve user's data from your database backend (for instance LDAP) here
... get $user_name_from_backend
... get $user_email_from_backend
... get $user_lang_from_backend
... from groups defined in your backend set $user_admin_status_frombackend_0_or_1
return Array(
'full_name' => "$user_name_from_backend",
'email' => "$user_email_from_backend",
'lang' => '$user_lang_from_backend',
'htmleditormode' => 'inline',
'templatelist' => 'default,basic,MyOrgTemplate',
'create_survey' => 1,
'create_user' => 0,
'delete_user' => 0,
'superadmin' => $user_admin_status_frombackend_0_or_1,
'configurator' =>0,
'manage_template' => 0,
'manage_label' => 0);
}

// If user should be denied access, return an empty array

// return Array();</syntaxhighlight><translate>


{{Alert|The optionnal 'hook_get_auth_webserver_profile' function is for advanced user usage only! For further details, please read the comments from the config-defaults.php file.}}

== User name mapping== 


In the case in which some users have an external user name that is different from their LimeSurvey user name, you may find useful to use a user name mapping. This is done in LimeSurvey by using the '''auth_webserver_user_map''' parameter. For instance, imagine you don't have an 'admin' user name defined in your external authentication database. Then, in order to login to LimeSurvey as admin, you'll have to map your external user name (let's call it 'myname') to the admin login name in LimeSurvey. The corresponding setup is:

</translate>
<syntaxhighlight lang="php">'config'=>array(
...
'auth_webserver_user_map' => array ('myname' => 'admin');
)</syntaxhighlight><translate>


After a successful authentication with the 'myname' login and web server password, you'll be directly authorized to use LimeSurvey as the 'admin' user.


This has serious security implications, so use it with care. Also, protect your config.php from write access by the web server.

== Use one-time passwords== 


A user can open the LimeSurvey login page at default.com/limesurvey/admin and type the username and the one-time password which was previously written into the users table (column one_time_pw) by an external application.


This setting has to be turned on config.php file to enable the usage of one-time passwords (default = false).
<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>0,
'debugsql'=>0,
'use_one_time_passwords'=>true,
)
</syntaxhighlight>


More information can be found in the [[Manage users#Use one-time passwords|"Manage Users" section]].

= Encryption settings {{NewIn|4.0.0}} = 


{{Alert|title=Attention|text=Once set, encryption keys should never be changed, otherwise all encrypted data could be lost !}}


{{Note|When update or install, this parameters was generated by LimeSurvey and set in <code>application/config/security.php</code> file. You can move this settings in config.php if you want or leave in security.php.}}


See [[data encryption]] for detail on this feature.


*'''encryptionkeypair'''
*'''encryptionpublickey'''
*'''encryptionsecretkey'''

= Advanced url settings= 


*'''publicurl:''' This should be set to the URL location of your 'public scripts'. The public scripts are those located in the "limesurvey" folder (or whatever name you gave to the directory that all the other scripts and directories are kept in). '''This settings is available in config.php and it is used when LimeSurvey need an absolute url (for example when token emails are sent).'''
*'''homeurl:''' This should be set to the URL location of your administration scripts. These are located in the /limesurvey/admin folder. This should be set to the WEB URL location - for example, ''http://www.example.com/limesurvey/html/admin''. Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the name of your server automatically using a php variable setting - <code>{$_SERVER<nowiki>[</nowiki>'SERVER_NAME']}</code>. '''In most cases, you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.'''
*'''tempurl:''' This should be set to the URL location of your "/limesurvey/tmp" directory - or to a directory in which you would like LimeSurvey to use to serve temporary files.
*'''uploadurl:''' This should be set to the URL location of your "/limesurvey/upload" directory - or to a directory in which you would like LimeSurvey to use to serve uploaded files. This allow you to set uploaded files on another url domain.

= Advanced path settings= 


*'''homedir:''' This should be set to the physical disk location of your administration scripts - for example "/home/usr/htdocs/limesurvey/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the default root path of all your documents using the php variable setting <code>{$_SERVER<nowiki>[</nowiki>'DOCUMENT_ROOT']}</code>. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.
*'''publicdir:''' This should be set to the physical disk location of your 'public scripts'.
*'''tempdir:''' This should be set to the physical disk location of your /limesurvey/tmp directory so that the script can read and write files.
*'''uploaddir:''' This should be set to the physical disk location of your /limesurvey/upload directory so that the script can read and write files.
*'''sCKEditorURL:''' url of the fckeditor script.
*'''fckeditexpandtoolbar:''' defines if the fckeditor toolbar should be opened by default.
*'''pdfexportdir:''' This is the directory with the tcpdf.php extensiontcpdf.php.
*'''pdffonts:''' This is the directory for the TCPDF fonts.

= Other advanced settings= 

== Upload files== 


*'''allowedthemeuploads:''' File types allowed to be uploaded in theme editor
*'''allowedresourcesuploads:''' File types allowed to be uploaded in the resources sections, and with the HTML Editor
*'''allowedfileuploads''' {{NewIn|4.0.0}} Global restriction on file type to be uploaded
*'''magic_database:''' {{NewIn|3.17.17}} Allow to use a different MIME database for [https://www.php.net/manual/en/function.finfo-open.php finfo_open]. Can be updated only in config.php file. Example : <code>/usr/share/misc/magic.mgc</code> for redhat based linux.
*'''magic_file:''' {{NewIn|3.17.17}} Allow to use a different file to get the array of extension by mime type than the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/core/utils/fileExtensions.php included one]. Must be a PHP file return an array. Can be updated only in config.php file.

== Update == 


*'''updatable:''' This setting is in version.php. Can be true or false. If you set to true : when an super admin user log in : LimeSurvey checks if an update is available and show you a warning. If set to false : no check is done and you can't use ComfortUpdate.

</translate>

RemoteControl 2 API

2015-07-08T05:51:40Z

Jweberhofer: more flexible jsonrpc integration in php

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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.

<source lang=php>
function list_users(string $sSessionKey)
</source>

{| class="wikitable"
! 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

<source lang=php>
function get_survey_properties( string $sSessionKey, int $iSurveyID, array $aSurveySettings)
</source>

{| class="wikitable"
! 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'''

{| class="wikitable"
|+ 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
** When there are no attributes for the question, the result for the "attributes" key is set to "No available attributes".
*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:

{| class="wikitable"
! 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

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

= PHP Example =

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included by composer calling

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

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

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?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 );

</source>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-03-18T10:55:02Z

Jweberhofer: Formatted and improved list_users documentation

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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.

<source lang=php>
function list_users(string $sSessionKey)
</source>

{| class="wikitable"
! 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

<source lang=php>
function get_survey_properties( string $sSessionKey, int $iSurveyID, array $aSurveySettings)
</source>

{| class="wikitable"
! 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'''

{| class="wikitable"
|+ 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:

{| class="wikitable"
! 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

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

= PHP Example =

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included by composer calling

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

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

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "2.1.0"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?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 );

</source>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-30T15:47:00Z

Jweberhofer: included jsonrpcphp composer support

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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

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

<source lang=php>
function get_survey_properties( string $sSessionKey, int $iSurveyID, array $aSurveySettings)
</source>

{| class="wikitable"
! 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'''

{| class="wikitable"
|+ 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

= PHP Example =

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included by composer calling

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

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

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "2.1.0"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?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 );

</source>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:39:33Z

Jweberhofer: fixed typo get_survey_properties

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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

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

<source lang=php>
function get_survey_properties( string $sSessionKey, int $iSurveyID, array $aSurveySettings)
</source>

{| class="wikitable"
! 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'''

{| class="wikitable"
|+ 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:38:39Z

Jweberhofer: reformatted get_survey_properties

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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

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

<source lang=php>
function get_survey_properties string $sSessionKey, int $iSurveyID, array $aSurveySettings
</source>

{| class="wikitable"
! 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'''

{| class="wikitable"
|+ 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:12:31Z

Jweberhofer: simplified get_site_settings

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
function get_site_settings( string $sSessionKey, string $sSetttingName)
</source>

{| class="wikitable"
! 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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:11:26Z

Jweberhofer: simplified release_session_key

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
public function get_site_settings( $sSessionKey, $sSetttingName)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
| sSetttingName || string || Name of the setting to get
|-
|}

'''Return on success''': (string) Setting's value

'''Return on failure''': (string) Error message

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:08:02Z

Jweberhofer: simplified get_session_key

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''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.

<source lang=php>
public function release_session_key($sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
public function get_site_settings( $sSessionKey, $sSetttingName)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
| sSetttingName || string || Name of the setting to get
|-
|}

'''Return on success''': (string) Setting's value

'''Return on failure''': (string) Error message

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:05:24Z

Jweberhofer: unified return value description

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
public function get_session_key($username, $password)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| username || string || User name
|-
| password || 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.

<source lang=php>
public function release_session_key($sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
public function get_site_settings( $sSessionKey, $sSetttingName)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
| sSetttingName || string || Name of the setting to get
|-
|}

'''Return on success''': (string) Setting's value

'''Return on failure''': (string) Error message

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T17:01:30Z

Jweberhofer: reformatted get_site_settings

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
public function get_session_key($username, $password)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| username || string || User name
|-
| password || string || Password
|-
|}

{| class="wikitable"
! Return Status !! Type !! Description
|-
| success || string || session key
|-
| failure || || 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.

<source lang=php>
public function release_session_key($sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

=== get_site_settings ===

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

<source lang=php>
public function get_site_settings( $sSessionKey, $sSetttingName)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
| sSetttingName || string || Name of the setting to get
|-
|}

'''Return on success''': (string) Setting's value

'''Return on failure''': (string) Error message

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T14:41:55Z

Jweberhofer: checked and re-formatted; named session key $sSessionKey

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
public function get_session_key($username, $password)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| username || string || User name
|-
| password || string || Password
|-
|}

{| class="wikitable"
! Return Status !! Type !! Description
|-
| success || string || session key
|-
| failure || || 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.

<source lang=php>
public function release_session_key($sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| sSessionKey || string || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T14:38:00Z

Jweberhofer: modified tables

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
public function get_session_key($username, $password)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| username || string || User name
|-
| password || string || Password
|-
|}

{| class="wikitable"
! Return Status !! Type !! Description
|-
| success || string || session key
|-
| failure || || 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T14:35:45Z

Jweberhofer: checked an re-formatted get_session_key()

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

<source lang=php>
public function get_session_key($username, $password)
</source>

{| class="wikitable"
|+ Parameters
! Parameter !! Type !! Description
|-
| username || string || User name
|-
| password || string || Password
|-
|}

{| class="wikitable"
|+ Return values
! Status !! Type !! Description
|-
| success || string || session key
|-
| failure || || 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T14:05:14Z

Jweberhofer: New section Token Properties for reference

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

== 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) - 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:

{| class="wikitable"
! 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 ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

'''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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T13:57:48Z

Jweberhofer: removed some noise

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

=== activate_tokens ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

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

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
|-
|email|| 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
|-
|email|| 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
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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T13:56:07Z

Jweberhofer: reformatted activate_tokens

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

=== activate_tokens ===

Activate tokens.

<source lang=php>
public function activate_tokens($sSessionKey, $iSurveyID, $additional_attributes)
</source>

{| class="wikitable"
! 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''': 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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

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

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
|-
|email|| 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
|-
|email|| 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
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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T13:45:14Z

Jweberhofer: simplified add_participants example

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

===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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">[ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ]</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

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

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
|-
|email|| 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
|-
|email|| 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
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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T13:27:48Z

Jweberhofer: Structured thematically

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html 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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

Parameters: session key (string)

Returns:
*Always: 'OK' (string)

== Site ==

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

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

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

* 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 and Users ==

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

===list_users===

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

===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 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.

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">{ "participantData": [ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ] }
</source>
|-
| $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:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

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

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
|-
|email|| 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
|-
|email|| 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
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.

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

== Responses ==

===add_response===

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

===export_responses===
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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===

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T12:12:46Z

Jweberhofer: Rewrote add_participants section

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

* 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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

<source lang=php>
public add_participants($sSessionKey, $iSurveyID, $participantData, $createTokenKey)
</source>

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $participantData || (array) || 2-dimensional array/structure containing your participants data. Example:
<source lang="javascript">{ "participantData": [ {"email":"me@example.com","lastname":"Bond","firstname":"James"} ] }
</source>
|-
| $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
|-
|}

'''Return''': array(struct) On success: Structure containing your participants data plus the token ID and (if applicable) the new token. Example:
<source lang="javascript">
[ {"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"} ]
</source>

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

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
|-
|email|| 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
|-
|email|| 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
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.

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

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

==export_responses==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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==

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T12:00:41Z

Jweberhofer: reformatted add_participants

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

* 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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

Request:
<source lang="javascript">
{
"id":"1",
"method":"add_participants",
"params": {
"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm",
"surveyID":"668138",
"participantData": [
{"email":"me@example.com","lastname":"Bond","firstname":"James"}
]
}
}
</source>

Response:
<source lang="javascript">
{
"id":"1",
"result": [
{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}
],
"error":null
}
</source>

==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
|-
|email|| 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
|-
|email|| 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
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.

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

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

==export_responses==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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==

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2015-01-27T12:00:20Z

Jweberhofer: reformatted add_participants

__TOC__

=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 [http://www.xmlrpc.com/ 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 [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

* 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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

Request:
<source lang="javascript">
{
"id":"1",
"method":"add_participants",
"params": {
"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm",
"surveyID":"668138",
"participantData": [
{"email":"me@example.com","lastname":"Bond","firstname":"James"}
]
}
}
</source>

Response:
<source lang="javascript">
{
"id":"1",
"result": [
{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}
],
"error":null}
</source>

==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
|-
|email|| 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
|-
|email|| 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
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.

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

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

==export_responses==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

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

{| class="wikitable"
! 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==

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:51:12Z

Jweberhofer: improved documentation for add_response

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

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

<source lang=php>
public function add_response($sSessionKey, $iSurveyID, $aResponseData)
</source>

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

{| class="wikitable"
! Parameter !! Type !! Description
|-
| $sSessionKey || string || Auth credentials
|-
| $iSurveyID || int || Id of the Survey
|-
| $aResponseData || array || The actual response
|-
|}

==export_responses==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

RPC Routine to export responses. 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

'''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 refer to the record's offset in the table

{| class="wikitable"
! 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==

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:44:31Z

Jweberhofer: Reformatted

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

RPC Routine to export responses. 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

'''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 refer to the record's offset in the table

{| class="wikitable"
! 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==

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:44:12Z

Jweberhofer: Reformatted

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

RPC Routine to export responses. 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

'''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 refer to the record's offset in the table

{| class="wikitable"
! 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==

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

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:42:27Z

Jweberhofer: added return values

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
RPC Routine to export responses. Returns the requested file as base64 encoded string.

<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

'''Return''': array|string 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.

'''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 refer to the record's offset in the table

{| class="wikitable"
! 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==

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

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:41:39Z

Jweberhofer: improved documentation of export_responses_by_token

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
RPC Routine to export responses. Returns the requested file as base64 encoded string.

<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

{| class="wikitable"
! 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
|-
|}

'''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 refer to the record's offset in the table

==export_responses_by_token==

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

<source lang=php>
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)
</source>

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

{| class="wikitable"
! 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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:36:05Z

Jweberhofer: Fixed typo

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
RPC Routine to export responses. Returns the requested file as base64 encoded string.

<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

{| class="wikitable"
! 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
|-
|}

'''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 refer to the record's offset in the table

==export_responses_by_token==

Export responses data of specific token to pdf,csv,xls,doc

Parameters:

sSessionKey (string) - Auth credentials

SurveyID (int) - Id of the Survey

DocumentType (string) - pdf,csv,xls,doc,html

sToken (string) - Token string of a candidate

sLanguageCode (string) - Optional The language to be used - if not given then the base language will 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'

aFields (array) - Optional Selected fields

Return:

On success: Requested file as base 64-encoded string.

On failure: Array with error information

=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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-30T15:35:19Z

Jweberhofer: improved documentation for export_response

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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==
RPC Routine to export responses. Returns the requested file as base64 encoded string.

<source lang=php>
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)
</source>

{| class="wikitable"
! 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
|-
|}
</source>

'''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 refer to the record's offset in the table

==export_responses_by_token==

Export responses data of specific token to pdf,csv,xls,doc

Parameters:

sSessionKey (string) - Auth credentials

SurveyID (int) - Id of the Survey

DocumentType (string) - pdf,csv,xls,doc,html

sToken (string) - Token string of a candidate

sLanguageCode (string) - Optional The language to be used - if not given then the base language will 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'

aFields (array) - Optional Selected fields

Return:

On success: Requested file as base 64-encoded string.

On failure: Array with error information

=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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

RemoteControl 2 API

2014-07-24T16:54:30Z

Jweberhofer: linked a newer version of jsonrpcphp

__TOC__

=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 [http://www.xmlrpc.com/ 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 the following functions:

==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.

Parameters: username (string), password (string)

Returns:
*On success: A session key (string)
*On failure: 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.

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

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

==list_users==

RPC Routine to return the ids and info of users

Parameters:

sSessionKey (string) - Auth credentials

Returns:
*On success: (array) The list of users
*On failure: (array) Failure status
**No users found
**Invalid session key
**No permission (super admin is required)

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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.

==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, html

sLanguageCode (string) - Optional The language to be used - if not given then the base language will 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'

FromResponse (int) - Optional start number of response

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

==export_responses_by_token==

Export responses data of specific token to pdf,csv,xls,doc

Parameters:

sSessionKey (string) - Auth credentials

SurveyID (int) - Id of the Survey

DocumentType (string) - pdf,csv,xls,doc,html

sToken (string) - Token string of a candidate

sLanguageCode (string) - Optional The language to be used - if not given then the base language will 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'

aFields (array) - Optional Selected fields

Return:

On success: Requested file as base 64-encoded string.

On failure: Array with error information

=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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>
==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].

<syntaxhighlight lang="php" enclose="div">
<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

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

<syntaxhighlight lang="java" enclose="div">
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();
}
}}

</syntaxhighlight>

=Python example=
<syntaxhighlight lang="python" enclose="div">
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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % 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 ( "Error: %s" % e )

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

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

Expression Manager

2013-06-13T12:30:45Z

Jweberhofer: added category

<languages /> <translate>


__TOC__


<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div>

=Quick Start Tutorial= 

==Overview== 


When customizing your surveys, you typically need a way to specify the following:
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked
#'''Tailoring/Piping''' - how to phrase the question (such as referring to prior answers, or conjugating sentences based upon the number or gender of your subjects), or how to generate custom reports (like assessment scores or tailored advice).
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern


Expression Manager (EM) provides an intuitive way to specifying the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression, even if you are calling functions. EM currently provides access to 70 functions, and can be easily extended to support more. It also lets you access your variables using human-readable variable names (rather than SGQA names).


The following sections show the main places where Expression Manager is used

==Relevance (Controlling Navigation/Branching)== 


Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


This image shows one way to review the relevance logic for a survey. It computes Body Mass Index. The relevance equation is shown in square bracket right after the variable name (which is in green). So, the relevance of weight, weight_units, weight_kg are all 1, meaning that those questions are always asked. However, the relevance for BMI is {!is_empty(height) and !is_empty(weight)}, which means that BMI will only be computed if the subject enters a value for both height and weight (thereby avoiding the risk of a divide by zero error). Also, the Report question is only shown if the subject answers all four main questions (height, height_units, weight, weight_units).


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

===Viewing / Editing Question-Level Relevance=== 


This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

===Viewing / Editing Group-Level Relevance=== 


This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}. EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.


Here is the screen for editing the group-level relevance for that question:


[[File:tutorial5.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping== 


EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use Mr. or Mrs. based upon the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation. EM supports each of these types of tailoring/piping.

===Conditional Equations=== 


The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height in weight in metric or non-metric units.


[[File:tailoring7.jpg]]


Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiple the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.


BMI computes the weight formula as {weight_kg / (height_m * height_m)}.


Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."


Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View


[[File:tailoring8.jpg]]


From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.


[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports=== 


<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki></nowiki> tag which is not valid inside select options.</div>


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.


[[File:tailoring12.jpg]]


You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.


Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation== 


EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers; min/max individual values; min/max sum values; and checking that entered values match specified string patterns. You continue to enter those advanced question options as usual. However, now any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.


In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.


The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction= 


LimeSurvey 1.92 and later uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).


This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.


However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.


This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?== 


Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.


Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?== 


Here is a list of pros and cons of each style:


{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions 2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well 2. Cascading conditions work erratically 3. Slow - database intensive, so can slow down long surveys 4. Some reported problems with re-loading conditions 5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions 6. May be slow to convert paper-based surveys since must use SGQA names 7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators 2. Perfect support for cascading logic 3. Fast - no extra database calls, so supports 1000+ question surveys 4. No problems with re-loading logic since does not require SGQA codes 5. Syntax-highlighting scales to 1000+ question surveys 6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. 7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead 2. New, so support teams have not mastered EM yet.
|}


The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?== 


Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.
#*This also avoids the common need to edit questions to change the SGQA code to make everything work.
#Tailoring - you can conditionally display text based upon other values
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?== 


Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values).
#Easy review of entire survey logic and content
#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
#*It also shows the relevance, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=Getting Started= 


The best way to get started with EM is to:
*Install 1.92+ from http://www.limesurvey.org/en/download .
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Availalbe Functions lists the 70+ functions and syntax
**Unit Tests of Isolsted Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)= 

==Conditions => Relevance== 


Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring== 


Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==Replacements => Micro-Tailoring== 


Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {INSERTANS:111X3X4} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

==Validation== 


Question could be validated with Regular expressions, or minimum/maximum values, or let an SGQA response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?= 


The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)== 


EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be diplayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.


Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.


Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:


{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}


The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose and option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first deterimine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping=== 


Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).


Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations=== 


There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.


This solves a common request for storing Assessment scores within the database

==Syntax== 


Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).


Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:


<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


Expression Manager supports the following syntax:
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)


EM syntax follows normal operator precedence:


{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}


Note, for consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, we recommend using the join() function for concatenation, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

===Caution about using Assignment Operator (=)=== 


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you sould create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.


To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")


The main reasons you may want to use assignment are:
*You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
*You need to forcibly change the response to a previous question based upon a later response

==Access to Variables== 


Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question


In addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.


Furthermore, Expression Manager lets you access many properties of the Question:


{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== Security issue=== 


For security issues, text entered by user are filtered. Some caracter are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming== 


Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:


QuestionCode . '_' . AnswerID . '_' . ScaleId


{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables== 


Quite often, you want to evalute all parts of a question, such as counting how many sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).


The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''


''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.


Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}


You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}


The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''


''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''


Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? (sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}


The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.


The one caveat is that when you use the [[Show Logic File|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'


Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Access to Functions== 


Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions=== 


The following functions are currently available:


{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join (in last 2.0 version)||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager Sample Surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle)
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered=== 


Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.


{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept(questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses(questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local== 


In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions== 


If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant


{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions=== 


Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN')). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.


To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.


So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?== 


Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):


{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}


All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.


Expression Manager provides this functionality by surrounding each expression with a named element. Every time a value changes, it recomputes the expression that should appear in that element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality== 


{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}'} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting= 


To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Relationship to LimeSurvey Ideas / Feature Requests= 


Expression Manager provides complete or partial solutions to each of the following:
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]
**Equations let one store the Assessment value in the database, completely solving this problem
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]
**since Tailoring has access to the full question text, it can include images in the export
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]
**The Show Survey Logic view shows that mapping (plus much more information)
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]
**You can use the Navigation Index for this in most cases
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}
**Computing the mean across a set of respondants would require extension of the Quota functionality.
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]
**Tailoring lets you conjugate verbs and decline nouns in each language
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]
**This can be done with Equation question type
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]
**This can be supported via conditional relevance branching and tailoring

=Additional Reading= 

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

==[[Expression Manager for developers|Reference for Developers]]== 

==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]== 

</translate>

[[Category:Development]]

Expression Manager

2013-06-13T12:27:11Z

Jweberhofer: Added function convert_value

Standard for Git commit messages

2013-06-10T08:53:12Z

Jweberhofer: added category

~tc~(alias(Standard for subversion commit messages))~/tc~

__TOC__

=General overview=

This page describes the standard format of commit messages. Indeed, standard commit messages will ease the automatic generation of releases change logs.

=Rules=

==Syntax==
* Each commit message is made up of one or more commit blocks
* A commit block:
** The first line is the 'Commit Summary' and describes the committed patch in a user friendly way
** the following lines begin with the Keyword '''Dev''' and are intended to the developpers team

<syntaxhighlight lang="php" enclose="div"><Commit type> <commit description> <NEWLINE>

[ Dev <development details> <NEWLINE> ]

[ Dev <development details> <NEWLINE> ]

<Commit type> <commit description> <NEWLINE>

[ Dev <development details> <NEWLINE> ]

[ Dev <development details> <NEWLINE> ]</syntaxhighlight>

==The commit type==

The first word in the commit message gives the commit type:
* If the commit is about a fix, the commit message must begin with the keyword ''''Fixed issue''''
* If the commit is about a change in LS feature, the commit message must begin with the keyword ''''Updated feature''''
* If the commit is about a change in a translation, the commit message must begin with the keyword ''''Updated translation''''
* If the commit is about a new feature, the commit message must begin with the keyword ''''New feature''''
* If the commit is about a new translation, the commit message must begin with the keyword ''''New translation''''

==The commit description==

Following the commit type is the commit description.

This must be a single line (no newline character), and is intended to be used in the generated changelog.

Ideally it is a text readable by end-users: for instance if you're resolving a bug ticket which has a very technical description, please use a "end-user friendly description".

==The development details==

Develoment details are added in extra optionnal lines, each one beginning with the keyword ''''Dev''''.

==Patches which require multiple commits==

When multiple commits are linked to the same topic (same new feature, same fix, ...), the 'Commit Summary' line of subsequent commits must be the same as the one provided for the first commit.

Of course the development details can differ.

== Examples==

Example of a simple language file update:

<syntaxhighlight lang="php" enclose="div">Updated translation: German</syntaxhighlight>

Example of a single bug which is fixed in several commits:

Commit 1:

<syntaxhighlight lang="php" enclose="div">Fixed issue #2565: Can't access survey more than once on the same browser window

Dev this fixes this bug for survey with tokens.

Dev When showing a new token (different from the one in session), the previous session is destroyed.</syntaxhighlight>

Commit 2:

<syntaxhighlight lang="php" enclose="div">

Fixed issue #2565: Can't access survey more than once on the same browser window

Dev this fixes this bug for survey without tokens and without answer preview.

Dev Session is destroyed at submit time.</syntaxhighlight>

Commit 3:

<syntaxhighlight lang="php" enclose="div">Fixed issue #2565: Can't access survey more than once on the same browser window

Dev this fixes this bug for survey without tokens and with answer preview.

Dev Session is destroyed when closing the answer preview window or closing the Submit confirmation page.</syntaxhighlight>

Example of a single commit containing several fixes each with a Dev comment:

<syntaxhighlight lang="php" enclose="div">Fixed issue #1234: fixed some untranslated strings

Dev missing call to clang-gT in admin.php

Fixed issue #2345: fixed a small layout issue in condition editor

Dev fixed div HTML elements</syntaxhighlight>

[[Category:Development]]

Coding guidelines

2013-06-10T08:52:30Z

Jweberhofer: added category

Contents:__TOC__

=General=

'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''

<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"

(Lance Burton, magician)</div>

Some general rules:
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.
*Ask if you are in doubt.

=Naming convention=
*Use the Hungarian Rule for variables:

<syntaxhighlight lang="php" enclose="div">

[t]NameOfVariable

| <strike>-</strike><strike>+</strike>----

| +--> Descriptive name

+--> Datatype stored (for example start with "a" if it is an array)

</syntaxhighlight>

Examples:

aQuestionAttributes: Array to store the questions attributes, Mixed values

dSurveyEnds: Date when the survey ends

sContditionsOutput: String used to create the JS for conditions
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":

function questionsRetrieve( $iQID, $iSurvey)
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems

Here a list of prefixes:
*o=Object
*a=Array
*i=Integer
*f=Float
*s=String

=Documentation=

Please refer to this introduction: [[How to document your source code]].

=Structures=
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.
*The opening curly brace must be below the structure opening:

<syntaxhighlight lang="php" enclose="div">

if (condition)

{

...

}

</syntaxhighlight>
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:

<syntaxhighlight lang="php" enclose="div">

WRONG: if (condition) {do true} else {do false}

WRONG: if (condition) {do true}

else {do false}

RIGHT: if (condition)

{

do true

} else

{

do false

}

RIGHT: swith $sSelector

{

case X:

...

break;

case Y:

...

default:

}

</syntaxhighlight>

NOTE: It´s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.
*SQL sentences must respect the same rule:

<syntaxhighlight lang="php" enclose="div">

$sSQL = "SELECT field1, field2, field3 "

."WHERE condition "

."AND condition "

."OR condition "

."ORDER BY field1, field2";

</syntaxhighlight>
*The same for HTML in views tags:

<syntaxhighlight lang="php" enclose="div">

<table>

<tr>

<td colspan='2'

height='4'>



Some Text



</td>

</tr>

</table>

</syntaxhighlight>

=HTML=
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?>
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.

=Localization=

Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.

Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.

Please follow these important rules:
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting

Wrong: $clang->eT('Visible? ');

Right: $clang->eT('Visible?');
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.

Wrong: $clang->eT('Create A New Label Set');

Right: $clang->eT('Create a new label set');

Wrong: $clang->eT('Google Maps API Key');

Right: $clang->eT('Google Maps API key');
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.

Wrong: echo $clang->gT('The sum must not be bigger than').$iMaxSum;

Right: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);

This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.

Wrong: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');

Right: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.

+Example:

Wrong: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);

Right: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);

=Bug tracker=
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.
#If you would like to work on a bug assign it to yourself.
#Try to reproduce the issue.
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.

=Cross-DB compatibility=

LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding

==Parameter binding==

Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions because this might create a security issue.

Example:

<syntaxhighlight lang="php" enclose="div"><?php

$oResult = Yii::app()->db

->createCommand()

->select('somefield')

->where("sid = :sid")

->from('{{sometable}}')

->bindParam(":sid", $surveyid, PDO::PARAM_INT);

?></syntaxhighlight>

If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:

WRONG:

<syntaxhighlight lang="php" enclose="div"><?php

$oResult = Yii::app()->db

->createCommand()

->select('somefield')

->where("sid = :sid and parent_sid= :sid ")

->from('{{sometable}}')

->bindParam(":sid", $surveyid, PDO::PARAM_INT);

?></syntaxhighlight>

RIGHT:

<syntaxhighlight lang="php" enclose="div"><?php

$oResult = Yii::app()->db

->createCommand()

->select('somefield')

->where("sid = :sid1 and parent_sid= :sid2 ")

->from('{{sometable}}')

->bindParam(":sid1", $surveyid, PDO::PARAM_INT)

->bindParam(":sid2", $surveyid, PDO::PARAM_INT);

?></syntaxhighlight>

=Miscellaneous=
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:

<syntaxhighlight lang="php" enclose="div">

WRONG:

iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)

It will be more readable:

iAuxB = fb(p1,p2)

iAuxD = fd(p3)

iAuxC = fc(iAuxD,p4)

iAResult = fa(iAuxB, iAuxC, p5)

</syntaxhighlight>

Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.

[[Category:Development]]

ExpressionScript for developers

2013-05-17T08:32:51Z

Jweberhofer: restructured text, make it more readable

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

=== Adding Functions ===

When you add a function that does not exist in PHP, then add it to the body of '''em_core_helper.php'''

''FIXME'': Eventually we should separate out such add-on functions into their own php file.

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
<syntaxhighlight lang=PHP>
'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3)
</syntaxhighlight>

The syntax for each function is:
<syntaxhighlight lang=PHP>
function => array( detail_1, detail_2, detail_3, detail_4, detail_5, detail_6 )
</syntaxhighlight>

The ''details'' which must be included in the array are:

# PHP function name - this is the PHP function that will be called for that func.
# JavaScript function name - this is the JavaScript function that will be called for that function
# Meaning - this is a short description of what the function does
# Syntax - this shows the valid syntax for the function
# Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
# Number of required arguments
#* Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
#* Negative values mean that the function accepts a variable number of arguments
#* Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in JavaScript, then add it to the body of '''em_javascript.js'''

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

Make sure to add Unit tests for new functions to UnitTestEvaluator

* Syntax is ExpectedResult~Expression, such as:
* 212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

When your test case should return an error, use NULL as the expected value, like this:

* NULL~four * / seven
* NULL~(5 + 7) = 8

[[Category:Development]]

How to document your source code

2013-05-17T08:27:16Z

Jweberhofer: reformatted

==General==

You can see the current LimeSurvey source code documentation on http://api.limesurvey.org

This documentation is created on an hourly base by phpDocumentor.

The LimeSurvey project is using [http://www.phpdoc.org/ phpDocumentor] to easily create source code documentation. phpDocumentor is an easy way to markup your source-code with specially formatted comments and let the software phpDocumentor afterwards extract this information about your classes/methods/function/variable and show it as a nice documentation.

==phpDocumentor Quick-Start==

However, the work to create the comments comes first. So here is how it works:
#Go to [http://2tbsp.com/content/phpdoc_cheatsheet,_because_documenting_code_fun! 2tbsp.com] and download the PHPDoc cheatsheet in your preferred format.
#Print it out as a poster and pin it to your wall above your PC monitor.
#Since the knowledge is not magically transferred from the cheatsheet to your brain, here is the short form instruction to give you a 'head' start (:biggrin:):
A PHPDoc comment always starts with /** (slash and two asterisks), every following line inside the comment has to start with an * (asterisk), and it is close with */ (single asterisk and slash), like this

<syntaxhighlight lang="php" enclose="div">

/**
* Global variable declaration docBlock
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/

</syntaxhighlight>
*A PHPDoc comment has always to '''precede''' the code it is made for (except for the File comment, which documents the file itself and cannot be placed outside the PHP tags)
*Inside the comment you can use the phpDocumentor tags as described on the cheat sheet. A typical PHPDoc comment for a function would look like this:

<syntaxhighlight lang="php" enclose="div">

/**
* CleanLanguagesFromSurvey() removes any languages from survey tables that are not in the passed list
* Please use carefully as the data is permanently deleted
*
* @param string $sid - the currently selected survey
* @param string $availlangs - space separated list of additional languages in survey (IANA code)
* @global string $connect- the database connection object
* @return bool - always returns true
*
* @since 1.5.0.1642 (2007-01-02)
* @author David Olivier
*/

function CleanLanguagesFromSurvey($sid, $availlangs)
{
global $connect;
$sid=sanitize_int($sid);
$baselang = GetBaseLanguageFromSurveyID($sid);
[....]
</syntaxhighlight>

The above example code block demonstrates nicely how it is done:
* First thing in the comment is a natural description of the functions purpose. Be as descriptive as possible. You can use several lines of description.
* The '''@param''' tags are describing the parameters of the function in the form '@param datatype variablename description'
* '''@global''' describes any global variable used in the function - same form as the @param tag
* '''@return''' describes the value the function returns
* '''@since''' is an optional parameter - it documents when a function was first added to the code - please name at least the subversion build number
* '''@author''' is pretty self-explaining

That's it. The examples on the cheat sheet for the File, Class, and Variable documentation are self-explaining.

[[Category:Development]]

==Errors on documentation generation==

When phpDocumentor is creating the documentation it might stumble over errors in the source code documentation you wrote. All errors generated by the last documentation run can be seen on http://api.limesurvey.org/errors.html .

Be sure to visit this page regularly to check if your documentation is parsing right.

Still if you have comments or questions do not hesitate to contact [[UserPage c_schmitz|me]] or change this document accordingly.

Development overview

2013-05-17T08:06:02Z

Jweberhofer: added category

Table of contents:

*[[LimeSurvey roadmap]]
*[[The LimeSurvey project team]]
*[[How to join the LimeSurvey project team]]
**[[How to become a LimeSurvey Developer]]
*[[Accessing the source code]]
**[[Switch from Subversion to Git]]
*[[Coding guidelines]]
*[[How to document your source code]]
*[[Standard for Git commit messages]]
*[[Updating FCKEditor]]
*[[Release process]]
*[[Help us: Tasks]]
*[[How can I support LimeSurvey?]]
*[[Developer user pages]]
**[[UserPage c_schmitz]]
**[[UserPage jcleeland]]
**[[UserPage kadejo]]
**[[UserPage Mazi]]
**[[UserPage Shnoulle]]
**[[UserPage magiclko]]
***[[SurveyPress]]
*[[How to contribute new features]]
*[[Database versioning]]
*[[The bugtracker and git]]
*[[Plugin system architecture]]
**[[Question plugins]]
***[[Creating a question plugin]]
****[[Question signature]]
**[[Defining attributes]]

[[Category:Development]]

RemoteControl 2 API

2013-05-17T08:02:15Z

Jweberhofer: added category

__TOC__

=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 [http://www.xmlrpc.com/ 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 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: 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.

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

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

Parameters:
*sessionkey (string) - The session key
*surveyID (string) - The survey id
*participantData (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

JSON-RPC example:

<syntaxhighlight lang="php" enclose="div">Request:

{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}

Response:

{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight>

==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
|-
|email|| 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
|-
|email|| 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
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

==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) - Optional The language to be used - if not given then the base language will 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'

FromResponse (int) - Optional start number of response

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

=Ruby Example=

==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.

<syntaxhighlight lang="ruby" enclose="div">
#!/usr/bin/env ruby

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

username = "api_user"
password = "api_user"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
survey = Limesurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')
</syntaxhighlight>

==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.
<syntaxhighlight lang="ruby" enclose="div">
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}"
</syntaxhighlight>

==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.

<syntaxhighlight lang="ruby" enclose="div">
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"}
</syntaxhighlight>

=PHP Example=

To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]

<syntaxhighlight lang="php" enclose="div">

<?php

require_once 'jsonRPCClient.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 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 );

?>

</syntaxhighlight>

=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.

<syntaxhighlight lang="php" enclose="div">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}</syntaxhighlight>

=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

2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties

[[Category:Development]]

ExpressionScript for developers

2013-05-17T08:01:22Z

Jweberhofer: added category

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

=== Adding Functions ===

When you add a function that does not exist in PHP, then add it to the body of '''em_core_helper.php'''

''FIXME'': Eventually we should separate out such add-on functions into their own php file.

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
<syntaxhighlight lang=PHP>
'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3)
</syntaxhighlight>

The syntax for each function is:
<syntaxhighlight lang=PHP>
function => array( detail_1, detail_2, detail_3, detail_4, detail_5, detail_6 )
</syntaxhighlight>

The ''details'' which must be included in the array are:

# PHP function name - this is the PHP function that will be called for that func.
# JavaScript function name - this is the JavaScript function that will be called for that function
# Meaning - this is a short description of what the function does
# Syntax - this shows the valid syntax for the function
# Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
# Number of required arguments
#* Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
#* Negative values mean that the function accepts a variable number of arguments
#* Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in JavaScript, then add it to the body of '''em_javascript.js'''

Make sure to add Unit tests for new functions to UnitTestEvaluator

* Syntax is ExpectedResult~Expression, such as:
* 212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

When your test case should return an error, use NULL as the expected value, like this:

* NULL~four * / seven
* NULL~(5 + 7) = 8

[[Category:Development]]

Plugins - advanced

2013-05-17T08:00:45Z

Jweberhofer: Improved markup, added category

Starting from Limesurvey 2.05, Limesurvey will officially support plugins.

Plugins allow users to customize the functionality of their installation while still being able to benefit from regular software updates.

This documentation is meant for developers that are extending Limesurvey for their own use or for their clients; end users will not be helped by this documentation.

Plugins must implement the [https://github.com/LimeSurvey/LimeSurvey/blob/2.05/application/libraries/PluginManager/iPlugin.php iPlugin] interface. We recommend

extending your plugin class from the [https://github.com/LimeSurvey/LimeSurvey/blob/2.05/application/libraries/PluginManager/PluginBase.php PluginBase] class.

By extending you benefit from common functionality required by plugins that we already have implemented for you. One of these function is the implementation of the getPluginSettings function. This function must return an array describing the configuration options for the user.

The example plugin exposes just 1 configurable setting, the message it'll show.

<syntaxhighlight lang="php" enclose="div">
protected $settings = array(
'logo' => array(
'type' => 'logo',
'path' => 'assets/logo.png'
),

'message' => array(
'type' => 'string',
'label' => 'Message'
)
);
</syntaxhighlight>

The array contains a name for each setting as a key. The values are arrays containing the required meta data.

Supported types are:

* logo
* string
* html
* choice
* relevance

Besides type a number of other keys are available:

* label, defines a label (use English, the label specified here will be passed through the translation functions)
* default, defines a value to show if no value is specified.
* current, defines the current value.
* readOnly, specifies the setting is read only.

[[Category:Development]]

ExpressionScript for developers

2013-05-17T07:47:27Z

Jweberhofer: restructured text, make it more readable

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

=== Adding Functions ===

When you add a function that does not exist in PHP, then add it to the body of '''em_core_helper.php'''

''FIXME'': Eventually we should separate out such add-on functions into their own php file.

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
<syntaxhighlight lang=PHP>
'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3)
</syntaxhighlight>

The syntax for each function is:
<syntaxhighlight lang=PHP>
function => array( detail_1, detail_2, detail_3, detail_4, detail_5, detail_6 )
</syntaxhighlight>

The ''details'' which must be included in the array are:

# PHP function name - this is the PHP function that will be called for that func.
# JavaScript function name - this is the JavaScript function that will be called for that function
# Meaning - this is a short description of what the function does
# Syntax - this shows the valid syntax for the function
# Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
# Number of required arguments
#* Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
#* Negative values mean that the function accepts a variable number of arguments
#* Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in JavaScript, then add it to the body of '''em_javascript.js'''

Make sure to add Unit tests for new functions to UnitTestEvaluator

* Syntax is ExpectedResult~Expression, such as:
* 212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

When your test case should return an error, use NULL as the expected value, like this:

* NULL~four * / seven
* NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-16T14:42:05Z

Jweberhofer: reformatted markup

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

=== Adding Functions ===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:

*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3)

The syntax for each function (func) is:

*''''func'''' => array('''details''')

The details which must be included in the array are:

# PHP function name - this is the PHP function that will be called for that func.
# JavaScript function name - this is the JavaScript function that will be called for that function
# Meaning - this is a short description of what the function does
# Syntax - this shows the valid syntax for the function
# Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
# Number of required arguments
#* Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
#* Negative values mean that the function accepts a variable number of arguments
#* Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

When you add a function that does not exist in PHP, then add it to the body of '''em_core_helper.php'''

* ''FIXME'': Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator

* Syntax is ExpectedResult~Expression, such as:
* 212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

When your test case should return an error, use NULL as the expected value, like this:

* NULL~four * / seven
* NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-13T15:13:24Z

Jweberhofer: fixed path

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

===Adding Functions===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3),

The syntax for each function (func) is:
*''''func'''' => array('''details''')

The details which must be included in the array are:
#PHP function name - this is the PHP function that will be called for that func.
#JavaScript function name - this is the JavaScript function that will be called for that function
#Meaning - this is a short description of what the function does
#Syntax - this shows the valid syntax for the function
#Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
#Number of required arguments
**Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
**Negative values mean that the function accepts a variable number of arguments
**Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in PHP, then add it to the body of em_core_helper.php
*FIXME: Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator
*Syntax is ExpectedResult~Expression, such as:
*212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

If your test case should return an error, use NULL as the expected value, like this:
*NULL~four * / seven
*NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-13T15:13:07Z

Jweberhofer: Updated path; reformatted markup

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionManager (LEM) ===

This centralizes the integration of LimeSurvey with EM

==== Location ====
* Version 1.92: /classes/expressions/LimeExpressionManager.php
* Version 2.0: /application/helpers/admin/expressions/em_manager_helper.php

==== Navigation Functions ====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions

* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====
* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====
* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

===Adding Functions===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3),

The syntax for each function (func) is:
*''''func'''' => array('''details''')

The details which must be included in the array are:
#PHP function name - this is the PHP function that will be called for that func.
#JavaScript function name - this is the JavaScript function that will be called for that function
#Meaning - this is a short description of what the function does
#Syntax - this shows the valid syntax for the function
#Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
#Number of required arguments
**Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
**Negative values mean that the function accepts a variable number of arguments
**Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in PHP, then add it to the body of em_core_helper.php
*FIXME: Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator
*Syntax is ExpectedResult~Expression, such as:
*212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

If your test case should return an error, use NULL as the expected value, like this:
*NULL~four * / seven
*NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-13T15:10:55Z

Jweberhofer: re-ordered sentences

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

===LimeExpressionManager (LEM)===
*Location
**Version 1.92: /classes/expressions/LimeExpressionManager.php
**Version 2.0: /application/helpers/admin/expressions/em_manager_helper.php
*Purpose - this centralizes the integration of LimeSurvey with EM
====Navigation Functions====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions
*NavigateForwards()
*NavigateBackwards()
*JumpTo()
*GetLastMoveResult() -
====Initialization Functions====
*StartSurvey() - initializes the survey, setting all variable mappings
*setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
*_CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
*ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
*_ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.
====Functions to Generate Tailored Content====
*StartProcessingPage() - called at beginning of each page
*StartProcessingGroup() - called for each group on a page
*FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
*FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function
====Response Management====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values
====Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
*SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
*SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one
====Validation Functions====
*_ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
*_ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
*_ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria
===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

===Adding Functions===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3),

The syntax for each function (func) is:
*''''func'''' => array('''details''')

The details which must be included in the array are:
#PHP function name - this is the PHP function that will be called for that func.
#JavaScript function name - this is the JavaScript function that will be called for that function
#Meaning - this is a short description of what the function does
#Syntax - this shows the valid syntax for the function
#Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
#Number of required arguments
**Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
**Negative values mean that the function accepts a variable number of arguments
**Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in PHP, then add it to the body of em_core_helper.php
*FIXME: Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator
*Syntax is ExpectedResult~Expression, such as:
*212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

If your test case should return an error, use NULL as the expected value, like this:
*NULL~four * / seven
*NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-13T14:52:41Z

Jweberhofer: Updated path for version 2; reformatted markup

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
=== ExpressionManager (EM) ===

==== Location ====
* Version 1.92: /classes/expressions/ExpressionManager.php
* Version 2.0: /application/helpers/expressions/em_core_helper.php

==== Purpose ====
Implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

===LimeExpressionManager (LEM)===
*Location
**Version 1.92: /classes/expressions/LimeExpressionManager.php
**Version 2.0: /application/helpers/admin/expressions/em_manager_helper.php
*Purpose - this centralizes the integration of LimeSurvey with EM
====Navigation Functions====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions
*NavigateForwards()
*NavigateBackwards()
*JumpTo()
*GetLastMoveResult() -
====Initialization Functions====
*StartSurvey() - initializes the survey, setting all variable mappings
*setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
*_CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
*ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
*_ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.
====Functions to Generate Tailored Content====
*StartProcessingPage() - called at beginning of each page
*StartProcessingGroup() - called for each group on a page
*FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
*FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function
====Response Management====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values
====Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
*SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
*SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one
====Validation Functions====
*_ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
*_ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
*_ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria
===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

===Adding Functions===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3),

The syntax for each function (func) is:
*''''func'''' => array('''details''')

The details which must be included in the array are:
#PHP function name - this is the PHP function that will be called for that func.
#JavaScript function name - this is the JavaScript function that will be called for that function
#Meaning - this is a short description of what the function does
#Syntax - this shows the valid syntax for the function
#Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
#Number of required arguments
**Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
**Negative values mean that the function accepts a variable number of arguments
**Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in PHP, then add it to the body of em_core_helper.php
*FIXME: Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator
*Syntax is ExpectedResult~Expression, such as:
*212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

If your test case should return an error, use NULL as the expected value, like this:
*NULL~four * / seven
*NULL~(5 + 7) = 8

ExpressionScript for developers

2013-05-08T15:09:22Z

Jweberhofer: Reformatted to make page readable

__TOC__

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend Expression Manager (EM).

<div class="simplebox">Note, this document is currently incomplete.</div>

==Getting Started==

The best way to get started with EM is to:
*Install [http://www.limesurvey.org/en/download LimeSurvey 1.92]
*Load and play with the Expression Manager demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**Select a survey, click Tools, then Expression Manager
*Read the documentation
**Main user documentation for [[Expression Manager|Expression Manager]]
**Expression Manager [[Expression Manager HowTos|How Tos]]

==EM Source Code Organization and Purpose==
===ExpressionManager (EM)===
*Location
**Version 1.92: /classes/expressions/ExpressionManager.php
**Version 2.0: /application/helpers/admin/expressions/em_core_helper.php
*Purpose - implements a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.
====Recursive Descent Parser (all variables and functions starting with RDP_)====
*This is the core of EM, a compiler which builds and evaluates the parse tree for the expression
*Unless you are an expert in compiler theory, you should not touch the RDP_ code.
====API Functions to the RDP====
*RegisterFunctions - an interface to add external functions to EM
*sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
*ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
*Get*() - returns information about the most recently processed expressions
===LimeExpressionManager (LEM)===
*Location
**Version 1.92: /classes/expressions/LimeExpressionManager.php
**Version 2.0: /application/helpers/admin/expressions/em_manager_helper.php
*Purpose - this centralizes the integration of LimeSurvey with EM
====Navigation Functions====
These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions
*NavigateForwards()
*NavigateBackwards()
*JumpTo()
*GetLastMoveResult() -
====Initialization Functions====
*StartSurvey() - initializes the survey, setting all variable mappings
*setVariableAndTokenMappingsForExpressionManager() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
*_CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
*ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
*_ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.
====Functions to Generate Tailored Content====
*StartProcessingPage() - called at beginning of each page
*StartProcessingGroup() - called for each group on a page
*FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
*FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function
====Response Management====
*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values
====Caching ====
LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
*SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
*SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
*SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one
====Validation Functions====
*_ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
*_ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
*_ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria
===EM-related JavaScript===
*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Version 2.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM
====JavaScript equivalents of PHP functions====
About 20 functions from phpjs.org
====Core Functions====
*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.
===EM-related Test Cases===
*Location
**Version 1.92: /classes/expressions/test/*.php
**Version 2.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of Expression Manager's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where Expression Manager properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how Expression Manager can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of sub-questions; which are relevant; and which are unanswered
****List of array filters applied, by sub-question
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
If there is whitespace after the opening brace or before the closing brace, it is ignored.
*This is so that EM can ignore embedded JavaScript.
*So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
#Escaped curly braces are ignored (e.g. '''\{''' and '''\}''')

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_'''{Q1}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'yes','no')}'''.png">
*<img src="images/mine_'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''.png">

===What does EM do with text containing expressions?===
#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionManager, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript()

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionManager (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g. for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

===Adding Functions===

Functions are stored in LimeExpressionManager::amValidFunctions[]. Some existing examples are:
*'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
*'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
*'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
*'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3),

The syntax for each function (func) is:
*''''func'''' => array('''details''')

The details which must be included in the array are:
#PHP function name - this is the PHP function that will be called for that func.
#JavaScript function name - this is the JavaScript function that will be called for that function
#Meaning - this is a short description of what the function does
#Syntax - this shows the valid syntax for the function
#Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
#Number of required arguments
**Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
**Negative values mean that the function accepts a variable number of arguments
**Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in PHP, then add it to the body of em_core_helper.php
*FIXME: Eventually we should separate out such add-on functions into their own php file

If you add a function that does not exist in JavaScript, then add it to the body of em_javascript.js

Make sure to add Unit tests for new functions to UnitTestEvaluator
*Syntax is ExpectedResult~Expression, such as:
*212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

If your test case should return an error, use NULL as the expected value, like this:
*NULL~four * / seven
*NULL~(5 + 7) = 8

RemoteControl 2 API

2012-11-03T11:29:10Z

Jweberhofer: