Models

Survey

Basic model

Properties

sid
intThe survey id (primary key)
owner_id
intId of the user that survey belongs to
admin
intThe administrator of the survey
active
varchar(Y|N) Survey is active
expires
datetimeDate the survey is due to expire
startdate
datetimeDate the survey is due to start
adminemail
varcharEmail of the survey's administrator
anonymized
varchar(Y|N) Survey has anonymized responses enabled
faxto
varcharThis 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
varchartemplate to use for Survey presentation
language
varcharLanguage 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
intChange 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
dateCreation 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
varcharEmail for delivery error notification email
attributedescriptions
textAttribute description expression
emailresponseto
textSend detailed admin notification email to
emailnotificationto
textSend basic admin notification email to
tokenlength
intSet 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
intTime to wait for bounce enable
bounceprocessing
varchar(L|N|G)Bounce settings to use, N-None, L-Survey settings, G-Global settings
bounceaccounttype
varcharBounce email account type (IMAP|POP)
bounceaccounthost
varcharBounce account host
bounceaccountpass
varcharBounce account password
bounceaccountencryption
varcharBounce account encryption
bounceaccountuser
varcharBounce 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
intNumber 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
varcharAPI key to allow integration with Google Analytics

Survey Language settings

Model regarding language specific survey information

Properties

surveyls_survey_id
intThe survey_language settings id
surveyls_language
varcharLanguage key for the survey (primary key with surveyls_survey_id)
surveyls_title
varcharTitle of the Survey
surveyls_description
textDescription of the Survey
surveyls_welcometext
textWelcome text for the Survey
surveyls_endtext
textEnd text of the Survey
surveyls_url
varcharEnd URL
surveyls_urldescription
varcharEnd URL Description
surveyls_email_invite_subj
varcharSubject of invitation email
surveyls_email_invite
textBody of invitation email
surveyls_email_remind_subj
varcharSubject of reminder email
surveyls_email_remind
textBody of reminder email
surveyls_email_register_subj
varcharSubject of registretion email
surveyls_email_register
textBody of registration email
surveyls_email_confirm_subj
varcharSubject of confirmation email
surveyls_email_confirm
textBody of confirmation email
surveyls_dateformat
int(0-12)Format of date
surveyls_attributecaptions
textReturns the token's captions
email_admin_notification_subj
varcharSubject of Admin email notification
email_admin_notification
Body of admin email notification
email_admin_responses_subj
varcharSubject of admin response email
email_admin_responses
tBody of admin responses email
surveyls_numberformat
int(0-1)Decimal mark, 0-".", 1-","

Groups

Model of question Groups

Properties

gid
intGroup id (Primary key with language)
sid
intSurvey id the group belongs to
group_name
varcharName of the group
group_order
intOrder that the group should appear (relative to other groups)
description
textGroup description
language
varcharLanguage of the group
randomization_group
varcharIdentifier of randomization group
grelevance
textFunction to declare that the group has dependencies

Questions

Model of Question

Properties

qid
intQuestion ID (Primary key with language)
parent_qid
intId of the question that this question belongs (if a subquestion)
sid
intId of the Survey this question belongs
gid
intId of the group this question belongs
type
varcharType of the question ()
title
varcharTitle for the question
question
textActual text question
preg
text the optional regular expression validation criteria for the question
help
textHelp 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
intOrder of appearance
language
varcharlanguage code of the question
scale_id
int0 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
textThis is the Boolean equation that specifies the conditions for this question

Tokens

Model of participant Tokens

Properties

tid
intDd of the token (primary key)
participant_id
varcharId from the central participants
firstname
varcharFirstname of participant
lastname
varcharLastname of participant
email
textParticipants email
emailstatus
textIf ok - email is valid
token
varcharToken string
language
varcharParticipants language
blacklisted
varchar(Y|N)Whether the participant is blacklisted
sent
varcharInvitation is sent (N|Date)
remindersent
varcharReminder is sent(N|Date)
remindercount
intNumber of reminders sent
completed
varchar(Y|N)Is token used
usesleft
intNumber of uses left for a token
validfrom
datetimeTokens start date
validuntil
datetimeTokens end date
mpid
intMpid

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 responses using specific token.

export_responses_by_token(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

$sToken

string

The token for which responses needed

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

$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, int|array $aGroupIDs) : 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

string

Language to use

$graph

string

Create graph option

$aGroupIDs

int|array

Optional IDs of groups to export statistics for

Returns

stringBase64 encoded string with the statistics file

RPC routine to export Timeline of a survey submissions progres.

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

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

access public

Parameters

$sSessionKey

string

Auth credentials

$iSurveyID

int

Id of the Survey

$sType

string

Type of statistics needes (per day or per hour). Permitted values day|hour

$dStart

string

Starting date of the period for which to extract timeline

$dEnd

string

End date of the period for which to extract timeline

Returns

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

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

$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