LimeSurvey Manual - User contributions [en]

RemoteControl

2009-11-27T10:27:26Z

Yohann:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

=Installation=

== How to install LSRC==

'''NOTE:''' It is included in Limesurvey since 1.80RC2, before 1.80RC4 it was called "japh" or "japhService"
* create a Dir "remotecontrol" in your LimeSurvey admin dir.
* copy the included files to the new directory.

== How to configure LSRC==
* first of all you have to '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes an own log. This log is helpful when implementing new features, if some function does not work, look where it hangs in this log. Should be set to false if in productive Use.
** $lsrcDebugLog, File where the log should be written to.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment if in productive Mode.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. It does not more or less than generating the target address in the wsdl with http: or https:.
** set the dirs, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl';

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" , "surveyDescription", "welcomeText", "endText", "surveyAdmins@email.adress", "Survey Adminsname", "http://end.url", "Description of End Url", "template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(m) means: Mandatory Parameter

==sCreateSurvey==

Parameters changed after 1.81+! (sVend added)
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (m) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (m) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** (m) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** (m) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int surveyID, Id of the survey from which participants will be mailed
*** (m) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (m) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (m) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (m) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (m) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

''(since 1.86)''
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.testclient.php needs to fit the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to change this vars in lsrc.client.php (between lines 20 and 30)
* If you just get a blank page on the testclient, make sure the path to the wsdl in the lsrc.client.php class is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Known Bugs (and workarounds)=
* With PHP 5.3.0, the testclient have problems to read the generated wsdl from lsrc.server.php?wsdl. You have to generate it an use the static file to test it.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

Questions - introduction

2009-11-17T11:27:25Z

Yohann:

__TOC__

=Introduction=

Once you have [[Creating a new group|created your groups]], you can start adding questions within each group. Create a new question by clicking on the add icon [[File:add.png]] on the right hand side of the "Group" menu bar.

When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "(Question Types|question type)". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs too at a later point.

=Field descriptions=
*'''Question code:''' Your ID, or number or code for the question. This field is only for quick identification for a question in export or for evaluation. Try to be consistent with your coding in this field. Planning makes your evaluation a lot easier at a later time. This field is normally not displayed to people taking the survey.
*'''Question:''' This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain the question, leave that for the "Help" field. HTML-code can be used, e.g., for including images: <img src="http://www.yourdomain.com/yourpics/pic.jpg">
*'''Help:''' This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens with the help text right beside.
*'''Question type:''' This determines the type of response the survey allows. View the [[Question types]] section for a description of the various options available.
*'''Label set:''' For some question types you can choose a set of labels. Only label sets are shown that at least contain labels in the base language of the survey.
*'''Validation:''' This feature is available on all free text type questions ("Short Free Text", "Long Free Text", "Date" or "Numerical"). You can use standard [[Using regular expressions|Regular Expressions]] in this field to validate the responses to the question, and if the responses don't validate against this expression, the user will be prompted to try again before they can progress.
*'''Other?:''' Depending upon your chosen 'question type' this option may appear. It allows you to specify that an "other" option be presented in some of the list question types.
*'''Mandatory?:''' For all question types, except the text ones, this setting allows you to require users to answer the question, before they can move on to the next question. For ranking question this means all items have to be ranked.
*'''Question attributes:''' Find out more under [[Question attributes]] Note: Adding a question attribute will loose any modifications to the questions if they have not been recorded yet by pressing the "Update Question" button.

=Importing a question=

At the bottom of the New Question Form you will find a file selection box to import a question file. Here you can import any question file (*.csv) you previously exported - for example this is useful if you want to reuse a question from another survey.

<div class="simplebox">Important: If you import a question there will always be a new question created. The original question will not be overwritten. If you want to copy a question inside the same survey it is easier to use the [[Copy Question]] function.</div>

=Information from tokens table=

