remotecontrol_handle

This class handles all methods of the RemoteControl 2 API

Methods

Constructor, stores the action instance into this handle class

__construct(\AdminController $controller) : void
access

public

Arguments

$controller

\AdminController

Create and return a session key.

get_session_key(string $username, string $password) : string|array

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

  • In case of success : Return the session key in string
  • In case of 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.
access

public

Arguments

$username

string

$password

string

Response

string|array

Close the RPC session

release_session_key(string $sSessionKey) : string

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

access

public

Arguments

$sSessionKey

string

the session key

Response

string

OK

Get a global setting

get_site_settings(string $sSessionKey, string $sSetttingName) : string|array

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

access

public

Arguments

$sSessionKey

string

Auth Credentials

$sSetttingName

string

Name of the setting to get

Response

string|array

The requested value or an array with the error in case of error

Add an empty survey with minimum details

add_survey(string $sSessionKey, int $iSurveyID, string $sSurveyTitle, string $sSurveyLanguage, string $sformat = 'G') : int|array

This just tries to create an empty survey with the minimal settings.

Failure status: Invalid session key, No permission, Faulty parameters, Creation Failed result

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The desired ID of the Survey to add

$sSurveyTitle

string

Title of the new Survey

$sSurveyLanguage

string

Default language of the Survey

$sformat

string

(optional) Question appearance format (A, G or S) for "All on one page", "Group by Group", "Single questions", default to group by group (G)

Response

int|array

The survey id in case of success

Delete a survey.

delete_survey(string $sSessionKey, int $iSurveyID) : array

Failure status: Invalid session key, No permission

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The ID of the Survey to be deleted

Response

array

Returns status : status are OK in case of success

Import a survey in a known format

import_survey(string $sSessionKey, string $sImportData, string $sImportDataType, string $sNewSurveyName = NULL, integer $DestSurveyID = NULL) : int|array

Allow importing lss, csv, xls or survey zip archive in BASE 64 encoded.

Failure status: Invalid session key, No permission, The import error

access

public

Arguments

$sSessionKey

string

Auth Credentials

$sImportData

string

String containing the BASE 64 encoded data of a lss, csv, txt or survey lsa archive

$sImportDataType

string

lss, csv, txt or lsa

$sNewSurveyName

string

(optional) The optional new name of the survey

$DestSurveyID

integer

(optional) This is the new ID of the survey - if already used a random one will be taken instead

Response

int|array

The ID of the new survey in case of success

Get properties of a survey

get_survey_properties(string $sSessionKey, int $iSurveyID, array|null $aSurveySettings = null) : array

All internal properties of a survey are available.

see \Survey

for the list of available properties Failure status : Invalid survey ID, Invalid session key, No permission, No valid Data

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The id of the Survey to be checked

$aSurveySettings

array|null

(optional) The properties to get

Response

array

Set survey properties.

set_survey_properties(string $sSessionKey, integer $iSurveyID, array|\struct $aSurveyData) : array
see \Survey

for the list of available properties Properties available are restricted * Always * sid * owner_id * active * language * additional_languages * If survey is active * anonymized * datestamp * savetimings * ipaddr * refurl In case of partial success : return an array with key as properties and value as boolean , true if saved with success. Failure status : Invalid survey ID, Invalid session key, No permission, No valid Data

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

The ID of the Survey

$aSurveyData

array|\struct

An array with the particular properties as keys and their values to set on that particular Survey

Response

array

In case of success Notifications according to internal validation of each params set

Activate an existing survey

activate_survey(string $sSessionKey, int $iSurveyID) : array

Return the result of the activation Failure status : Invalid Survey ID, Activation Error, Invalid session key, No permission

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to be activated

Response

array

in case of success result of the activation

Export statistics of a survey to a user.

export_statistics(string $sSessionKey, int $iSurveyID, string $docType = 'pdf', string $sLanguage = null, string $graph = '0', int|array $groupIDs = null) : string

Allow to export statistics available Returns string - base64 encoding of the statistics.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$docType

string

(optional) Type of documents the exported statistics should be (pdf|xls|html)

$sLanguage

string

(optional) language of the survey to use (default from Survey)

