LimeSurvey API - Master branch

remotecontrol_handle
in package

Table of Contents

Constants

INVALID_SESSION_KEY  = 'Invalid session key'

Properties

$controller  : AdminController

Methods

__construct()  : mixed
Constructor, stores the action instance into this handle class
activate_survey()  : array<string|int, mixed>
Activate survey (RPC function)
activate_tokens()  : array<string|int, mixed>
Activate survey participants (RPC function)
add_group()  : array<string|int, mixed>|int
Add empty group with minimum details (RPC function)
add_language()  : array<string|int, mixed>
Add a survey language (RPC function)
add_participants()  : array<string|int, mixed>
Add participants to the survey.
add_quota()  : array<string|int, mixed>|int
Add a new quota with minimum details
add_response()  : int|array<string|int, mixed>
Add a response to the survey responses collection.
add_survey()  : int|array<string|int, mixed>
Add an empty survey with minimum details
copy_survey()  : array<string|int, mixed>
Copy survey (RPC function)
cpd_importParticipants()  : array<string|int, mixed>
Import a participant into the LimeSurvey CPDB
delete_group()  : array<string|int, mixed>|int
Delete a group from a chosen survey (RPC function)
delete_language()  : array<string|int, mixed>
Delete a language from a survey (RPC function)
delete_participants()  : array<string|int, mixed>
Delete multiple participants from the survey participants table (RPC function)
delete_question()  : array<string|int, mixed>|int
Delete question from a survey (RPC function)
delete_quota()  : array<string|int, mixed>|int
Delete a quota
delete_response()  : array<string|int, mixed>
Delete a response in a given survey using its Id
delete_survey()  : array<string|int, mixed>
Delete a survey.
export_responses()  : array<string|int, mixed>|string
Export responses in base64 encoded string
export_responses_by_token()  : array<string|int, mixed>|string
Export token response in a survey.
export_statistics()  : string|array<string|int, mixed>
Export survey statistics (RPC function)
export_timeline()  : array<string|int, mixed>
Export submission timeline (RPC function)
get_available_site_settings()  : array<string|int, mixed>
Get the available site settings
get_fieldmap()  : array<string|int, mixed>
Get survey fieldmap (RPC function)
get_group_properties()  : array<string|int, mixed>
Get the properties of a group of a survey .
get_language_properties()  : array<string|int, mixed>
Get survey language properties (RPC function)
get_participant_properties()  : array<string|int, mixed>
Get settings of a survey participant (RPC function)
get_question_properties()  : array<string|int, mixed>
Get properties of a question in a survey.
get_quota_properties()  : array<string|int, mixed>
Get quota attributes (RPC function)
get_response_ids()  : array<string|int, mixed>
Find response IDs given a survey ID and a token (RPC function)
get_session_key()  : string|array<string|int, mixed>
Create and return a session key.
get_site_settings()  : string|array<string|int, mixed>
Get a global setting
get_summary()  : string|array<string|int, mixed>
Get survey summary, regarding token usage and survey participation (RPC function)
get_survey_properties()  : array<string|int, mixed>
Get survey properties (RPC function)
get_uploaded_files()  : array<string|int, mixed>
Obtain all uploaded files for all responses
import_group()  : array<string|int, mixed>|int
Import a group and add to a survey (RPC function)
import_question()  : array<string|int, mixed>|int
Import question (RPC function)
import_survey()  : int|array<string|int, mixed>
Import survey in a known format (RPC function)
invite_participants()  : array<string|int, mixed>
Invite participants in a survey (RPC function)
list_groups()  : array<string|int, mixed>
Get survey groups (RPC function)
list_participants()  : array<string|int, mixed>
Return the IDs and properties of survey participants (RPC function)
list_questions()  : array<string|int, mixed>
Return the ids and info of (sub-)questions of a survey/group (RPC function)
list_quotas()  : array<string|int, mixed>
List the quotas in a survey
list_survey_groups()  : array<string|int, mixed>
List the survey groups belonging to a user
list_surveys()  : array<string|int, mixed>
List the survey belonging to a user (RPC function)
list_users()  : array<string|int, mixed>
Get list the ids and info of administration user(s) (RPC function)
mail_registered_participants()  : array<string|int, mixed>
Send e-mails to registered participants in a survey (RPC function)
release_session_key()  : string
Close the RPC session
remind_participants()  : array<string|int, mixed>
Send a reminder to participants in a survey (RPC function)
set_group_properties()  : array<string|int, mixed>
Set group properties (RPC function)
set_language_properties()  : array<string|int, mixed>
Set survey language properties (RPC function)
set_participant_properties()  : array<string|int, mixed>
Set properties of a survey participant (RPC function)
set_question_properties()  : array<string|int, mixed>
Set question properties.
set_quota_properties()  : array<string|int, mixed>
Set quota attributes (RPC function)
set_survey_properties()  : array<string|int, mixed>
Set survey properties (RPC function)
update_response()  : array<string|int, mixed>|bool
Update a response in a given survey.
upload_file()  : array<string|int, mixed>
Uploads one file to be used later.
_checkEmailFormat()  : bool
Check the email, if it's in a valid format
_checkSessionKey()  : bool
Check if the session key is valid. If yes returns true, otherwise false and sends an error message with error code 1
_doLogin()  : bool|string
Login with username and password
_jumpStartSession()  : bool
Fills the session with necessary user info on the fly

