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

RPC routine to create a session key.

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

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

access

public

Arguments

$username

string

$password

string

Response

string

Closes the RPC session

release_session_key(string $sSessionKey) : string
access

public

Arguments

$sSessionKey

string

Response

string

RPC Routine to get settings.

get_site_settings(string $sSessionKey, string $sSetttingName) : string
access

public

Arguments

$sSessionKey

string

Auth Credentials

$sSetttingName

string

Name of the setting to get

Response

string

The requested value

RPC Routine to add an empty survey with minimum details.

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

Used as a placeholder for importing groups and/or questions.

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

Question appearance format

Response

array|string|int

RPC Routine to delete a survey.

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The ID of the Survey to be deleted

Response

array

Returns Status

RPC Routine to import a survey - imports lss,csv,xls or survey zip archive.

import_survey(string $sSessionKey, string $sImportData, string $sImportDataType, string $sNewSurveyName = NULL, integer $DestSurveyID = NULL) : array|integer
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

The optional new name of the survey

$DestSurveyID

integer

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

Response

array|integer

iSurveyID - ID of the new survey

RPC Routine to get survey properties.

get_survey_properties(string $sSessionKey, int $iSurveyID, array $aSurveySettings) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The id of the Survey to be checked

$aSurveySettings

array

The properties to get

Response

array

RPC Routine to set survey properties.

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

  • ID of the Survey

$aSurveyData

array|\struct

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

Response

array

Of succeeded and failed nodifications according to internal validation

RPC Routine that launches a newly created survey.

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

The ID of the Survey to be activated

Response

array

The result of the activation

RPC routine to 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

Returns string - base64 encoding of the statistics.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$docType

string

Type of documents the exported statistics should be

$sLanguage

string

Optional language of the survey to use

$graph

string

Create graph option

$groupIDs

int|array

An OPTIONAL array (ot a single int) containing the groups we choose to generate statistics from

Response

string

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

RPC routine to get survey summary, regarding token usage and survey participation.

get_summary(string $sSessionKey, int $iSurveyID, string $sStatName) : string

Returns the requested value as string.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to get summary

$sStatName

string

Name of the summary option - valid values are 'token_count', 'token_invalid', 'token_sent', 'token_opted_out', 'token_completed', 'completed_responses', 'incomplete_responses', 'full_responses' or 'all'

Response

string

The requested value or an array of all values when $sStatName = 'all'

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 where a token table will be created for

$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 successfull, otherwise the error description

RPC Routine to delete a survey language.

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

integer

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

$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 successfull, otherwise the error description

RPC Routine to get survey language properties.

get_language_properties(string $sSessionKey, int $iSurveyID, array $aSurveyLocaleSettings, string $sLang = NULL) : array
access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$aSurveyLocaleSettings

array

Properties to get

$sLang

string

Language to use

Response

array

The requested values

RPC Routine to set survey language properties.

set_language_properties(string $sSessionKey, integer $iSurveyID, array|\struct $aSurveyLocaleData, string $sLanguage = NULL) : array
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

Status=>OK, when save successful otherwise error text.

RPC Routine to add an empty group with minimum details.

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

RPC Routine to delete a group of a 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

RPC Routine to import a group - 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

RPC Routine to 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

RPC Routine to return properties of a group of a survey .

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

Returns array of properties

access

public

Arguments

$sSessionKey

string

Auth credentials

$iGroupID

int

Id of the group to get properties

$aGroupSettings

array

The properties to get

Response

array

The requested values

RPC Routine to set group properties.

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

public

Arguments

$sSessionKey

string

Auth credentials

$iGroupID

integer

  • ID of the Survey

$aGroupData

array|\struct

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

Response

array

Of succeeded and failed modifications according to internal validation.

RPC Routine to delete a question of 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

RPC Routine to import a question - imports lsq,csv.

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

$iGroupID

int

The ID of the Group that the question will belong

$sImportData

string

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

$sImportDataType

string

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

Response

array|integer

iQuestionID - ID of the new question - Or status

RPC Routine to return properties of a question of a survey.

get_question_properties(string $sSessionKey, int $iQuestionID, array $aQuestionSettings, string $sLanguage = NULL) : array

Returns string

access

public

Arguments

$sSessionKey

string

Auth credentials

$iQuestionID

int

ID of the question to get properties

$aQuestionSettings

array

The properties to get

$sLanguage

string

Optional parameter language for multilingual questions

Response

array

The requested values

RPC Routine to set question properties.

set_question_properties(string $sSessionKey, integer $iQuestionID, array|\struct $aQuestionData, string $sLanguage = NULL) : array
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.

RPC Routine to add participants to the tokens collection of the survey.

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

Returns the inserted data including additional new information like the Token entry ID and the token string.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey

$aParticipantData

\struct

Data of the participants to be added

$bCreateToken

Response

array

The values added

RPC Routine to delete multiple participants 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

RPC Routine to return settings of a token/participant of a survey .

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey to get token properties

$aTokenQueryProperties

$aTokenProperties

array

The properties to get

Response

array

The requested values

RPC Routine to set properties of a survey participant/token.

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

Returns array

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey that participants belong

$aTokenQueryProperties

$aTokenData

array|\struct

Data to change

Response

array

Result of the change action

RPC Routine to return the ids and info of groups belonging to survey.

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

Returns array of ids and info.

access

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey containing the groups

Response

array

The list of groups

RPC Routine to return the ids and info of token/participants of a survey.

list_participants(string $sSessionKey, int $iSurveyID, int $iStart, int $iLimit = 10, bool $bUnused = false, bool|array $aAttributes = false, array|\struct $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. Parameter aAttributes is an optional array containing more attributes that may be requested

access

public

Arguments

$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 tokens, set true

$aAttributes

bool|array

The extented attributes that we want

$aConditions

array|\struct

Optional conditions to limit the list, e.g. with array('email' => 'info@example.com')

Response

array

The list of tokens

RPC Routine to 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

RPC Routine to list the ids and info of surveys belonging to a user.

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

Returns array of ids and info. 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.

access

public

Arguments

$sSessionKey

string

Auth credentials

$sUsername

string

Optional username to get list of surveys

Response

array

The list of surveys

RPC Routine to list the ids and info of users.

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

Returns array of ids and info.

Arguments

$sSessionKey

string

Auth credentials

$uid

int

Optional parameter user id.

Response

array

The list of users

RPC routine to to initialise the survey's collection of tokens 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 successfull, otherwise the error description

RPC Routine to send register mails to participants in a survey Returns array of results of sending

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

public

Arguments

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the Survey that participants belong

$overrideAllConditions

array

replace the default conditions, like this: $overrideAllConditions = Array(); $overrideAllConditions[] = 'tid = 2'; $response = $myJSONRPCClient->mail_registered_participants( $sessionKey, $survey_id, $overrideAllConditions );

Response

array

Result of the action

RPC Routine to invite participants in a survey Returns array of results of sending

invite_participants(string $sSessionKey, int $iSurveyID, array $aTokenIds = false, bool $bEmail = true) : array
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

RPC Routine to 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

Result of the action

RPC Routine to 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

RPC Routine to 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

RPC Routine to export responses.

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

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

$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

Response

array|string

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

RPC Routine to 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

RPC to 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

Tries to login with username and password

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

protected

Arguments

$sUsername

string

The username

$sPassword

string

The 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

This function checks 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

This function imports 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

This function checks 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