LimeSurvey API - Master branch

__construct()

Constructor, stores the action instance into this handle class

Parameters

$controller : AdminController

Tags

access

public

activate_survey()

Activate survey (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey to be activated

$userActivationSettings : mixed = []

Tags

access

public

activate_tokens()

Activate survey participants (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey where a survey participant list will be created for

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

An array of integer describing any additional attribute fields

Tags

access

public

add_group()

Add empty group with minimum details (RPC function)

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

add_language()

Add a survey language (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

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

add_participants()

Add participants to the survey.

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

add_quota()

Add a new quota with minimum details

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

add_response()

Add a response to the survey responses collection.

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

add_survey()

Add an empty survey with minimum details

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

copy_survey()

Copy survey (RPC function)

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

cpd_importParticipants()

Import a participant into the LimeSurvey CPDB

Parameters

$sSessionKey : int

$participants : mixed

$update : bool = false

delete_group()

Delete a group from a chosen survey (RPC function)

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

delete_language()

Delete a language from a survey (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

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

delete_participants()

Delete multiple participants from the survey participant list (RPC function)

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

delete_question()

Delete question from a survey (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iQuestionID : int

ID of the Question to delete

Tags

access

public

delete_quota()

Delete a quota

Parameters

$sSessionKey : string

Auth credentials

$iQuotaID : int

The ID of the quota to be deleted

Tags

access

public

delete_response()

Delete a response in a given survey using its Id

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

delete_survey()

Delete a survey.

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

The ID of the Survey to be deleted

Tags

access

public

export_responses()

Export responses in base64 encoded 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, @see \FormattingOptions, example : 'convertY', 'convertN', 'nValue', 'yValue', 'headerSpacesToUnderscores', 'useEMCode'

Tags

access

public

export_responses_by_token()

Export token response in a survey.

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

export_statistics()

Export survey statistics (RPC function)

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

export_timeline()

Export submission timeline (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$sType : string

(day|hour)

$dStart : string

$dEnd : string

Tags

access

public

get_available_site_settings()

Get the available site settings

Parameters

$sSessionKey : string

the session key

Tags

access

public

get_fieldmap()

Get survey fieldmap (RPC function)

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

get_group_properties()

Get the properties of a group of a survey .

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

get_language_properties()

Get survey language properties (RPC function)

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

get_participant_properties()

Get settings of a survey participant (RPC function)

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

get_question_properties()

Get properties of a question in a survey.

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

get_quota_properties()

Get quota attributes (RPC function)

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

get_response_ids()

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

Parameters

$sSessionKey : string

$iSurveyID : int

$sToken : string

get_session_key()

Create and return a session key.

Parameters

$username : string

$password : string

$plugin : string = 'Authdb'

to be used

Tags

access

public

get_site_settings()

Get a global setting

Parameters

$sSessionKey : string

Auth Credentials

$sSetttingName : string

Name of the setting to get

Tags

access

public

get_summary()

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

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

get_survey_properties()

Get survey properties (RPC function)

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

get_uploaded_files()

Obtain all uploaded files for all responses

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey

$sToken : string

Response token

$responseId : int = null

Response ID

Tags

access

public

import_group()

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

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 in the survey's base language

$sNewGroupDescription : string = null

Optional new description for the group in the survey's base language

Tags

access

public

import_question()

Import question (RPC function)

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

import_survey()

Import survey in a known format (RPC function)

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

invite_participants()

Invite participants in a survey (RPC function)

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

list_groups()

Get survey groups (RPC function)

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

list_participants()

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

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 extended attributes that we want

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

Optional conditions to limit the list, either as a key => value if key is an integer : value is used as comparaison string : sample ['tid = 2'] key=>value search value in column key : sample ['tid' => '2'] key=>array(operator,value[,value[...]]) using an operator : sample ['tid'=>['=','2']] Valid operators are ['<', '>', '>=', '<=', '=', '<>', 'LIKE', 'IN'] Only the IN operator allows for several values. All conditions are connected by AND.

Tags

access

public

list_questions()

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

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

list_quotas()

List the quotas in a survey

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey containing the quotas

Tags

access

public

list_survey_groups()

List the survey groups belonging to a user

Parameters

$sSessionKey : string

Auth credentials

$sUsername : string|null = null

(optional) username to get list of survey groups

Tags

access

public

list_surveys()

List the survey belonging to a user (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$sUsername : string|null = null

(optional) username to get list of surveys

$gsid : int|null = null

(optional) the surveys group id to get list of surveys

Tags

access

public

list_users()

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

Parameters

$sSessionKey : string = null

Auth credentials

$uid : int = null

Optional; ID of the user

$username : string = null

Optional; name of the user

mail_registered_participants()

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

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

ID of the Survey that participants belong

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

replace the default conditions, either as a key => value if key is an integer : value is used as comparaison string : sample ['tid = 2'] key=>value search value in column key : sample ['tid' => '2'] key=>array(operator,value[,value[...]]) using an operator : sample ['tid'=>['=','2']] Valid operators are ['<', '>', '>=', '<=', '=', '<>', 'LIKE', 'IN'] Only the IN operator allows for several values. All conditions are connected by AND.

Tags

access

public

release_session_key()

Close the RPC session

Parameters

$sSessionKey : string

the session key

Tags

access

public

remind_participants()

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

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

set_group_properties()

Set group properties (RPC function)

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

set_language_properties()

Set survey language properties (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

• ID of the Survey

$aSurveyLocaleData : struct

• 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

set_participant_properties()

Set properties of a survey participant (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

Id of the Survey that participants belong

$aTokenQueryProperties : struct|int

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

$aTokenData : struct

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

Tags

see

Token

for available properties

access

public

set_question_properties()

Set question properties.

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

access

public

set_quota_properties()

Set quota attributes (RPC function)

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

set_survey_properties()

Set survey properties (RPC function)

Parameters

$sSessionKey : string

Auth credentials

$iSurveyID : int

• ID of the Survey

$aSurveyData : struct

• 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

update_response()

Update a response in a given survey.

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

upload_file()

Uploads one file to be used later.

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