$graph

string

(optional) Create graph option (default : no)

$groupIDs

int|array

(optional) array or integer containing the groups we choose to generate statistics from

Response

string

in case of success : Base64 encoded string with the statistics file

RPC Routine to export submission timeline.

export_timeline(string $sSessionKey, int $iSurveyID, string $sType, string $dStart, string $dEnd) : array

Returns an array of values (count and period)

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$sType

string

(day|hour)

$dStart

string

$dEnd

string

Response

array

On success: The timeline. On failure array with error information

Get survey summary, regarding token usage and survey participation.

get_summary(string $sSessionKey, int $iSurveyID, string $sStatName = 'all') : string|array

Returns the requested value as string, or all status in an array

Available status are * For Survey stats * completed_responses * incomplete_responses * full_responses * For token part * token_count * token_invalid * token_sent * token_opted_out * token_completed All available status can be sent using all

Failure status : No available data, No such property, Invalid session key, No permission

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to get summary

$sStatName

string

(optional) Name of the summary option, or all to send all in an array (all by default)

Response

string|array

in case of success the requested value or an array of all values

RPC Routine to add a survey language.

add_language(string $sSessionKey, integer $iSurveyID, string $sLanguage) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

ID of the Survey for which a token table will be created

$sLanguage

string

A valid language shortcut to add to the current Survey. If the language already exists no error will be given.

Response

array

Status=>OK when successful, otherwise the error description

RPC Routine to delete a language from a survey.

delete_language(string $sSessionKey, integer $iSurveyID, string $sLanguage) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

ID of the Survey for which a token table will be created

$sLanguage

string

A valid language shortcut to delete from the current Survey. If the language does not exist in that Survey no error will be given.

Response

array

Status=>OK when successful, otherwise the error description

Get survey language properties.

get_language_properties(string $sSessionKey, int $iSurveyID, array|null $aSurveyLocaleSettings = null, string|null $sLang = null) : array
see \SurveyLanguageSetting

for available properties

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$aSurveyLocaleSettings

array|null

(optional) Properties to get, default to all attributes

$sLang

string|null

(optional) Language to use, default to Survey->language

Response

array

in case of success The requested values

Set survey language properties.

set_language_properties(string $sSessionKey, integer $iSurveyID, array|\struct $aSurveyLocaleData, string $sLanguage = NULL) : array
see \SurveyLanguageSetting

for available properties. Some properties can not be set * surveyls_language * surveyls_survey_id

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

  • ID of the Survey

$aSurveyLocaleData

array|\struct

  • An array with the particular fieldnames as keys and their values to set on that particular survey

$sLanguage

string

  • Optional - Language to update - if not give the base language of the particular survey is used

Response

array

in case of success 'status'=>'OK', when save successful otherwise error text.

Add an empty group with minimum details to a chosen survey.

add_group(string $sSessionKey, int $iSurveyID, string $sGroupTitle, string $sGroupDescription = '') : array|int

Used as a placeholder for importing questions. Returns the groupid of the created group.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to add the group

$sGroupTitle

string

Name of the group

$sGroupDescription

string

Optional description of the group

Response

array|int

The id of the new group - Or status

Delete a group from a chosen survey .

delete_group(string $sSessionKey, int $iSurveyID, int $iGroupID) : array|int

Returns the id of the deleted group.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey that the group belongs

$iGroupID

int

ID of the group to delete

Response

array|int

The ID of the deleted group or status

Import a group and add to a chosen survey - imports lsg,csv

import_group(string $sSessionKey, int $iSurveyID, string $sImportData, string $sImportDataType, string $sNewGroupName = NULL, string $sNewGroupDescription = NULL) : array|integer
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The ID of the Survey that the group will belong

$sImportData

string

String containing the BASE 64 encoded data of a lsg,csv

$sImportDataType

string

lsg,csv

$sNewGroupName

string

Optional new name for the group

$sNewGroupDescription

string

Optional new description for the group

Response

array|integer

iGroupID - ID of the new group or status

Find response IDs given a survey ID and a token.

get_response_ids(string $sSessionKey, int $iSurveyID, string $sToken) 

Arguments

$sSessionKey