Constants

Properties

Methods

activate_survey()

Activate survey (RPC function)

public activate_survey(string $sSessionKey, int $iSurveyID[, mixed $userActivationSettings = [] ]) : array<string|int, mixed>

Return the result of the activation Failure status : Invalid Survey ID, Survey already active, Consistency check error, Activation Error, Invalid session key, No permission

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to be activated

$userActivationSettings : mixed = []
Tags
access

public

Return values
array<string|int, mixed> —

in case of success result of the activation

activate_tokens()

Activate survey participants (RPC function)

public activate_tokens(string $sSessionKey, int $iSurveyID[, array<string|int, mixed> $aAttributeFields = array() ]) : array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey where a survey participants table will be created for

$aAttributeFields : array<string|int, mixed> = array()

An array of integer describing any additional attribute fields

Tags
access

public

Return values
array<string|int, mixed> —

Status=>OK when successful, otherwise the error description

add_group()

Add empty group with minimum details (RPC function)

public add_group(string $sSessionKey, int $iSurveyID, string $sGroupTitle[, string $sGroupDescription = '' ]) : array<string|int, mixed>|int

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

Parameters
$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

Tags
access

public

Return values
array<string|int, mixed>|int —

The id of the new group - Or status

add_language()

Add a survey language (RPC function)

public add_language(string $sSessionKey, int $iSurveyID, string $sLanguage) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey for which a survey participants 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.

Tags
access

public

Return values
array<string|int, mixed> —

Status=>OK when successful, otherwise the error description

add_participants()

Add participants to the survey.

public add_participants(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aParticipantData[, bool $bCreateToken = true ]) : array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$aParticipantData : array<string|int, mixed>

Data of the participants to be added

$bCreateToken : bool = true

Optional - Defaults to true and determins if the access token automatically created

Tags
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

Return values
array<string|int, mixed> —

The values added

add_quota()

Add a new quota with minimum details

public add_quota(string $sSessionKey, int $iSurveyID, string $sQuotaName, int $iLimit[, bool $bActive = true ][, string $sAction = 'terminate' ][, bool $bAutoloadURL = false ][, string $sMessage = '' ][, string $sURL = '' ][, string $sURLDescription = '' ]) : array<string|int, mixed>|int

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

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID the Quota will belong to

$sQuotaName : string

The name of the new Quota

$iLimit : int

Quota limit

$bActive : bool = true

Whether quota is active

$sAction : string = 'terminate'

('terminate', 'confirm_terminate')

$bAutoloadURL : bool = false

Whether URL is automatically redirected if quota is triggered

$sMessage : string = ''

Message to be presented to the user

$sURL : string = ''

URL to be redirected to after finishing the quota

$sURLDescription : string = ''

Description of the URL

Tags
access

public

Return values
array<string|int, mixed>|int —

The id of the new quota - Or status

add_response()

Add a response to the survey responses collection.

