phpDocumentor » \remotecontrol

This class handles all methods of the RPCs

Methods

Constructor, stores the action instance into this handle class

__construct(\AdminController $controller) : void

access	public

Parameters

$controller

\AdminController

RPC Routine that launches a newly created survey.

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

The id of the survey to be activated

Returns

arrayThe result of the activation

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

access	public

Parameters

$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

Returns

arrayStatus=>OK when successfull, otherwise the error description

RPC Routine to add an empty group with minimum details.

add_group(string $sSessionKey, int $iSurveyID, string $sGroupTitle, string $sGroupDescription) : string

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Dd of the Survey to add the group

$sGroupTitle

string

Name of the group

$sGroupDescription

string

Optional description of the group

Returns

stringThe id of the new group

RPC Routine to add a survey language.

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

access	public

Parameters

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

Returns

arrayStatus=>OK when successfull, otherwise the error description

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

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

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey

$aParticipantData

\struct

Data of the participants to be added

$bCreateToken

bool

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

Returns

arrayThe values added

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

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey to insert responses

$aResponseData

\struct

The actual response

Returns

intThe response ID

RPC Routine to add an empty survey with minimum details.

add_survey(string $sSessionKey, int $iSurveyID, string $sSurveyTitle, string $sSurveyLanguage, string $sformat) : string

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

The wish 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

Returns

string

RPC Routine to delete a group of a survey .

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

Returns the id of the deleted group.

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the survey that the group belongs

$iGroupID

int

Id of the group to delete

Returns

intThe id of the deleted group

RPC Routine to delete a survey language.

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

access	public

Parameters

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

Returns

arrayStatus=>OK when successfull, otherwise the error description

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

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey that the participants belong to

$aTokenIDs

array

Id of the tokens/participants to delete

Returns

arrayResult of deletion

RPC Routine to delete a question of a survey .

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

Returns the id of the deleted question.

access	public

Parameters

$sSessionKey

string

Auth credentials

$iQuestionID

int

iQuestionID Id of the question to delete

Returns

stringId of the deleted Question

RPC Routine to delete a survey.

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

The id of the Survey to be deleted

Returns

arrayReturns Status

RPC Routine to export responses.

export_responses(string $sSessionKey, int $iSurveyID, string $sDocumentType, string $sLanguageCode, string $sCompletionStatus, string $sHeadingType, string $sResponseType, integer $iFromResponseID, integer $iToResponseID, array $aFields) : array

Returns the requested file as base64 encoded string

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey

$sDocumentType

string

pdf,csv,xls,doc

$sLanguageCode

string

The language to be used

$sCompletionStatus

string

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

$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

Returns

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

RPC routine to export statistics of a survey to a user.

export_statistics(string $sSessionKey, int $iSurveyID, string $docType, $sLanguage, string $graph) : string

Returns string - base64 encoding of the statistics.

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey

$docType

string

Type of documents the exported statistics should be $param string $sLanguage Optional language of the survey to use

$sLanguage

$graph

string

Create graph option

Returns

stringBase64 encoded string with the statistics file

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

Parameters

$sSessionKey

string

Auth credentials

$iGroupID

int

Id of the group to get properties

$aGroupSettings

array

The properties to get

Returns

arrayThe requested values

RPC Routine to get survey language properties.

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Dd of the Survey

$aSurveyLocaleSettings

array

Properties to get

$sLang

string

Language to use

Returns

arrayThe requested values

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

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey to get token properties

$iTokenID

int

Id of the participant to check

$aTokenProperties

array

The properties to get

Returns

arrayThe requested values

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

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

Returns string

access	public

Parameters

$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

Returns

arrayThe requested values

RPC routine to create a session key.

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

access	public

Parameters

$username

string

$password

string

Returns

string

RPC Routine to get settings.

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

access	public

Parameters

$sSessionKey

string

Auth Credentials

$sSetttingName

string

Name of the setting to get

Returns

