RemoteControl is available using json for transport and exposes the following functionality:
- activate_survey
/**
* Activate survey (RPC function)
*
* Return the result of the activation
* Failure status : Invalid Survey ID, Constistency check error, Activation Error, Invalid session key, No permission
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to be activated
* @return array in case of success result of the activation
*/- activate_tokens
/**
* Activate survey participants (RPC function)
*
* Initialise the survey participant table of a survey where new participant tokens may be later added.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iSurveyID ID of the Survey where a survey participants table will be created for
* @param array $aAttributeFields An array of integer describing any additional attribute fields
* @return array Status=>OK when successful, otherwise the error description
*/- add_group
/**
* Add empty page with minimum details (RPC function)
*
* Used as a placeholder for importing questions.
* Returns the groupid of the created page.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to add the group
* @param string $sGroupTitle Name of the group
* @param string $sGroupDescription Optional description of the group
* @return array|int The id of the new group - Or status
*/- add_language
/**
* Add a survey language (RPC function)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iSurveyID ID of the Survey for which a survey participants table will be created
* @param string $sLanguage A valid language shortcut to add to the current Survey. If the language already exists no error will be given.
* @return array Status=>OK when successful, otherwise the error description
*/- add_participants
/**
* Add participants to the survey.
*
* The parameters $aParticipantData is a 2 dimensionnal array containing needed participant data.
* @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
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param array $aParticipantData Data of the participants to be added
* @param bool $bCreateToken Optional - Defaults to true and determins if the access token automatically created
* @return array The values added
*/- add_response
/**
* Add a response to the survey responses collection.
*
* Returns the id of the inserted survey response
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to insert responses
* @param array $aResponseData The actual response
* @return int|array The response ID or an array with status message (can include result_id)
* @todo Need to clean up return array, especially the case when response was added but file not uploaded.
* @todo See discussion: https://bugs.digitellsurvey.org/view.php?id=13794
*/- add_survey
/**
* Add an empty survey with minimum details
*
* This just tries to create an empty survey with the minimal settings.
*
* Failure status: Invalid session key, No permission, Faulty parameters, Creation Failed result
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID The desired ID of the Survey to add
* @param string $sSurveyTitle Title of the new Survey
* @param string $sSurveyLanguage Default language of the Survey
* @param string $sformat (optional) Question appearance format (A, G or S) for "All on one page", "Group by Group", "Single questions", default to group by group (G)
* @return int|array The survey id in case of success
*/- copy_survey
/**
* Copy survey (RPC function)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID_org Id of the source survey
* @param string $sNewname name of the new survey
* @return array On success: new $iSurveyID in array['newsid']. On failure array with error information
* */- cpd_importParticipants
/**
* Import a participant into the DigitellSurvey CPDB
*
* It stores attributes as well, if they are registered before within ui
*
* Call the function with $response = $myJSONRPCClient->cpd_importParticipants( $sessionKey, $aParticipants);
*
* @param int $sSessionKey
* @param array $aParticipants
* [[0] => ["email"=>"dummy-02222@digitellsurvey.com","firstname"=>"max","lastname"=>"mustermann"]]
* @return array with status
*/- delete_group
/**
* Delete a page from a chosen survey (RPC function)
*
* Returns the id of the deleted group.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey that the group belongs
* @param int $iGroupID ID of the group to delete
* @return array|int The ID of the deleted group or status
*/- delete_language
/**
* Delete a language from a survey (RPC function)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iSurveyID ID of the Survey for which a survey participants table will be created
* @param string $sLanguage A valid language shortcut to delete from the current Survey. If the language does not exist in that Survey no error will be given.
* @return array Status=>OK when successful, otherwise the error description
*/- delete_participants
/**
* Delete multiple participants from the survey participants table (RPC function)
*
* Returns the id of the deleted token
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey that the participants belong to
* @param array $aTokenIDs ID of the tokens/participants to delete
* @return array Result of deletion
*/- delete_question
/**
* Delete question from a survey (RPC function)
*
* Returns the id of the deleted question.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iQuestionID ID of the Question to delete
* @return array|int ID of the deleted Question or status
*/- delete_survey
/**
* Delete a survey.
*
* Failure status: Invalid session key, No permission
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID The ID of the Survey to be deleted
* @return array Returns status : status are OK in case of success
*/- export_responses
/**
* Export responses in base64 encoded string
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param string $sDocumentType any format available by plugins (for example : pdf, csv, xls, doc, json)
* @param string $sLanguageCode (optional) The language to be used
* @param string $sCompletionStatus (optional) 'complete','incomplete' or 'all' - defaults to 'all'
* @param string $sHeadingType (optional) 'code','full' or 'abbreviated' Optional defaults to 'code'
* @param string $sResponseType (optional)'short' or 'long' Optional defaults to 'short'
* @param integer $iFromResponseID (optional)
* @param integer $iToResponseID (optional)
* @param array $aFields (optional) Selected fields
* @return array|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.
*
* Returns the requested file as base64 encoded string
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param string $sDocumentType pdf, csv, xls, doc, json
* @param string $sToken The token for which responses needed
* @param string $sLanguageCode The language to be used
* @param string $sCompletionStatus Optional 'complete','incomplete' or 'all' - defaults to 'all'
* @param string $sHeadingType 'code','full' or 'abbreviated' Optional defaults to 'code'
* @param string $sResponseType 'short' or 'long' Optional defaults to 'short'
* @param array $aFields Optional Selected fields
* @return array|string On success: Requested file as base 64-encoded string. On failure array with error information
*
*/- export_statistics
/**
* Export survey statistics (RPC function)
*
* Allow to export statistics available Returns string - base64 encoding of the statistics.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param string $docType (optional) Type of documents the exported statistics should be (pdf|xls|html)
* @param string $sLanguage (optional) language of the survey to use (default from Survey)
* @param string $graph (optional) Create graph option (default : no)
* @param int|array $groupIDs (optional) array or integer containing the groups we choose to generate statistics from
* @return string|array in case of success : Base64 encoded string with the statistics file
*/- export_timeline
/**
* Export submission timeline (RPC function)
*
* Returns an array of values (count and period)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param string $sType (day|hour)
* @param string $dStart
* @param string $dEnd
* @return array On success: The timeline. On failure array with error information
* */- get_group_properties
/**
* Get the properties of a survey page (RPC function)
*
* Returns array of properties needed or all properties
* @see \QuestionGroup for available properties
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iGroupID Id of the group to get properties of
* @param array $aGroupSettings The properties to get
* @return array in case of success the requested values in array
*/- get_language_properties
/**
* Get survey language properties (RPC function)
*
* @see \SurveyLanguageSetting for available properties
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param array|null $aSurveyLocaleSettings (optional) Properties to get, default to all attributes
* @param string|null $sLang (optional) Language to use, default to Survey->language
* @return array in case of success The requested values
*/- get_participant_properties
/**
* Get settings of a survey participant (RPC function)
*
* Allow to request for a specific participant. If more than one participant is returned with specified attribute(s) an error is returned.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to get token properties
* @param array|int $aTokenQueryProperties of participant properties used to query the participant, or the token id as an integer
* @param array $aTokenProperties The properties to get
* @return array The requested values
*/- get_question_properties
/**
* Get properties of a question in a survey.
*
* @see \Question for available properties.
* Some more properties are available_answers, subquestions, attributes, attributes_lang, answeroptions, answeroptions_multiscale, defaultvalue
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iQuestionID ID of the question to get properties
* @param array $aQuestionSettings (optional) properties to get, default to all
* @param string $sLanguage (optional) parameter language for multilingual questions, default are \Survey->language
* @return array The requested values
*/- get_response_ids
/**
* Find response IDs given a survey ID and a token (RPC function)
*
* @param string $sSessionKey
* @param int $iSurveyID
* @param string $sToken
* @return array
*/- get_session_key
/**
* Create and return a session key.
*
* 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.
*
* @access public
* @param string $username
* @param string $password
* @param string $plugin to be used
* @return string|array
*/- get_site_settings
/**
* Get a global setting
*
* Function to query site settings. Can only be used by super administrators.
*
* @access public
* @param string $sSessionKey Auth Credentials
* @param string $sSetttingName Name of the setting to get
* @return string|array 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)
*
* 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
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to get summary
* @param string $sStatName (optional) Name of the summary option, or all to send all in an array (all by default)
* @return string|array in case of success the requested value or an array of all values
*/- get_survey_properties
/**
* Get survey properties (RPC function)
*
* Get properties of a survey
* All internal properties of a survey are available.
* @see \Survey for the list of available properties
*
* Failure status : Invalid survey ID, Invalid session key, No permission, No valid Data
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID The id of the Survey to be checked
* @param array|null $aSurveySettings (optional) The properties to get
* @return array
*/- get_uploaded_files
/**
* Obtain all uploaded files for all responses
*
* @access public
*
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey
* @param int $sToken Response token
*
* @return array 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)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID The ID of the Survey that the group will belong
* @param string $sImportData String containing the BASE 64 encoded data of a lsg,csv
* @param string $sImportDataType lsg,csv
* @param string $sNewGroupName Optional new name for the group
* @param string $sNewGroupDescription Optional new description for the group
* @return array|integer iGroupID - ID of the new group or status
*/- import_question
/**
* Import question (RPC function)
*
* Import a question from lsq file
*
* @access public
* @param string $sSessionKey
* @param int $iSurveyID The ID of the Survey that the question will belong to
* @param int $iGroupID The ID of the Group that the question will belong to
* @param string $sImportData String containing the BASE 64 encoded data of a lsq
* @param string $sImportDataType lsq
* @param string $sMandatory (optional) Mandatory question option (default to No)
* @param string $sNewQuestionTitle (optional) new title for the question
* @param string $sNewqQuestion (optional) new question text
* @param string $sNewQuestionHelp (optional) new question help text
* @return array|integer The id of the new question in case of success. Array if errors
*/- import_survey
/**
* Import survey in a known format (RPC function)
*
* Allow importing lss, csv, xls or survey zip archive in BASE 64 encoded.
*
* Failure status: Invalid session key, No permission, The import error
*
* @access public
* @param string $sSessionKey Auth Credentials
* @param string $sImportData String containing the BASE 64 encoded data of a lss, csv, txt or survey lsa archive
* @param string $sImportDataType lss, csv, txt or lsa
* @param string $sNewSurveyName (optional) The optional new name of the survey
* @param integer $DestSurveyID (optional) This is the new ID of the survey - if already used a random one will be taken instead
* @return int|array The ID of the new survey in case of success
*/- invite_participants
/**
* Invite participants in a survey (RPC function)
*
* Returns array of results of sending
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the survey that participants belong
* @param array $aTokenIds Ids of the participant to invite
* @param bool $bEmail Send only pending invites (TRUE) or resend invites only (FALSE)
* @return array Result of the action
*/- list_groups
/**
* Get survey pages (RPC function)
*
* Returns the ids and all attributes of all survey pages
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey containing the groups
* @return array in case of success the list of groups
*/- list_participants
/**
* Return the IDs and properties of survey participants (RPC function)
*
* 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.
*
* 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
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to list participants
* @param int $iStart Start id of the token list
* @param int $iLimit Number of participants to return
* @param bool $bUnused If you want unused tokens, set true
* @param bool|array $aAttributes The extented attributes that we want
* @param array $aConditions Optional conditions to limit the list, e.g. with array('email' => 'info@example.com')
* @return array The list of tokens
*/- list_questions
/**
* Return the ids and info of (sub-)questions of a survey/group (RPC function)
*
* Returns array of ids and info.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to list questions
* @param int $iGroupID Optional id of the group to list questions
* @param string $sLanguage Optional parameter language for multilingual questions
* @return array The list of questions
*/- list_surveys
/**
* List the survey belonging to a user (RPC function)
*
* 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)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param string|null $sUsername (optional) username to get list of surveys
* @return array In case of success the list of surveys
*/- list_users
/**
* Get list the ids and info of administration user(s) (RPC function)
*
* Returns array of ids and info.
*
* Failure status : No users found, Invalid session key, No permission (super admin is required)
*
* @param string $sSessionKey Auth credentials
* @param int $uid Optional parameter user id.
* @return array The list of users in case of success
*/
- mail_registered_participants
/**
* Send e-mails to registered participants in a survey (RPC function)
*
* 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 );
* ````
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey that participants belong
* @param array $overrideAllConditions replace the default conditions
* @return array Result of the action
*/- release_session_key
/**
* Close the RPC session
*
* Using this function you can close a previously opened XML-RPC/JSON-RPC session.
*
* @access public
* @param string $sSessionKey the session key
* @return string OK
*/- remind_participants
/**
* Send a reminder to participants in a survey (RPC function)
*
* Returns array of results of sending
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey that participants belong
* @param int $iMinDaysBetween (optional) parameter days from last reminder
* @param int $iMaxReminders (optional) parameter Maximum reminders count
* @param array $aTokenIds Ids of the participant to remind (optional filter)
* @return array 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)
*
* @see \QuestionGroup for available properties and restriction
*
* Some attribute can not be set
* * sid
* * gid
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iGroupID - ID of the Survey
* @param array $aGroupData - An array with the particular fieldnames as keys and their values to set on that particular survey
* @return array Of succeeded and failed modifications according to internal validation.
*/- set_language_properties
/**
* Set survey language properties (RPC function)
*
* @see \SurveyLanguageSetting for available properties.
*
* Some properties can not be set
* * surveyls_language
* * surveyls_survey_id
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iSurveyID - ID of the Survey
* @param array $aSurveyLocaleData - An array with the particular fieldnames as keys and their values to set on that particular survey
* @param string $sLanguage - Optional - Language to update - if not given the base language of the particular survey is used
* @return array in case of success 'status'=>'OK', when save successful otherwise error text.
*/- set_participant_properties
/**
* Set properties of a survey participant (RPC function)
*
* Allow to set properties about a specific participant, only one particpant can be updated.
* @see \Token for available properties
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID Id of the Survey that participants belong
* @param array|int $aTokenQueryProperties of participant properties used to query the participant, or the token id as an integer
* @param array $aTokenData Data to change
* @return array Result of the change action
*/- set_question_properties
/**
* Set question properties.
*
* @see \Question for available properties.
*
* Restricted properties:
* * qid
* * gid
* * sid
* * parent_qid
* * language
* * type
* * question_order in some condition (with dependecies)
*
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iQuestionID - ID of the question
* @param array $aQuestionData - An array with the particular fieldnames as keys and their values to set on that particular question
* @param string $sLanguage Optional parameter language for multilingual questions
* @return array Of succeeded and failed modifications according to internal validation.
*/- set_quota_properties
/**
* Set quota attributes (RPC function)
*
* Retuns an array containing the boolean 'success' and 'message' with either errors or Quota attributes (on success)
* @access public
* @param string $sSessionKey Auth credentials
* @param integer $iQuotaId Quota ID
* @param array $aQuotaData Quota attributes as array eg ['active'=>1,'limit'=>100]
* @return array ['success'=>bool, 'message'=>string]
*/- set_survey_properties
/**
* Set survey properties (RPC function)
*
* @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
* @param string $sSessionKey Auth credentials
* @param integer $iSurveyID - ID of the Survey
* @param array $aSurveyData - An array with the particular fieldnames as keys and their values to set on that particular Survey
* @return array Of succeeded and failed nodifications according to internal validation
*/- update_response
/**
* Update a response in a given survey.
*
* Routine supports only single response updates.
* Response to update will be identified either by the response id, or the token if response id is missing.
* Routine is only applicable for active surveys with alloweditaftercompletion = Y.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID Id of the Survey to update response
* @param array $aResponseData The actual response
* @return string|boolean TRUE(bool) on success. errormessage on error
*/- upload_file
/**
* Uploads one file to be used later.
*
* Returns the metadata on success.
*
* @access public
* @param string $sSessionKey Auth credentials
* @param int $iSurveyID ID of the Survey to insert file
* @param string $sFieldName the Field to upload file
* @param string $sFileName the uploaded file name
* @param string $sFileContent the uploaded file content encoded as BASE64
* @return array The file metadata with final upload path or error description
*/