public add_response(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aResponseData) : int|array<string|int, mixed>

Returns the id of the inserted survey response

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to insert responses

$aResponseData : array<string|int, mixed>

The actual response

Tags
access

public

todo

Need to clean up return array, especially the case when response was added but file not uploaded.

todo

See discussion: https://bugs.limesurvey.org/view.php?id=13794

Return values
int|array<string|int, mixed> —

The response ID or an array with status message (can include result_id)

add_survey()

Add an empty survey with minimum details

public add_survey(string $sSessionKey, int $iSurveyID, string $sSurveyTitle, string $sSurveyLanguage[, string $sformat = 'G' ]) : int|array<string|int, mixed>

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

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

Parameters
$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 = 'G'

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

Tags
access

public

Return values
int|array<string|int, mixed> —

The survey ID in case of success

copy_survey()

Copy survey (RPC function)

public copy_survey(string $sSessionKey, int $iSurveyID_org, string $sNewname[, int $DestSurveyID = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID_org : int

Id of the source survey

$sNewname : string

name of the new survey

$DestSurveyID : int = null

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

Tags
access

public

Return values
array<string|int, mixed> —

On success: new $iSurveyID in array['newsid']. On failure array with error information

cpd_importParticipants()

Import a participant into the LimeSurvey CPDB

public cpd_importParticipants(int $sSessionKey, mixed $participants[, bool $update = false ]) : array<string|int, mixed>

It stores attributes as well, if they are registered before within ui

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

Parameters
$sSessionKey : int
$participants : mixed
$update : bool = false
Return values
array<string|int, mixed> —

with status

delete_group()

Delete a group from a chosen survey (RPC function)

public delete_group(string $sSessionKey, int $iSurveyID, int $iGroupID) : array<string|int, mixed>|int

Returns the id of the deleted group.

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey that the group belongs

$iGroupID : int

ID of the group to delete

Tags
access

public

Return values
array<string|int, mixed>|int —

The ID of the deleted group or status

delete_language()

Delete a language from a survey (RPC function)

public delete_language(string $sSessionKey, int $iSurveyID, string $sLanguage) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey for which a survey participants 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.

Tags
access

public

Return values
array<string|int, mixed> —

Status=>OK when successful, otherwise the error description

delete_participants()

Delete multiple participants from the survey participants table (RPC function)

public delete_participants(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aTokenIDs) : array<string|int, mixed>

Returns the id of the deleted token

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey that the participants belong to

$aTokenIDs : array<string|int, mixed>

ID of the tokens/participants to delete

Tags
access

public

Return values
array<string|int, mixed> —

Result of deletion

delete_question()

Delete question from a survey (RPC function)

public delete_question(string $sSessionKey, int $iQuestionID) : array<string|int, mixed>|int

Returns the id of the deleted question.

Parameters
$sSessionKey : string

Auth credentials

$iQuestionID : int

ID of the Question to delete

Tags
access

public

Return values
array<string|int, mixed>|int —

ID of the deleted Question or status

delete_quota()

Delete a quota

public delete_quota(string $sSessionKey, int $iQuotaID) : array<string|int, mixed>|int
Parameters
$sSessionKey : string

Auth credentials

$iQuotaID : int

The ID of the quota to be deleted

Tags
access

public

Return values
array<string|int, mixed>|int —

The ID of the deleted quota or status

delete_response()

Delete a response in a given survey using its Id

public delete_response(string $sSessionKey, int $iSurveyID, int $iResponseID) : array<string|int, mixed>

RPC Routine to delete responses of particular id in a survey. Returns array

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

Id of the survey that participants belong

$iResponseID : int

Id of the response to delete

Tags
access

public

Return values
array<string|int, mixed> —

Result of the change action

delete_survey()

Delete a survey.

public delete_survey(string $sSessionKey, int $iSurveyID) : array<string|int, mixed>

Failure status: Invalid session key, No permission

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

The ID of the Survey to be deleted

Tags
access

public

Return values
array<string|int, mixed> —

Returns status : status are OK in case of success

export_responses()

Export responses in base64 encoded string

public export_responses(string $sSessionKey, int $iSurveyID, string $sDocumentType[, string $sLanguageCode = null ][, string $sCompletionStatus = 'all' ][, string $sHeadingType = 'code' ][, string $sResponseType = 'short' ][, int $iFromResponseID = null ][, int $iToResponseID = null ][, array<string|int, mixed> $aFields = null ][, array<string|int, mixed> $aAdditionalOptions = null ]) : array<string|int, mixed>|string
Parameters
$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 = null

(optional) The language to be used

$sCompletionStatus : string = 'all'

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

$sHeadingType : string = 'code'

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

$sResponseType : string = 'short'

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

$iFromResponseID : int = null

(optional) Frpm response id

$iToResponseID : int = null

(optional) To response id

$aFields : array<string|int, mixed> = null

(optional) Name the fields to export

$aAdditionalOptions : array<string|int, mixed> = null

(optional) Addition options for export, mainly 'convertY', 'convertN', 'nValue', 'yValue',

Tags
access

public

Return values
array<string|int, mixed>|string —

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

export_responses_by_token()

Export token response in a survey.

public export_responses_by_token(string $sSessionKey, int $iSurveyID, string $sDocumentType, array<string|int, mixed>|string $aTokens[, string $sLanguageCode = null ][, string $sCompletionStatus = 'all' ][, string $sHeadingType = 'code' ][, string $sResponseType = 'short' ][, array<string|int, mixed> $aFields = null ]) : array<string|int, mixed>|string

Returns the requested file as base64 encoded string

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$sDocumentType : string

pdf, csv, xls, doc, json

$aTokens : array<string|int, mixed>|string

The tokens (or single token) for which responses needed

$sLanguageCode : string = null

The language to be used

$sCompletionStatus : string = 'all'

Optional 'complete','incomplete' or 'all' - defaults to 'all'

$sHeadingType : string = 'code'

'code','full' or 'abbreviated' Optional defaults to 'code'

$sResponseType : string = 'short'

'short' or 'long' Optional defaults to 'short'

$aFields : array<string|int, mixed> = null

Optional Selected fields

Tags
access

public

Return values
array<string|int, mixed>|string —

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

export_statistics()

Export survey statistics (RPC function)

public export_statistics(string $sSessionKey, int $iSurveyID[, string $docType = 'pdf' ][, string $sLanguage = null ][, string $graph = '0' ][, int|array<string|int, mixed> $groupIDs = null ]) : string|array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$docType : string = 'pdf'

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

$sLanguage : string = null

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

$graph : string = '0'

(optional) Create graph option (default : no)

$groupIDs : int|array<string|int, mixed> = null

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

Tags
access

public

Return values
string|array<string|int, mixed> —

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

export_timeline()

Export submission timeline (RPC function)

public export_timeline(string $sSessionKey, int $iSurveyID, string $sType, string $dStart, string $dEnd) : array<string|int, mixed>

Returns an array of values (count and period)

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$sType : string

(day|hour)

$dStart : string
$dEnd : string
Tags
access

public

Return values
array<string|int, mixed> —

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

get_available_site_settings()

Get the available site settings

public get_available_site_settings(string $sSessionKey) : array<string|int, mixed>

Using this function you can get the available site settings.

Parameters
$sSessionKey : string

the session key

Tags
access

public

Return values
array<string|int, mixed>

get_fieldmap()

Get survey fieldmap (RPC function)

public get_fieldmap(string $sessionKey, int $surveyId[, string $language = null ]) : array<string|int, mixed>

Returns the requested survey's fieldmap in an array

Parameters
$sessionKey : string

Auth credentials

$surveyId : int

ID of the Survey

$language : string = null

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

Tags
access

public

Return values
array<string|int, mixed>

get_group_properties()

Get the properties of a group of a survey .

public get_group_properties(string $sSessionKey, int $iGroupID[, array<string|int, mixed> $aGroupSettings = null ][, string $sLanguage = null ]) : array<string|int, mixed>

Returns array of properties needed or all properties

Parameters
$sSessionKey : string

Auth credentials

$iGroupID : int

Id of the group to get properties of

$aGroupSettings : array<string|int, mixed> = null

The properties to get

$sLanguage : string = null

Optional parameter language for multilingual groups

Tags
see
QuestionGroup

for available properties

access

public

Return values
array<string|int, mixed> —

in case of success the requested values in array

get_language_properties()

Get survey language properties (RPC function)

public get_language_properties(string $sSessionKey, int $iSurveyID[, array<string|int, mixed>|null $aSurveyLocaleSettings = null ][, string|null $sLang = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$aSurveyLocaleSettings : array<string|int, mixed>|null = null

(optional) Properties to get, default to all attributes

$sLang : string|null = null

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

Tags
see
SurveyLanguageSetting

for available properties

access

public

Return values
array<string|int, mixed> —

in case of success The requested values

get_participant_properties()

Get settings of a survey participant (RPC function)

public get_participant_properties(string $sSessionKey, int $iSurveyID, array<string|int, mixed>|int $aTokenQueryProperties[, array<string|int, mixed> $aTokenProperties = null ]) : array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to get token properties

$aTokenQueryProperties : array<string|int, mixed>|int

of participant properties used to query the participant, or the token id as an integer

$aTokenProperties : array<string|int, mixed> = null

The properties to get

Tags
access

public

Return values
array<string|int, mixed> —

The requested values

get_question_properties()

Get properties of a question in a survey.

public get_question_properties(string $sSessionKey, int $iQuestionID[, array<string|int, mixed> $aQuestionSettings = null ][, string $sLanguage = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iQuestionID : int

ID of the question to get properties

$aQuestionSettings : array<string|int, mixed> = null

(optional) properties to get, default to all

$sLanguage : string = null

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

Tags
see
Question

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

access

public

Return values
array<string|int, mixed> —

The requested values

get_quota_properties()

Get quota attributes (RPC function)

public get_quota_properties(string $sSessionKey, int $iQuotaId[, array<string|int, mixed>|null $aQuotaSettings = null ][, string $sLanguage = null ]) : array<string|int, mixed>

Get properties of a quota All internal properties of a quota are available.

Parameters
$sSessionKey : string

Auth credentials

$iQuotaId : int

Quota ID

$aQuotaSettings : array<string|int, mixed>|null = null

(optional) The properties to get

$sLanguage : string = null

Optional parameter language for multilingual quotas

Tags
see
Quota

for the list of available properties

Failure status : Invalid quota ID, Invalid session key, No permission, No valid Data

access

public

Return values
array<string|int, mixed>

get_response_ids()

Find response IDs given a survey ID and a token (RPC function)

public get_response_ids(string $sSessionKey, int $iSurveyID, string $sToken) : array<string|int, mixed>
Parameters
$sSessionKey : string
$iSurveyID : int
$sToken : string
Return values
array<string|int, mixed>

get_session_key()

Create and return a session key.

public get_session_key(string $username, string $password[, string $plugin = 'Authdb' ]) : string|array<string|int, mixed>

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.
Parameters
$username : string
$password : string
$plugin : string = 'Authdb'

to be used

Tags
access

public

Return values
string|array<string|int, mixed>

get_site_settings()

Get a global setting

public get_site_settings(string $sSessionKey, string $sSetttingName) : string|array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth Credentials

$sSetttingName : string

Name of the setting to get

Tags
access

public

Return values
string|array<string|int, mixed> —

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

get_summary()

Get survey summary, regarding token usage and survey participation (RPC function)

public get_summary(string $sSessionKey, int $iSurveyID[, string $sStatName = 'all' ]) : string|array<string|int, mixed>

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
    • token_screenout All available status can be sent using all

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to get summary

$sStatName : string = 'all'

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

Tags
access

public

Return values
string|array<string|int, mixed> —

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

get_survey_properties()

Get survey properties (RPC function)

public get_survey_properties(string $sSessionKey, int $iSurveyID[, array<string|int, mixed>|null $aSurveySettings = null ]) : array<string|int, mixed>

Get properties of a survey All internal properties of a survey are available.

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

The id of the Survey to be checked

$aSurveySettings : array<string|int, mixed>|null = null

(optional) The properties to get

Tags
see
Survey

for the list of available properties

Failure status : Invalid survey ID, Invalid session key, No permission, No valid Data

access

public

Return values
array<string|int, mixed>

get_uploaded_files()

Obtain all uploaded files for all responses

public get_uploaded_files(string $sSessionKey, int $iSurveyID, string $sToken[, int $responseId = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$sToken : string

Response token

$responseId : int = null

Response ID

Tags
access

public

Return values
array<string|int, mixed> —

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

import_group()

Import a group and add to a survey (RPC function)

public import_group(string $sSessionKey, int $iSurveyID, string $sImportData, string $sImportDataType[, string $sNewGroupName = null ][, string $sNewGroupDescription = null ]) : array<string|int, mixed>|int
Parameters
$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 = null

Optional new name for the group

$sNewGroupDescription : string = null

Optional new description for the group

Tags
access

public

Return values
array<string|int, mixed>|int —

iGroupID - ID of the new group or status

import_question()

Import question (RPC function)

public 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<string|int, mixed>|int

Import a question from lsq file

Parameters
$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 = 'N'

(optional) Mandatory question option (default to No)

$sNewQuestionTitle : string = null

(optional) new title for the question

$sNewqQuestion : string = null

(optional) new question text

$sNewQuestionHelp : string = null

(optional) new question help text

Tags
access

public

Return values
array<string|int, mixed>|int —

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

import_survey()

Import survey in a known format (RPC function)

public import_survey(string $sSessionKey, string $sImportData, string $sImportDataType[, string $sNewSurveyName = null ][, int $DestSurveyID = null ]) : int|array<string|int, mixed>

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

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

Parameters
$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 = null

(optional) The optional new name of the survey

$DestSurveyID : int = null

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

Tags
access

public

Return values
int|array<string|int, mixed> —

The ID of the new survey in case of success

invite_participants()

Invite participants in a survey (RPC function)

public invite_participants(string $sSessionKey, int $iSurveyID[, array<string|int, mixed> $aTokenIds = null ][, bool $bEmail = true ][, bool $continueOnError = false ]) : array<string|int, mixed>

Returns array of results of sending. The sending stops on the first error (ie. when a token is invalid).

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the survey that participants belong

$aTokenIds : array<string|int, mixed> = null

Ids of the participant to invite

$bEmail : bool = true

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

$continueOnError : bool = false

Don't stop on first invalid participant

Tags
access

public

Return values
array<string|int, mixed> —

Result of the action

list_groups()

Get survey groups (RPC function)

public list_groups(string $sSessionKey, int $iSurveyID[, string $sLanguage = null ]) : array<string|int, mixed>

Returns the ids and all attributes of all survey groups

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey containing the groups

$sLanguage : string = null

Optional parameter language for multilingual groups

Tags
access

public

Return values
array<string|int, mixed> —

in case of success the list of groups

list_participants()

Return the IDs and properties of survey participants (RPC function)

public list_participants(string $sSessionKey, int $iSurveyID[, int $iStart = 0 ][, int $iLimit = 10 ][, bool $bUnused = false ][, bool|array<string|int, mixed> $aAttributes = false ][, array<string|int, mixed> $aConditions = array() ]) : array<string|int, mixed>

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. Starting with version 4.3.0 it is not possible anymore to query for several IDs just using an array of values - instead you have use the 'IN' operator. Examples of conditions: array ('tid => 'IN','1','3','26') array('email' => 'info@example.com') array('validuntil' => array('>', '2019-01-01 00:00:00'))

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
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to list participants

$iStart : int = 0

Start id of the token list

$iLimit : int = 10

Number of participants to return

$bUnused : bool = false

If you want unused tokens, set true

$aAttributes : bool|array<string|int, mixed> = false

The extented attributes that we want

$aConditions : array<string|int, mixed> = array()

Optional conditions to limit the list, either as a key=>value array for simple comparisons or as key=>array(operator,value[,value[...]]) using an operator. Valid operators are ['<', '>', '>=', '<=', '=', '<>', 'LIKE', 'IN'] Only the IN operator allows for several values. The same key can be used several times. All conditions are connected by AND.

Tags
access

public

Return values
array<string|int, mixed> —

The list of tokens

list_questions()

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

public list_questions(string $sSessionKey, int $iSurveyID[, int $iGroupID = null ][, string $sLanguage = null ]) : array<string|int, mixed>

Returns array of ids and info.

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to list questions

$iGroupID : int = null

Optional id of the group to list questions

$sLanguage : string = null

Optional parameter language for multilingual questions

Tags
access

public

Return values
array<string|int, mixed> —

The list of questions

list_quotas()

List the quotas in a survey

public list_quotas(string $sSessionKey, int $iSurveyID) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey containing the quotas

Tags
access

public

Return values
array<string|int, mixed> —

The list of quotas

list_survey_groups()

List the survey groups belonging to a user

public list_survey_groups(string $sSessionKey[, string|null $sUsername = null ]) : array<string|int, mixed>

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

Returns array with survey group attributes

Parameters
$sSessionKey : string

Auth credentials

$sUsername : string|null = null

(optional) username to get list of survey groups

Tags
access

public

Return values
array<string|int, mixed> —

In case of success the list of survey groups

list_surveys()

List the survey belonging to a user (RPC function)

public list_surveys(string $sSessionKey[, string|null $sUsername = null ]) : array<string|int, mixed>

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)
Parameters
$sSessionKey : string

Auth credentials

$sUsername : string|null = null

(optional) username to get list of surveys

Tags
access

public

Return values
array<string|int, mixed> —

In case of success the list of surveys

list_users()

Get list the ids and info of administration user(s) (RPC function)

public list_users([string $sSessionKey = null ][, int $uid = null ][, string $username = null ]) : array<string|int, mixed>

Returns array of ids and info.

Failure status : Invalid user id, Invalid username, No users found, Invalid session key, Permission denied (super admin is required)

Parameters
$sSessionKey : string = null

Auth credentials

$uid : int = null

Optional; ID of the user

$username : string = null

Optional; name of the user

Return values
array<string|int, mixed> —

The list of users in case of success

mail_registered_participants()

Send e-mails to registered participants in a survey (RPC function)

public mail_registered_participants(string $sSessionKey, int $iSurveyID[, array<string|int, mixed> $overrideAllConditions = array() ]) : array<string|int, mixed>

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 );
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey that participants belong

$overrideAllConditions : array<string|int, mixed> = array()

replace the default conditions

Tags
access

public

Return values
array<string|int, mixed> —

Result of the action

release_session_key()

Close the RPC session

public release_session_key(string $sSessionKey) : string

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

Parameters
$sSessionKey : string

the session key

Tags
access

public

Return values
string —

OK

remind_participants()

Send a reminder to participants in a survey (RPC function)

public remind_participants(string $sSessionKey, int $iSurveyID[, int $iMinDaysBetween = null ][, int $iMaxReminders = null ][, array<string|int, mixed> $aTokenIds = false ][, bool $continueOnError = false ]) : array<string|int, mixed>

Returns array of results of sending

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey that participants belong

$iMinDaysBetween : int = null

(optional) parameter days from last reminder

$iMaxReminders : int = null

(optional) parameter Maximum reminders count

$aTokenIds : array<string|int, mixed> = false

Ids of the participant to remind (optional filter)

$continueOnError : bool = false

Don't stop on first invalid participant

Tags
access

public

Return values
array<string|int, mixed> —

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

set_group_properties()

Set group properties (RPC function)

public set_group_properties(string $sSessionKey, int $iGroupID, array<string|int, mixed> $aGroupData) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iGroupID : int
  • ID of the Group
$aGroupData : array<string|int, mixed>
  • An array with the particular fieldnames as keys and their values to set on that particular survey
Tags
see
QuestionGroup

for available properties and restriction

Some attribute can not be set

  • sid
  • gid
access

public

Return values
array<string|int, mixed> —

Of succeeded and failed modifications according to internal validation.

set_language_properties()

Set survey language properties (RPC function)

public set_language_properties(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aSurveyLocaleData[, string $sLanguage = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int
  • ID of the Survey
$aSurveyLocaleData : array<string|int, mixed>
  • An array with the particular fieldnames as keys and their values to set on that particular survey
$sLanguage : string = null
  • Optional - Language to update - if not given the base language of the particular survey is used
Tags
see
SurveyLanguageSetting

for available properties.

Some properties can not be set

  • surveyls_language
  • surveyls_survey_id
access

public

Return values
array<string|int, mixed> —

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

set_participant_properties()

Set properties of a survey participant (RPC function)

public set_participant_properties(string $sSessionKey, int $iSurveyID, array<string|int, mixed>|int $aTokenQueryProperties, array<string|int, mixed> $aTokenData) : array<string|int, mixed>

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

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

Id of the Survey that participants belong

$aTokenQueryProperties : array<string|int, mixed>|int

of participant properties used to query the participant, or the token id as an integer

$aTokenData : array<string|int, mixed>

Data to change

Tags
see
Token

for available properties

access

public

Return values
array<string|int, mixed> —

Result of the change action

set_question_properties()

Set question properties.

public set_question_properties(string $sSessionKey, int $iQuestionID, array<string|int, mixed> $aQuestionData[, string $sLanguage = null ]) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iQuestionID : int
  • ID of the question
$aQuestionData : array<string|int, mixed>
  • An array with the particular fieldnames as keys and their values to set on that particular question
$sLanguage : string = null

Optional parameter language for multilingual questions

Tags
see
Question

for available properties.

Restricted properties:

  • qid
  • gid
  • sid
  • parent_qid
  • language
  • type
  • question_order in some condition (with dependecies)
access

public

Return values
array<string|int, mixed> —

Of succeeded and failed modifications according to internal validation.

set_quota_properties()

Set quota attributes (RPC function)

public set_quota_properties(string $sSessionKey, int $iQuotaId, array<string|int, mixed> $aQuotaData) : array<string|int, mixed>

Retuns an array containing the boolean 'success' and 'message' with either errors or Quota attributes (on success)

Parameters
$sSessionKey : string

Auth credentials

$iQuotaId : int

Quota ID

$aQuotaData : array<string|int, mixed>

Quota attributes as array eg ['active'=>1,'limit'=>100]

Tags
access

public

Return values
array<string|int, mixed> —

['success'=>bool, 'message'=>string]

set_survey_properties()

Set survey properties (RPC function)

public set_survey_properties(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aSurveyData) : array<string|int, mixed>
Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int
  • ID of the Survey
$aSurveyData : array<string|int, mixed>
  • An array with the particular fieldnames as keys and their values to set on that particular Survey
Tags
see
Survey

for the list of available properties Properties available are restricted

  • Always
    • sid
    • 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

Return values
array<string|int, mixed> —

Of succeeded and failed nodifications according to internal validation

update_response()

Update a response in a given survey.

public update_response(string $sSessionKey, int $iSurveyID, array<string|int, mixed> $aResponseData) : array<string|int, mixed>|bool

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.

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

Id of the Survey to update response

$aResponseData : array<string|int, mixed>

The actual response

Tags
access

public

Return values
array<string|int, mixed>|bool —

TRUE(bool) on success. Array with error status on failure.

upload_file()

Uploads one file to be used later.

public upload_file(string $sSessionKey, int $iSurveyID, string $sFieldName, string $sFileName, string $sFileContent) : array<string|int, mixed>

Returns the metadata on success.

Parameters
$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to insert file

$sFieldName : string

the Field to upload file

$sFileName : string

the uploaded file name

$sFileContent : string

the uploaded file content encoded as BASE64

Tags
access

public

Return values
array<string|int, mixed> —

The file metadata with final upload path or error description

_checkEmailFormat()

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

protected _checkEmailFormat( $sEmail) : bool
Parameters
$sEmail :
Return values
bool

_checkSessionKey()

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

protected _checkSessionKey(string $sSessionKey) : bool
Parameters
$sSessionKey : string

Auth credentials

Tags
access

protected

Return values
bool

_doLogin()

Login with username and password

protected _doLogin(string $sUsername, string $sPassword, string $sPlugin) : bool|string
Parameters
$sUsername : string

username

$sPassword : string

password

$sPlugin : string

plugin to be used

Tags
access

protected

Return values
bool|string

_jumpStartSession()

Fills the session with necessary user info on the fly

protected _jumpStartSession(string $username) : bool
Parameters
$username : string

The username

Tags
access

protected

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results