stringThe requested value

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

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey to get summary

$sStatName

string

Name of the sumamry option

Returns

stringThe requested value

RPC Routine to get survey properties.

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

The id of the Survey to be checked

$aSurveySettings

array

The properties to get

Returns

array

RPC Routine to import a group - imports lsg,csv

import_group(string $sSessionKey, int $iSurveyID, string $sImportData, string $sImportDataType, string $sNewGroupName, string $sNewGroupDescription) : integer

access	public

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

Optional new name for the group

$sNewGroupDescription

string

Optional new description for the group

Returns

integeriGroupID - ID of the new group

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

import_question(string $sSessionKey, int $iSurveyID, int $iGroupID, string $sImportData, string $sImportDataType, string $sMandatory, string $sNewQuestionTitle, string $sNewqQuestion, string $sNewQuestionHelp) : integer

access	public

Parameters

$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 N)

$sNewQuestionTitle

string

Optional new title for the question

$sNewqQuestion

string

An optional new question

$sNewQuestionHelp

string

An optional new question help text

Returns

integeriQuestionID - ID of the new question

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

import_survey(string $sSessionKey, string $sImportData, string $sImportDataType, string $sNewSurveyName, integer $DestSurveyID) : integer

access	public

Parameters

$sSessionKey

string

Auth Credentials

$sImportData

string

String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive

$sImportDataType

string

lss,csv,xls or zip

$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

Returns

integeriSurveyID - ID of the new survey

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

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

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

ID of the survey that participants belong

Returns

arrayResult of the 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

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey containing the groups

Returns

arrayThe 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, bool $bUnused) : array

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

access	public

Parameters

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

Returns

arrayThe list of tokens

RPC Routine to return the ids and info of questions of a survey/group.

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

Returns array of ids and info.

access	public

Parameters

$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

Returns

arrayThe list of questions

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

list_surveys(string $sSessionKey, string $sUser) : 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 syrveys belonging to the user requesting will be shown.

access	public

Parameters

$sSessionKey

string

Auth credentials

$sUser

string

Optional username to get list of surveys

Returns

arrayThe list of surveys

Closes the RPC session

release_session_key(string $sSessionKey) : string

access	public

Parameters

$sSessionKey

string

Returns

string

RPC Routine to send reminder for participants in a survey Returns array of results of sending

remind_participants(string $sSessionKey, int $iSurveyID, int $iMinDaysBetween, int $iMaxReminders) : array

access	public

Parameters

$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

Returns

arrayResult of the action

RPC Routine to set group properties.

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

access	public

Parameters

$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

Returns

arrayOf succeeded and failed modifications according to internal validation.

RPC Routine to set survey language properties.

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

access	public

Parameters

$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

Returns

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

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

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

Returns array

access	public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the survey that participants belong

$iTokenID

int

Id of the participant to alter

$aTokenData

array\struct

Data to change

Returns

arrayResult of the change action

RPC Routine to set question properties.

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

access	public

Parameters

$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

Returns

arrayOf succeeded and failed modifications according to internal validation.

RPC Routine to set survey properties.

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

access	public

Parameters

$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

Returns

arrayOf succeeded and failed nodifications according to internal validation.

This function checks if the XML-RPC session key is valid.

_checkSessionKey(string $sSessionKey) : bool

If yes returns true, otherwise false and sends an error message with error code 1

access	protected

Parameters

$sSessionKey

string

Auth credentials

Returns

bool

Tries to login with username and password

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

access	protected

Parameters

$sUsername

string

The username

$sPassword

mixed

The Password

Returns

bool

Fills the session with necessary user info on the fly

_jumpStartSession(string $username) : bool

access	protected

Parameters

$username

string

The username

Returns

bool

Properties

$controller

$controller : \AdminController

Models

Survey

Basic model

Properties