You can insert information/text from the tokens table into your question so that it can show context related information. For LimeSurvey to do this, the survey needs to be set as NOT Anonymous (ie: tracked), and it needs to have a tokens table. The fields available for this are: 

{|
|{TOKEN:FIRSTNAME}||inserts the value from the "firstname" field in the tokens table
|-
|{TOKEN:LASTNAME}||inserts the value from the "lastname" field in the tokens table
|-
|{TOKEN:EMAIL}||inserts the value from the "email" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_1}||inserts the value from the "attribute_1" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_2}||inserts the value from the "attribute_2" field in the tokens table
|}

To use this functionality you must type the field text into your question exactly as listed above. For example, if Attribute 1 contains either 'worker' or 'boss', one could personalise a question:

Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?

another example with more customisation, but using javascript:

see [[Optional settings |Optional settings]] on how to allow javascript for building the questions and why it's not always a good idea.

then turn off $filterxsshtml in your config file

<syntaxhighlight lang="php" enclose="div">Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?

What do you as a {TOKEN:ATTRIBUTE_1} think about your

<script type="text/javascript" language="Javascript">

var job='{TOKEN:ATTRIBUTE_1}';

if (job=='worker') {

document.write ('bosses')

} else {

document.write('workers')

}

</script>

?</syntaxhighlight>

=Information from previous answers=

There is currently also the capacity to insert the answer of previous questions into the text of an answer with the following provisos:
**The question must have been answered in a previously displayed '''page''' in the survey - answers to questions on the current page are not available
**You refer to the exact Survey ID, Group ID and Question ID for the question to which the answer was made - in the form: {INSERTANS:SIDXGIDXQID} - ie {INSERTANS:1X2X3}. Read more under [[SGQA identifier]] to find out how to create this code.

<div class="simplebox">Important: The capacity to use perviously provided answers in questions is currently only considered "proof of concept" and so should be used with caution as future releases of LimeSurvey may involve significant changes in the way that it is used and/or works.</div>

A wizard has been integrated in the Wysiwyg HTML editor (FCKeditor), so that you can easilly insert previous answers SQGA codes: this plugin is called the LimeReplacementFields. In order to use this feature, in the FCKeditor, click on the "lime between brackets" icon, and select a question from the select box. Only answers from previous pages are displayed.

<div class="simplebox">LimeReplacementFields notice: when you want to delete a reference to a {SQGA} tag, please select all chars from the openning bracket to the closing bracket and press delete: DO NOT erase it char by char with the Delete or Backspace key otherwise the field will appear again.</div>

=Styling Questions=