string

$iSurveyID

int

$sToken

string

Get the properties of a group of a survey .

get_group_properties(string $sSessionKey, int $iGroupID, array $aGroupSettings = null) : array

Returns array of properties needed or all properties

see \QuestionGroup

for available properties

access

public

Arguments

$sSessionKey

string

Auth credentials

$iGroupID

int

Id of the group to get properties of

$aGroupSettings

array

The properties to get

Response

array

in case of success the requested values in array

Set group properties.

set_group_properties(string $sSessionKey, integer $iGroupID, array|\struct $aGroupData) : array
see \QuestionGroup

for available properties and restriction Some attribute can not be set * sid * gid

access

public

Arguments

$sSessionKey

string

Auth credentials

$iGroupID

integer

ID of the Survey

$aGroupData

array|\struct

array with the particular fieldnames as keys and their values to set on that particular survey

Response

array

in case of partial success : return array of each properties with status according to internal validation.

Delete a question from a survey .

delete_question(string $sSessionKey, $iQuestionID) : array|int

Returns the id of the deleted question.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iQuestionID

Response

array|int

ID of the deleted Question or status

Import a question from lsq file

import_question(string $sSessionKey, int $iSurveyID, int $iGroupID, string $sImportData, string $sImportDataType, string $sMandatory = 'N', string $sNewQuestionTitle = NULL, string $sNewqQuestion = NULL, string $sNewQuestionHelp = NULL) : array|integer
access

public

Arguments

$sSessionKey

string

$iSurveyID

int

The ID of the Survey that the question will belong to

$iGroupID

int

The ID of the Group that the question will belong to

$sImportData

string

String containing the BASE 64 encoded data of a lsq

$sImportDataType

string

lsq

$sMandatory

string

(optional) Mandatory question option (default to No)

$sNewQuestionTitle

string

(optional) new title for the question

$sNewqQuestion

string

(optional) new question text

$sNewQuestionHelp

string

(optional) new question help text

Response

array|integer

The id of the new question in case of success. Array if errors

Get properties of a question in a survey.

get_question_properties(string $sSessionKey, int $iQuestionID, array $aQuestionSettings = null, string $sLanguage = null) : array
see \Question

for available properties. Some more properties are available_answers, subquestions, attributes, attributes_lang, answeroptions, defaultvalue

access

public

Arguments

$sSessionKey

string

Auth credentials

$iQuestionID

int

ID of the question to get properties

$aQuestionSettings

array

(optional) properties to get, default to all

$sLanguage

string

(optional) parameter language for multilingual questions, default are \Survey->language

Response

array

The requested values

Set question properties.

set_question_properties(string $sSessionKey, integer $iQuestionID, array|\struct $aQuestionData, string $sLanguage = NULL) : array
see \Question

for available properties. Restricted properties: * qid * gid * sid * parent_qid * language * type * question_order in some condition (with dependecies)

access

public

Arguments

$sSessionKey

string

Auth credentials

$iQuestionID

integer

  • ID of the question

$aQuestionData

array|\struct

  • 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

Response

array

Of succeeded and failed modifications according to internal validation.

Add participants to the tokens collection of the survey.

add_participants(string $sSessionKey, int $iSurveyID, \struct $aParticipantData, bool $bCreateToken = true) : array

The parameters $aParticipantData is a 2 dimensionnal array containing needed participant data.

see \Token

for all available attribute,

example

[ {"email":"me@example.com","lastname":"Bond","firstname":"James"},{"email":"me2@example.com","attribute_1":"example"} ] Returns the inserted data including additional new information like the Token entry ID and the token string. In case of errors in some data, return it in errors.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$aParticipantData

\struct

Data of the participants to be added

$bCreateToken

bool

(optional) generate the new token, defaults to true

Response

array

in case of partial success the final participant data

Delete multiple participants from the token table of a survey.

delete_participants(string $sSessionKey, int $iSurveyID, array $aTokenIDs) : array

Returns the id of the deleted token

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey that the participants belong to

$aTokenIDs

array

ID of the tokens/participants to delete

Response

array

Result of deletion

Get settings of a token/participant of a survey.