sid	`int`	The survey id (primary key)
owner_id	`int`	Id of the user that survey belongs to
admin	`int`	The administrator of the survey
active	`varchar(Y\|N)`	Survey is active
expires	`datetime`	Date the survey is due to expire
startdate	`datetime`	Date the survey is due to start
adminemail	`varchar`	Email of the survey's administrator
anonymized	`varchar(Y\|N)`	Survey has anonymized responses enabled
faxto	`varchar`	This field is used to give a fax number on the "printable survey"
format	`varchar(G\|S\|A)`	The way the questions are shown (G-By group, S - By question, A-All)
savetimings	`varchar (Y\|N)`	Option to save timings of survey completion
template	`varchar`	template to use for Survey presentation
language	`varchar`	Language code of the surveys's basic language
additional_languages	`varchar`	"\|" separated value of additional languages codes
datestamp	`varchar(Y\|N)`	Store date information for survey responses
usecookie	`varchar(Y\|N)`	Use cookies to prevent repeated participation
allowregister	`varchar(Y\|N)`	Allow new users to register when using tokens
allowsave	`varchar(Y\|N)`	Allow surveys to be saverd for future completion
autonumber_start	`int`	Change the numbering in the surveys id
autoredirect	`varchar(Y\|N)`	Automatically load URL when survey complete
allowprev	`varchar(Y\|N)`	Show [<< Prev] button
printanswers	`varchar(Y\|N)`	Participants may print answers
ipaddr	`varchar(Y\|N)`	Save IP address of responses
refurl	`varchar(Y\|N)`	Save referrer URL of responses
datecreated	`date`	Creation time of Survey
publicstatistics	`varchar(Y\|N)`	Enable the creation of public statistics
publicgraphs	`varchar(Y\|N)`	Show graphs in public statistic
listpublic	`varchar(Y\|N)`	Publish to available surveys portal
htmlemail	`varchar(Y\|N)`	Use HTML format for token emails
sendconfirmation	`varchar(Y\|N)`	Enable Send confirmation emails
tokenanswerspersistence	`varchar(Y\|N)`	Enable token-based response persistence
assessments	`varchar(Y\|N)`	Enable assesment mode
usecaptcha	`varchar(A\|B\|C\|D\|X\|R\|S\|N)`	Enble use of captcha for public pages
usetokens	`varchar(Y\|N)`	Tokens are used
bounce_email	`varchar`	Email for delivery error notification email
attributedescriptions	`text`	Attribute description expression
emailresponseto	`text`	Send detailed admin notification email to
emailnotificationto	`text`	Send basic admin notification email to
tokenlength	`int`	Set token length to
showxquestions	`varchar(Y\|N)`	Show "There are X questions in this survey"
showgroupinfo	`varchar(B\|N\|D\|X)`	Show group name and\|or description. B-Both, N-Name, D-Description, X-None
shownoanswer	`varchar(Y\|N)`	When Yes, the No Answer will be displayed as the default option for non-mandatory single-select questions
showqnumcode	`varchar(B\|N\|C\|X)`	Show question number and code, B-Both, N-Name, C-Code, X-None
bouncetime	`int`	Time to wait for bounce enable
bounceprocessing	`varchar(L\|N\|G)`	Bounce settings to use, N-None, L-Survey settings, G-Global settings
bounceaccounttype	`varchar`	Bounce email account type (IMAP\|POP)
bounceaccounthost	`varchar`	Bounce account host
bounceaccountpass	`varchar`	Bounce account password
bounceaccountencryption	`varchar`	Bounce account encryption
bounceaccountuser	`varchar`	Bounce account username
showwelcome	`varchar(Y\|N)`	Show welcome screen
showprogress	`varchar(Y\|N)`	Allow the administrator to turn off the Progress bar
allowjumps	`varchar(Y\|N)`	When Yes, an index will be displayed on the right side. Users can jump to any section in the survey
navigationdelay	`int`	Number of seconds before Previous and Next buttons are enabled
nokeyboard	`varchar(Y\|N)`	By activating this setting there will be a virtual keyboard available for certain question types
alloweditaftercompletion	`varchar(Y\|N)`	Allow editing of answers after completion
googleanalyticsstyle	`varchar(0\|1\|2)`	0-Do not use GA, 1-Use Default, 3-Custom GA code
googleanalyticsapikey	`varchar`	API key to allow integration with Google Analytics