Since version 1.80 it is possible to generally edit the question layout/design by using CSS. You can find more information at [http://docs.limesurvey.org/tiki-index.php?page=Templates+%2F+The+Template+Editor#Styling_questions_in_LimeSurvey_1_8 Templates/The Template Editor -> Styling questions in Limesurvey 1.8]

Questions - introduction

2009-11-17T11:17:22Z

Yohann:

__TOC__

=Introduction=

Once you have [[Creating a new group|created your groups]], you can start adding questions within each group. Create a new question by clicking on the add icon [[File:add.png]] on the right hand side of the "Group" menu bar.

When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "(Question Types|question type)". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs too at a later point.

=Field descriptions=
*'''Question code:''' Your ID, or number or code for the question. This field is only for quick identification for a question in export or for evaluation. Try to be consistent with your coding in this field. Planning makes your evaluation a lot easier at a later time. This field is normally not displayed to people taking the survey.
*'''Question:''' This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain the question, leave that for the "Help" field. HTML-code can be used, e.g., for including images: <img src="http://www.yourdomain.com/yourpics/pic.jpg">
*'''Help:''' This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens with the help text right beside.
*'''Question type:''' This determines the type of response the survey allows. View the [[Question types]] section for a description of the various options available.
*'''Label set:''' For some question types you can choose a set of labels. Only label sets are shown that at least contain labels in the base language of the survey.
*'''Validation:''' This feature is available on all free text type questions ("Short Free Text", "Long Free Text", "Date" or "Numerical"). You can use standard [[Using regular expressions|Regular Expressions]] in this field to validate the responses to the question, and if the responses don't validate against this expression, the user will be prompted to try again before they can progress.
*'''Other?:''' Depending upon your chosen 'question type' this option may appear. It allows you to specify that an "other" option be presented in some of the list question types.
*'''Mandatory?:''' For all question types, except the text ones, this setting allows you to require users to answer the question, before they can move on to the next question. For ranking question this means all items have to be ranked.
*'''Question attributes:''' Find out more under [[Question attributes]] Note: Adding a question attribute will loose any modifications to the questions if they have not been recorded yet by pressing the "Update Question" button.

=Importing a question=

At the bottom of the New Question Form you will find a file selection box to import a question file. Here you can import any question file (*.csv) you previously exported - for example this is useful if you want to reuse a question from another survey.

<div class="simplebox">Important: If you import a question there will always be a new question created. The original question will not be overwritten. If you want to copy a question inside the same survey it is easier to use the [[Copy Question]] function.</div>

=Information from tokens table=

You can insert information/text from the tokens table into your question so that it can show context related information. For LimeSurvey to do this, the survey needs to be set as NOT Anonymous (ie: tracked), and it needs to have a tokens table. The fields available for this are: 

{|
|{TOKEN:FIRSTNAME}||inserts the value from the "firstname" field in the tokens table
|-
|{TOKEN:LASTNAME}||inserts the value from the "lastname" field in the tokens table
|-
|{TOKEN:EMAIL}||inserts the value from the "email" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_1}||inserts the value from the "attribute_1" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_2}||inserts the value from the "attribute_2" field in the tokens table
|}

To use this functionality you must type the field text into your question exactly as listed above. For example, if Attribute 1 contains either 'worker' or 'boss', one could personalise a question:

Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?

another example with more customisation, but using javascript:

<syntaxhighlight lang="php" enclose="div">Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?

What do you as a {TOKEN:ATTRIBUTE_1} think about your

<script type="text/javascript" language="Javascript">

var job='{TOKEN:ATTRIBUTE_1}';

if (job=='worker') {

document.write ('bosses')

} else {

document.write('workers')

}

</script>

?</syntaxhighlight>

=Information from previous answers=

There is currently also the capacity to insert the answer of previous questions into the text of an answer with the following provisos:
**The question must have been answered in a previously displayed '''page''' in the survey - answers to questions on the current page are not available
**You refer to the exact Survey ID, Group ID and Question ID for the question to which the answer was made - in the form: {INSERTANS:SIDXGIDXQID} - ie {INSERTANS:1X2X3}. Read more under [[SGQA identifier]] to find out how to create this code.

<div class="simplebox">Important: The capacity to use perviously provided answers in questions is currently only considered "proof of concept" and so should be used with caution as future releases of LimeSurvey may involve significant changes in the way that it is used and/or works.</div>

A wizard has been integrated in the Wysiwyg HTML editor (FCKeditor), so that you can easilly insert previous answers SQGA codes: this plugin is called the LimeReplacementFields. In order to use this feature, in the FCKeditor, click on the "lime between brackets" icon, and select a question from the select box. Only answers from previous pages are displayed.

<div class="simplebox">LimeReplacementFields notice: when you want to delete a reference to a {SQGA} tag, please select all chars from the openning bracket to the closing bracket and press delete: DO NOT erase it char by char with the Delete or Backspace key otherwise the field will appear again.</div>

=Styling Questions=

Since version 1.80 it is possible to generally edit the question layout/design by using CSS. You can find more information at [http://docs.limesurvey.org/tiki-index.php?page=Templates+%2F+The+Template+Editor#Styling_questions_in_LimeSurvey_1_8 Templates/The Template Editor -> Styling questions in Limesurvey 1.8]