get_participant_properties(string $sSessionKey, int $iSurveyID, $aTokenQueryProperties, array $aTokenProperties = null) : array

Allow to request for a specific participant. If more than one participant is returned with specified attribute(s) an error is returned.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to get token properties

$aTokenQueryProperties

$aTokenProperties

array

(optional) properties to get, default to all

Response

array

The requested values

Set properties of a survey participant/token.

set_participant_properties(string $sSessionKey, int $iSurveyID, $aTokenQueryProperties, array $aTokenData) : array

Allow to set properties about a specific participant, only one particpant can be updated.

see \Token

for available properties

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey that participants belongs to

$aTokenQueryProperties

$aTokenData

array

Data to change

Response

array

Result of the change action

Return the ids and all attributes of groups belonging to survey.

list_groups(string $sSessionKey, int $iSurveyID) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey containing the groups

Response

array

in case of success the list of groups

Return the ids and propertries of token/participants of a survey.

list_participants(string $sSessionKey, int $iSurveyID, int $iStart, int $iLimit = 10, bool $bUnused = false, false|array $aAttributes = false, array $aConditions = array()) : array

if $bUnused is true, user will get the list of uncompleted tokens (token_return functionality). Parameters iStart and iLimit are used to limit the number of results of this call.

By default return each participant with basic information * tid : the token id * token : the token for this participant * participant_info : an array with firstname, lastname and email Parameter $aAttributes can be used to add more attribute in participant_info array

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to list participants

$iStart

int

(optional) start id of the token list, default to 0

$iLimit

int

(optional) number of participants to return, default to 10

$bUnused

bool

(optional) If you want unused tokens (not completed survey), default to false

$aAttributes

false|array

The extented attributes that we want

$aConditions

array

(optional) conditions to limit the list, @example ['email' => 'info@example.com']

Response

array

The list of tokens

Return the ids and info of (sub-)questions of a survey/group.

list_questions(string $sSessionKey, int $iSurveyID, int $iGroupID = NULL, string $sLanguage = NULL) : array

Returns array of ids and info.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to list questions

$iGroupID

int

Optional id of the group to list questions

$sLanguage

string

Optional parameter language for multilingual questions

Response

array

The list of questions

List the survey belonging to a user

list_surveys(string $sSessionKey, string|null $sUsername = NULL) : array

If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null) Else only the surveys belonging to the user requesting will be shown.

Returns array with * sid the ids of survey * surveyls_title the title of the survey * startdate start date * expires expiration date * active if survey is active (Y) or not (!Y)

access

public

Arguments

$sSessionKey

string

Auth credentials

$sUsername

string|null

(optional) username to get list of surveys

Response

array

In case of success the list of surveys

Get list the ids and info of users.

list_users(string $sSessionKey = null, int $uid = FALSE) : array

Returns array of ids and info.

Failure status : No users found, Invalid session key, No permission (super admin is required)

Arguments

$sSessionKey

string

Auth credentials

$uid

int

Optional parameter user id.

Response

array

The list of users in case of success

Initialise the token system of a survey where new participant tokens may be later added.

activate_tokens(string $sSessionKey, integer $iSurveyID, array $aAttributeFields = array()) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

ID of the Survey where a token table will be created for

$aAttributeFields

array

An array of integer describing any additional attribute fields

Response

array

Status=>OK when successful, otherwise the error description

Send register mails to participants in a survey

mail_registered_participants(string $sSessionKey, int $iSurveyID, array $overrideAllConditions = array()) : array

Returns array of results of sending

Default behaviour is to send register emails to not invited, not reminded, not completed and in valid frame date participant.

$overrideAllConditions replaces this default conditions for selecting the participants. A typical use case is to select only one participant $overrideAllConditions = Array(); $overrideAllConditions[] = 'tid = 2'; $response = $myJSONRPCClient->mail_registered_participants( $sessionKey, $survey_id, $overrideAllConditions );

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey that participants belong

$overrideAllConditions

array

replace the default conditions

Response

array

Result of the action

Invite participants in a survey

invite_participants(string $sSessionKey, int $iSurveyID, array $aTokenIds = false, bool $bEmail = true) : array