Survey Language settings

Model regarding language specific survey information

Properties

surveyls_survey_id	`int`	The survey_language settings id
surveyls_language	`varchar`	Language key for the survey (primary key with surveyls_survey_id)
surveyls_title	`varchar`	Title of the Survey
surveyls_description	`text`	Description of the Survey
surveyls_welcometext	`text`	Welcome text for the Survey
surveyls_endtext	`text`	End text of the Survey
surveyls_url	`varchar`	End URL
surveyls_urldescription	`varchar`	End URL Description
surveyls_email_invite_subj	`varchar`	Subject of invitation email
surveyls_email_invite	`text`	Body of invitation email
surveyls_email_remind_subj	`varchar`	Subject of reminder email
surveyls_email_remind	`text`	Body of reminder email
surveyls_email_register_subj	`varchar`	Subject of registretion email
surveyls_email_register	`text`	Body of registration email
surveyls_email_confirm_subj	`varchar`	Subject of confirmation email
surveyls_email_confirm	`text`	Body of confirmation email
surveyls_dateformat	`int(0-12)`	Format of date
surveyls_attributecaptions	`text`	Returns the token's captions
email_admin_notification_subj	`varchar`	Subject of Admin email notification
email_admin_notification		Body of admin email notification
email_admin_responses_subj	`varchar`	Subject of admin response email
email_admin_responses	`t`	Body of admin responses email
surveyls_numberformat	`int(0-1)`	Decimal mark, 0-".", 1-","

Groups

Model of question Groups

Properties

gid	`int`	Group id (Primary key with language)
sid	`int`	Survey id the group belongs to
group_name	`varchar`	Name of the group
group_order	`int`	Order that the group should appear (relative to other groups)
description	`text`	Group description
language	`varchar`	Language of the group
randomization_group	`varchar`	Identifier of randomization group
grelevance	`text`	Function to declare that the group has dependencies

Questions

Model of Question

Properties

qid	`int`	Question ID (Primary key with language)
parent_qid	`int`	Id of the question that this question belongs (if a subquestion)
sid	`int`	Id of the Survey this question belongs
gid	`int`	Id of the group this question belongs
type	`varchar`	Type of the question ()
title	`varchar`	Title for the question
question	`text`	Actual text question
preg	`text`	the optional regular expression validation criteria for the question
help	`text`	Help text for the question
other	`varchar`	It allows you to specify that an "other" option be presented in some of the list question types
mandatory	`Varchar(Y\|N)`	Question is mandatory
question_order	`int`	Order of appearance
language	`varchar`	language code of the question
scale_id	`int`	0 or 1, depending upon question type (e.g. array text will have two scales)
same_default	`int`	'Y' for true, in which case any defaultvalue set for primary language applies to other languages
relevance	`text`	This is the Boolean equation that specifies the conditions for this question

Tokens

Model of participant Tokens

Properties

tid	`int`	Dd of the token (primary key)
participant_id	`varchar`	Id from the central participants
firstname	`varchar`	Firstname of participant
lastname	`varchar`	Lastname of participant
email	`text`	Participants email
emailstatus	`text`	If ok - email is valid
token	`varchar`	Token string
language	`varchar`	Participants language
blacklisted	`varchar(Y\|N)`	Whether the participant is blacklisted
sent	`varchar`	Invitation is sent (N\|Date)
remindersent	`varchar`	Reminder is sent(N\|Date)
remindercount	`int`	Number of reminders sent
completed	`varchar(Y\|N)`	Is token used
usesleft	`int`	Number of uses left for a token
validfrom	`datetime`	Tokens start date
validuntil	`datetime`	Tokens end date
mpid	`int`	Mpid