Returns array of results of sending

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the survey that participants belong

$aTokenIds

array

Ids of the participant to invite

$bEmail

bool

Send only pending invites (TRUE) or resend invites only (FALSE)

Response

array

Result of the action

Send a reminder to participants in a survey Returns array of results of sending

remind_participants(string $sSessionKey, int $iSurveyID, int $iMinDaysBetween = null, int $iMaxReminders = null, array $aTokenIds = false) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey that participants belong

$iMinDaysBetween

int

(optional) parameter days from last reminder

$iMaxReminders

int

(optional) parameter Maximum reminders count

$aTokenIds

array

Ids of the participant to remind (optional filter)

Response

array

in case of success array of result of each email send action and count of invitations left to send in status key

Add a response to the survey responses collection.

add_response(string $sSessionKey, int $iSurveyID, \struct $aResponseData) : int

Returns the id of the inserted survey response

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to insert responses

$aResponseData

\struct

The actual response

Response

int

The response ID

Update a response in a given survey.

update_response(string $sSessionKey, int $iSurveyID, \struct $aResponseData) : mixed

Routine supports only single response updates. Response to update will be identified either by the response id, or the token if response id is missing. Routine is only applicable for active surveys with alloweditaftercompletion = Y.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey to update response

$aResponseData

\struct

The actual response

Response

mixed

TRUE(bool) on success. errormessage on error

Export responses in base64 encoded string

export_responses(string $sSessionKey, int $iSurveyID, string $sDocumentType, string $sLanguageCode = null, string $sCompletionStatus = 'all', string $sHeadingType = 'code', string $sResponseType = 'short', integer $iFromResponseID = null, integer $iToResponseID = null, array $aFields = null) : array|string
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$sDocumentType

string

any format available by plugins (for example : pdf, csv, xls, doc, json)

$sLanguageCode

string

(optional) The language to be used

$sCompletionStatus

string

(optional) 'complete','incomplete' or 'all' - defaults to 'all'

$sHeadingType

string

(optional) 'code','full' or 'abbreviated' Optional defaults to 'code'

$sResponseType

string

(optional)'short' or 'long' Optional defaults to 'short'

$iFromResponseID

integer

(optional)

$iToResponseID

integer

(optional)

$aFields

array

(optional) Selected fields

Response

array|string

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

Export token response in a survey.

export_responses_by_token(string $sSessionKey, int $iSurveyID, string $sDocumentType, string $sToken, string $sLanguageCode = null, string $sCompletionStatus = 'all', string $sHeadingType = 'code', string $sResponseType = 'short', array $aFields = null) : array|string

Returns the requested file as base64 encoded string

access

public

Arguments

$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

Response

array|string

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

Obtain all uploaded files for a single response

get_uploaded_files(string $sSessionKey, int $iSurveyID, int $sToken) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$sToken

int

Response token

Response

array

On success: array containing all uploads of the specified response On failure: array with error information

Login with username and password

_doLogin(string $sUsername, string $sPassword) : bool
access

protected

Arguments

$sUsername

string

username

$sPassword

string

password

Response

bool

Fills the session with necessary user info on the fly

_jumpStartSession(string $username) : bool
access

protected

Arguments

$username

string

The username

Response

bool

Check if the session key is valid. If yes returns true, otherwise false and sends an error message with error code 1

_checkSessionKey(string $sSessionKey) : bool
access

protected

Arguments

$sSessionKey

string

Auth credentials

Response

bool

Import a participant into the LimeSurvey cpd. It stores attributes as well, if they are registered before within ui

cpd_importParticipants(int $sSessionKey, array $aParticipants) : array

Call the function with $response = $myJSONRPCClient->cpd_importParticipants( $sessionKey, $aParticipants);

Arguments

$sSessionKey

int

$aParticipants

array

[[0] => ["email"=>"dummy-02222@limesurvey.com","firstname"=>"max","lastname"=>"mustermann"]]

Response

array

with status

Check the email, if it's in a valid format

_checkEmailFormat(mixed $sEmail) : bool

Arguments

$sEmail

mixed

Response

bool

Properties

controller

controller : \AdminController
var

Type(s)

\AdminController