web services technical guide 15.1 fp3...verint systems inc. does not warrant, guarantee or make any...

Confidential and Proprietary Information of Verint Systems Inc.

Enterprise Intelligence Solutions

EFM Enterprise

Web Services Technical Guide

Version 15.1 FP3

Document Revision 15.13

© 1992–2016 Verint Systems Inc. All Rights Reserved Worldwide. Confidential and Proprietary Information of Verint Systems Inc.

All materials (regardless of form and including, without limitation, software applications, documentation, and any other information relating to Verint Systems, its products or services) are the exclusive property of Verint Systems Inc. Only expressly authorized individuals under obligations of confidentiality are permitted to review materials in this document. By reviewing these materials, you agree to not disclose these materials to any third party unless expressly authorized by Verint Systems, and to protect the materials as confidential and trade secret information. Any unauthorized review, retransmission, dissemination or other use of these materials is strictly prohibited. If you are not authorized to review these materials, please return these materials (and any copies) from where they were obtained. All materials found herein are provided “AS IS” and without warranty of any kind.

Verint Systems Inc. does not warrant, guarantee or make any representation regarding the use or the results of the use of the information, links, tools, and materials in terms of the accuracy, reliability, quality, validity, stability, completeness, currentness, or otherwise of its content or products. The entire risk as to the use, results and performance of information, links, tools and materials provided or referenced herein is assumed by the user. Verint Systems Inc. shall not be liable for damages resulting from the use, misuse or unlawful use of the information, links, tools, and materials contained or referenced herein.

Any third party technology that may be appropriate or necessary for use with the Verint Product is licensed to you only for use with the Verint Product under the terms of the third party license agreement specified in the Documentation, the Software or as provided online at http://verint.com/thirdpartylicense. You may not take any action that would separate the third party technology from the Verint Product. Unless otherwise permitted under the terms of the third party license agreement, you agree to only use the third party technology in conjunction with the Verint Product.

The Verint Systems Inc. products are protected by one or more U.S., European or International Patents and other U.S. and International Patents and Patents Pending.

All marks referenced herein with the ® or ™ symbol are registered trademarks or trademarks of Verint Systems Inc. or its subsidiaries. All rights reserved. All other marks are trademarks of their respective owners.

Visit our website at www.verint.com/intellectualpropertynotice for updated information on Verint Intellectual Property.

Document Revision 15.13

Published November 7, 2016

http://verint.com/thirdpartylicense

http://www.verint.com/intellectualpropertynotice

C o n t e n t s

3 Web Services API-Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5General Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6EFM Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 Web Services Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Web Service projectdata.asmx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Web Service paneldata.asmx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Web Service bulk.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Web Service for casedata.asmx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Web Service admin.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Web Service reportdata.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

5 Survey Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Survey Event Handler Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Use Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Using the Visual Studio Web Site Provided . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating a New Web Service (Classic) or HTTP Handler (Modern) . . . . . . . . . . . . . . . 212Creating a Web Method for Use with Classic Survey Engine . . . . . . . . . . . . . . . . . . 214Creating an HTTP Handler for use with Modern Survey Engine . . . . . . . . . . . . . . . . 216Using the WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Web Service Event Handler Properties for the Modern Survey Engine . . . . . . . . . . . . . 218Survey Event Handler Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Survey Event Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Sample Survey Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

6 Hierarchical Questions Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Adding a Hierarchical Question to Your Survey . . . . . . . . . . . . . . . . . . . . . . . . 243Example of Using a Web Service for Hierarchical Questions . . . . . . . . . . . . . . . . . . 245Sample Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

7 Survey Engine API - Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . 252General Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Initial request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Working with survey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Contents

Product Name The Book Title and Name of this Guide 4


Survey page elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260Survey pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306Custom Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

8 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Campaign Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314Survey Engine API - JSON examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316Validations for Matrix question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344Input types for Matrix Short Answer side . . . . . . . . . . . . . . . . . . . . . . . . . . .346

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

C h a p t e r 3

Web Services API1-Getting Started

Topics General Introduction, page 6

EFM Web Services, page 11

1 Web Services API - These are the endpoints into the application that are made available to our customers.Some of the methods available trigger actions but most just push data into the system or pull it out. Custom-ers run programs on their servers that call into EFM servers and Web Services (using SOAP over HTTP).There are over 100 methods and these are documented in this Web Services guide.

Chapter 3 - Web Services API-Getting Started General Introduction

EFM Web Services Technical Guide 6


General IntroductionA Web Service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface that is described in a machine-processable format such as WSDL (Web Services Description Language). Other systems interact with the Web Service in a manner prescribed by its interface using messages, which may be enclosed in a SOAP (Simple Object Access Protocol) envelope.

All Web Services provided by EFM were created entirely within Visual Studio, and use the conventions supported by the Microsoft .NET Framework.

EFM currently provides the following Web Services:

Survey Project Data (http://{EFM_SERVER}/ws/projectdata.asmx)

Report Data (http://{EFM_SERVER}/ws/reportdata.asmx)

Case Data (http://{EFM_SERVER}/ws/casedata.asmx)

Panel Data (http://{EFM_SERVER}/ws/paneldata.asmx)

Bulk (http://{EFM_SERVER}/ws/bulk.asmx)

Administration (http://{EFM_SERVER}/ws/admin.asmx)

Add a Reference to a Web Service Using Visual StudioIn Visual Studio, open the project that will use the Web Service. In the solution explorer project tree, right-click the project file and click "Add Web Reference"

Adding a Reference to a Web Service Using Visual Studio

Chapter 3 - Web Services API-Getting Started Add a Reference to a Web Service Using Visual Studio



Type in the URL to the Web Service that you wish to use and click "Go."

A list of available functions the Service provides will display. Enter a “Web reference name” that will be used to reference the Web Service in code, and then click “Add reference.”

A Web reference will now display for the selected project with the Web reference “name” that was provided. See the following example:

ProjectData Web Reference

NOTE Web Services published by EFM all have the “.asmx” extension.

Chapter 3 - Web Services API-Getting Started Connecting to a Web Service Using Visual Studio



Connecting to a Web Service Using Visual StudioTo use a Web Service in Visual Studio, an instance of the object (using the Web reference name that was selected earlier) must be created. Following is a C# code sample that demonstrates how a typical EFM Web Service is accessed.

// Create an instance of the Web Service:WSProjectData.ProjectData wsProjectData = new ProjectData();

// Assign a cookie container so the Web Service can preserve the validated// session:wsProjectData.CookieContainer = new System.Net.CookieContainer();

// Initialize the account information that the Web Service will use to login:string userName = "WebServiceAccount";string password = "12345";

// Attempt to login to the Service using an existing accounttry {wsProjectData.Login(userName, password);} catch (SoapException ex){// TODO: Notify the user that the login failed}

Before any Web Service functionality is used, the program must login to EFM using an existing account.

Note that the program must log in to each Web Service. Logging in to a single Web Service does not authenticate the program globally.

Any EFM account can be used to log in, but the Web Service is restricted to the permissions allowed for that account's role in EFM. For example, if the Web Service logs in to an account that only has survey editing capabilities, you cannot view or edit invitations.

NOTE Notice that a cookie container object was assigned to the Web Service. Without cookies, the Web Service will not be able to preserve the session information needed to authenticate further calls to the EFM Web Services after the initial login. For more information, see the last bullet point in the Tips on using EFM Web Services section.

Chapter 3 - Web Services API-Getting Started Dynamically Accessing a Web Service



Dynamically Accessing a Web ServiceSometimes the URL of a Web Service may not be fixed. In these cases, you may want to specify a URL for the Web Service at runtime. Following is a C# code sample of that demonstrates how to change the URL of a Web Service at runtime.

// Create an instance of the Web Service// WSProjectData.ProjectData wsProjectData = new ProjectData();...// TODO: Determine the server and/or specially construct the URL to access the

// Web Servicestring wsUrl = @"http://{EFM_SERVER}/ws/projectdata.asmx";wsProjectData.Url = wsUrl;

Notice that a complete URL is used (including "http://") to access the Web Service, instead of a relative URL. Sometimes it may be more efficient to use the System.Uri object to construct the URL instead of building a string.

Chapter 3 - Web Services API-Getting Started Tips on using EFM Web Services



Tips on using EFM Web Services In documentation and method names, the term “project” is used to cover both

surveys and panel profiles.

All of EFM Web Services support the method Ping, which can be used to confirm that the Web Service is active and the client is connected to it correctly. The method returns “ACK” when successful.

All of EFM Web Services support the method Login, which is used to authenticate a program calling a Web Service. The best practice is to use an account that is used only for accessing Web Services and has a security role with the minimum required permissions needed by the process that is accessing the Web Service.

It is also best practice to set the Web Service account time zone to UTC. Some methods return times in Web Service account time and some in UTC. Setting the Web Service account time zone to UTC results in all methods returning a consistent time.

All of EFM Web Services support the method Logout, which is used to end the current user session. The best practice is to call this method at the end of a web service session.

Methods throw Soap Exceptions for permission errors, parameters out of range, problems reading from or writing to the database, and logical errors (for example, asking for a questionnaire before it has been created).

Exceptions are not thrown if data cannot be found (for example, asking for survey responses but there are no responses collected yet).

The Microsoft .NET Framework does not enable cookies for you automatically. The symptom that may occur is that calls to Ping and Login will be successful, but further calls will throw an “Invalid Access” exception. To solve this, a cookie container will need to be assigned to the Web Service. Following is a C# code example:// Assign a cookie container so the Web Service can preserve the validated// sessionwsProjectData.CookieContainer = new System.Net.CookieContainer();

In newer versions of Visual Studio, use of a Service Reference is recommended over a Web Reference. If a Service Reference is used, a different method of enabling the Cookie Container is required. In app.config in the <binding> node, the attribute allowCookies=”true” must be added. For example:<binding name=”ProjectDataSoap” allowCookies=”true”/>

Chapter 3 - Web Services API-Getting Started EFM Web Services



EFM Web Services

Introduction to EFM Web ServicesIn documentation and method names, we use "project" to cover both surveys and panel profiles. The following pages provide you information on:

How to Confirm and Validate your Web Service Account

How to perform EFM Web Service calls for projectdata.asmx, reportdata.asmx, casedata.asmx, paneldata.asmx, bulk.asmx, and admin.asmx.

When handling XML responses from the Web Service calls, your applications should be able to handle additional, undocumented values in the XML as we may add more attributes or elements in future versions of this API.

Each method call is provided along with the following information (if applicable):

Method Call name

Description

Parameters

Return Value and Description

Permissions

Exceptions

Methods throw Soap Exceptions for:

permission errors

parameters out of range

problems reading from or writing to the database

logical errors (for example, asking for a questionnaire before it has been created).

Check the exception message to see exactly what is wrong. EFM Web Services will not throw an exception if data cannot be found (for example you ask for survey responses and there are not any yet).

The Permissions line for each method details what permission(s) are required of the logged-in user. The “Permission Denied” exception will be thrown for permission violations.

The “Invalid Access” exception will be thrown if the user is not properly logged in.

Chapter 3 - Web Services API-Getting Started Introduction to EFM Web Services



If you use .NET to create a client, it will not enable cookies for you. The symptom will be that you can call Ping and Login, but further calls will throw an Invalid Access exception. To solve this, add the following code to your client before making any calls:

// Assign a cookie container so the Web Service can preserve the validated// sessionwsProjectData.CookieContainer = new System.Net.CookieContainer();

In newer versions of Visual Studio, use of a Service Reference is recommended over a Web Reference. If a Service Reference is used, a different method of enabling the Cookie Container is required. In app.config in the <binding> node, the attribute allowCookies=”true” must be added. For example:<binding name=”ProjectDataSoap” allowCookies=”true”/>

Chapter 3 - Web Services API-Getting Started Confirming and Validating your Web Service Account



Confirming and Validating your Web Service Account

Method Call: Ping

Description: Confirm that the Web Service is active and that the client is correctly connected to it.

NOTE If this is the only method that works, when there is a validation problem. See “Login” call below.

Parameters:(name, type, description)

None

Return Value & Description:

string Returns: The string ACK

Permissions: None

Exceptions: None




Method Call: Login

Description: Validate the account credentials and establish a session for future calls.

NOTE This call must be made before any other calls except Ping.

Best practice is to use an account which is used only for accessing Web Services that belongs to a security role that has the minimum set of required permissions needed to perform whatever actions the calling process needs to perform (that is, the principle of least privilege). The client must enable cookies, so that the login information is preserved across calls. While accessing the web service, if the user name/password combos are not valid, user account is locked out after the configured maximum number of failed attempts within the window duration.There is the CSRF protection to ensure that only valid accounts are accessing Web Services. CSRF protection is turned off by default. It can be turned on in app.config. When the global option to turn CSRF protection is on, APIs include an anti-forgery token. The initial token is returned by the login request. The token is a GUID.To enable CSRF, add the following node to app.config in the:

<ApplicationSettings><WSUseCSRFProtection>True|False</WSUseCSRFProtection>

In subsequent calls for this login session, an HTTP header with the name "X-CSRF-Token" and the value returned by Login must be added.


userName (string) EFM username password (string) Unencrypted user password


string Returns:Empty string or CSRF token (if enabled) for success

Permissions: None

Exceptions: SOAP exception on failure and locking out account




Method Call: Logout

Description: Ends the current user session. No effect if there is not a user logged in. This call is not required but can help overall system memory usage if called after a web session.


None


None

Permissions: None

Exceptions: None

Chapter 3 - Web Services API-Getting Started Using CSRF Token in Web Service calls



Using CSRF Token in Web Service callsThe CSRF (Cross-Site Request Forgery) protection ensures that only valid accounts can access Web Services.

If EFM is configured for CSRF, the Login method returns a token that can be passed back into each subsequent Web Service request by request header. The token is stored in the session and expires with the authentication token.

The client application should be modified to use the CSRF Token, if CSRF is enabled. The CSRF Token returned by a successful Login call should be retrieved and verified that it is valid GUID. If so, it should be added as a value of “X-CSRF-Token” header to all subsequent requests.

Update proxy class

New members should be added to Web Service Proxy Class. Following is a C# code sample that illustrates this.

//Store Token returned by Loginpublic string Token { get; set; }

//Add Token as value of “X-CSRF-Token” header of all requestsprotected override System.Net.WebRequest GetWebRequest(Uri uri) {

System.Net.WebRequest wr = base.GetWebRequest(uri);if (!string.IsNullOrEmpty(Token)){

wr.Headers.Add("X-CSRF-Token", Token);}return wr;

}

Members can be added either by updating the generated Proxy Class itself or by extending it. You can extend a Proxy Class by creating a partial class in the appropriate namespace.

namespace Verint.CSRFExample.WS.Admin{

public partial class Admin : System.Web.Services.Protocols.SoapHttpClientProtocol{

public string Token { get; set; }protected override System.Net.WebRequest GetWebRequest(Uri uri){

System.Net.WebRequest wr = base.GetWebRequest(uri);if (!string.IsNullOrEmpty(Token)){

wr.Headers.Add("X-CSRF-Token", Token);}return wr;

}}

}

Chapter 3 - Web Services API-Getting Started Update login process



Update login process

Retrieve CSRF Token returned by successful Login call, verify if it is a valid GUID, store it as a Token Field of Proxy Class. Following is a C# code sample that demonstrates this.

//Initialize WS ProxyWS.Admin.Admin adminData = new WS.Admin.Admin();adminData.Url = url;adminData.CookieContainer = new CookieContainer();

try{

//Attempt to login and retrieve CSRF Tokenstring loginRes = adminData.Login(userName, password);

//If Token returned, parse Guid and store into Proxy to use in further requests//See WS.Admin.Admin.GetWebRequest method for detailsif (!string.IsNullOrEmpty(loginRes)){

Guid token = Guid.Empty;if (Guid.TryParse(loginRes, out token)){

adminData.Token = token.ToString();}

}

//Call WS MethodXmlNode userInfo = adminData.GetUserInfoByUsername(userName);

} catch (SoapException ex){

// TODO: Notify the user that the login failed}

C h a p t e r 4

Web Services Data

Topics Web Service projectdata.asmx, page 19

Web Service paneldata.asmx, page 109

Web Service bulk.asmx, page 135

Web Service for casedata.asmx, page 151

Web Service admin.asmx, page 169

Web Service reportdata.asmx, page 196

Chapter 4 - Web Services Data Web Service projectdata.asmx



Web Service projectdata.asmxThis Web Service exposes Survey Project data. In documentation and method names, we use “project” to cover both surveys and panel profiles.

When handling XML responses from the Web Service calls, your applications must be able to handle additional, undocumented values in the XML as we may add additional attributes or elements in future versions of this API.

Lists of Projects

Method Call: GetSurveyList

Description: Returns a list of surveys in an XML representation


sharingType (int)0 = login user's surveys1 = other people's surveys visible to the user2 = both


XMLNode Returns: XML giving information about each survey, as follows:

<Projects><Project id="ID">

<Name>SURVEY NAME</Name></Project>

</Projects>

Permissions: View Surveys

Exceptions: None

Chapter 4 - Web Services Data Lists of Projects



Method Call: GetCommonSurveyList

Description: EFM keeps a record of how a survey was introduced into the system. For example, a survey can be imported from a .que or .doc file. It can also be copied from another survey. The initial source string is the specified field or survey name of the survey source.


initialSource (string)The initial source string must exactly match what is stored in the system.


XMLNodeReturns: XML giving information about each survey, as follows:


<Name>SURVEY NAME</Name></Project>

</Projects>


Exceptions: None

Chapter 4 - Web Services Data Lists of Projects



Method Call: GetProfileList

Description: Returns a list of EFM profiles, in an XML representation.


None


XMLNode Returns:XML giving information about each profile, as follows:


<Name>PROFILE NAME</Name></Project>

</Projects>

Permissions: View Panel Profiles

Exceptions: None

Chapter 4 - Web Services Data Project Creation



Project Creation

Method Call: CreateSurveyProject

Description: Create a new blank survey with specified name and description.


projectName (string) Short name of the survey (max 150 characters)

description (string) Description of the survey (max 255 characters)

respondent Source (int)

0 = open participation

1 = EFM panel

2 = external email list

3 = external access list

4 = SMS survey


intReturns: The new project id

Permissions: Create Surveys

Exceptions: None

Chapter 4 - Web Services Data Project Creation



Method Call: CreatePanelProfile

Description: Create a new blank panel profile with specified name and description.


profileName (string) Short name of the profile (max 150 characters)

description (string) Description of the profile (max 255 characters)


intReturns: The new project id

Permissions: Create Panel Profiles

Exceptions: None

Chapter 4 - Web Services Data Questionnaire Access



Questionnaire Access

Method Call: GetQuestionnaire

Description: Return the XML that specifies the current questionnaire. If the survey has been modified since it was published, the questionnaire may not match the response data.

CAUTION This function returns XML that represents the internal structure of a Questionnaire in the EFM platform. This XML may change with new releases and the XML structure should not be relied on for individual elements. Use calls like GetSurveyInformation or GetSurveyFieldInformation to query the structure of the questionnaire.

Parameters: (name, type, description)

projectId (int) A project ID


XMLNodeReturns: XML which fully specifies the questionnaire. The format is too complex to document here, but it is the same as found in an EFM .que file.


Exceptions: None




Method Call: GetPublishedQuestionnaire

Description: Returns the XML that specifies the published questionnaire. This may not be the same as the latest questionnaire; see also GetQuestionnaire.

CAUTION This function returns XML that represents the internal structure of a Questionnaire in the EFM platform. This XML may change with new releases and the XML structure should not be relied on for individual elements. Use calls like GetSurveyInformation or GetSurveyFieldInformation to query.




XMLNodeReturns: XML which fully specifies the questionnaire. The format is too complex to document here, but it is the same as found in an EFM .que file.


Exceptions: None




Method Call: SetQuestionnaire

Description: Set the questionnaire via its XML representation.

CAUTION No validation is done, so know what you are doing before performing this Method Call. EFM does not support dynamic survey creation by the API. Only pass in survey XML returned from GetQuestionnaire or GetPubilshedQuestionnaire.


projectId (int) A project ID surveyXml (string) An XML representation of

the questionnaire, as returned by GetQuestionnaire


intReturns: The version number, which may be passed to RevertQuestionnaire.

Permissions: Edit Surveys

Exceptions: This Web Service Method is not available for data sets.




Method Call: GetQuestionnaireVersions

Description: Get the current list of versions of this survey



Return Value & Description

XMLNodeReturns: XML specifying the versions, as follows:

<Versions><Version versionid="ID" change="CHANGETYPE" date="DATE/TIME OF CHANGE" userid="USER"/>

</Versions>


Exceptions: None

Notes: CHANGETYPE ValuesThese are the values currently for CHANGETYPE.CreatedGeneralWordProcessorQuestionLogicQuestionAppearanceTablePropertiesWebFormattingSurveyPropertiesScoringValidationMessagesWebAccessibilityTranslationEndPagesAdvancedBranchingChoiceConditionsSpellCheckLibraryQuestionPageElementMovedPageElementRemovedQuestionUpdated




Notes: SectionUpdatedTextBlockUpdatedCommentUpdatedQuestionAddedSectionAddedCommentAddedPageBreakAddedTextBlockAddedPublishRollBackUpgradeQuotaPageRotationCodeBlockUpdatedCodeBlockAddedSurveyGlossary EmailTriggerActivatePageBreakDeleted

Method Call: GetQuestionnaireVersions




Method Call: RevertQuestionnaire

Description: Revert to an earlier version of the questionnaire


projectId (int) A project ID versionId (int) ID of a version to return to; see

also GetQuestionnaireVersions


N/A



Chapter 4 - Web Services Data Custom Properties



Custom Properties

Method Call: GetSurveyCustomProperties

Description: Get the custom properties for a question, or for the entire survey.


projectId (int) A project ID columnName (string) The database name for

the column. Pass a null value for this parameter to get the survey custom properties


XMLNodeReturns: XML specifying the custom properties, as follows; the Property element repeats as needed:

<Properties><Property>

<Name>CUSTOM PROPERTY NAME</Name><Value>CUSTOM PROPERTY VALUE</Value>

</Property></Properties>


Exceptions: None




Method Call: GetCustomPropertiesForSurveys

Description: Get the custom properties for a list of surveys.


projectIds (int[]) An array of project IDs targetPropertyName (string) If not null, we will

only return projects with a custom property with this name


XMLNodeReturns: XML specifying the custom properties, as follows; the Property element repeats as needed:

<Projects><Project id="PROJECTID">

<Property><Name>CUSTOM PROPERTY NAME</Name><Value>CUSTOM PROPERTY VALUE</Value>

</Property></Project>

</Projects>


Exceptions: None




Method Call: SetSurveyCustomProperties

Description: Set the custom properties for a question, or for the entire survey.


projectId (int) A project ID columnName (string) The database name for

the column; or null to set the survey custom properties.

NOTE "columnName" is limited to 255 characters.

propertiesXml (string) XML specifying the custom properties, in the same format as returned by GetSurveyCustomProperties.


N/A



Chapter 4 - Web Services Data Column Information



Column Information

Method Call: GetDataMap

Description: Return the data map for a questionnaire that maps the choice values to their labels. This can be passed to GetSurveyDataEx, with or without user modification.




XMLNodeReturns: XML with information about each column, in this format.Note that ValueMap will only occur for choice questions (Choose One, Choose Many, and table versions of the same).

<DataMap sourceType="0"><FieldMap sourceField="DBHEADING" destinationField="DBHEADING">

<ValueMap sourceValue="CHOICE QUESTION VALUE" destinationValue="CHOICE LABEL"/>

</FieldMap></DataMap>


Exceptions: None




Method Call: GetExportDataMap

Description: Return the data map for a questionnaire that maps the choice values to their specified export values. If export values are not defined, the map specifies choice values.This can be passed to GetSurveyDataEx, with or without user modification. Data extracted using the export datamap cannot be correctly imported back into EFM. Information comes from the latest published questionnaire. If the survey is not yet published, no information will be returned.




XMLNodeReturns: XML with information about each column, in this format. Note that ValueMap will only occur for choice questions (Choose One, Choose Many, and table versions of the same).


<ValueMap sourceValue="CHOICE QUESTION VALUE" destinationValue="CHOICE QUESTION EXPORT VALUE" />



Exceptions: None




Method Call: GetReportDataMap

Description: Return the data map for a questionnaire that maps the choice values to their specified report values. If report values are not defined, the map specifies choice values.This can be passed to GetSurveyDataEx, with or without user modification. Data extracted using the report datamap cannot be correctly imported back into EFM. Information comes from the latest published questionnaire. If the survey is not yet published, no information will be returned.




XMLNodeReturns: XML with information about each column, in this format. Note that ValueMap will only occur for choice questions (Choose One, Choose Many, and matrix versions of the same).


<ValueMap sourceValue="CHOICE QUESTION VALUE" destinationValue="CHOICE QUESTION REPORT VALUE" />



Exceptions: None




Method Call: GetColumnList

Description: Return an XML representation of the names of the columns in the survey. Information comes from the latest published questionnaire. If the survey is not yet published, no information will be returned.




XMLNodeReturns: XML containing the column names, in this format:

<Columns><Field id="DBHEADING" type="TYPE"/>

</Columns>


Exceptions: None




Method Call: GetSurveyInformation

Description: Return a simplified XML representation of the survey structure. This is easier than examining the questionnaire XML directly. It is most useful for custom reports. The emphasis is on providing a mapping between nodes of the questionnaire and the database headings in the export or Web Methods. Information comes from the latest published questionnaire. If the survey is not yet published, no information will be returned.




XMLNodeReturns: XML containing the column names, in this format (examples of each question type are shown):

<Survey><Question class="ChooseOne" heading="DISPLAY HEADING" column="DB HEADING">

<Choice id="INDEX" specify="DATABASE HEADING OF SPECIFY (IF ANY)" />

</Question><Question class="ChooseMany" heading="DISPLAY HEADING">

<Choice id="INDEX" column="DB HEADING" specify="DB HEADING OF SPECIFY (IF ANY)" />

</Question><Question class="Essay" heading="DISPLAY HEADING" column="DB HEADING" /><Question class="FillIn" heading="DISPLAY HEADING">

<Option id="INDEX"column="DB HEADING" type="DATA TYPE" />

</Question><Question class="Matrix" heading="DISPLAY HEADING">

<Side id="INDEX" class="ChooseOne"><Topic id="INDEX"column="DB HEADING" />

</Side><Side id="INDEX" class="ChooseMany">

<Topic id="INDEX" column="DB HEADING">

<Choice id="INDEX" column="DB HEADING" />

</Topic>





</Side><Side id="INDEX" class="FillIn" type="DATATYPE"/>

<Topic id="INDEX" column="DB HEADING" /><Topic id="DATATYPE" column="DB HEADING" />

</Side><Side id="INDEX" class="Essay" column="DB HEADING" />

</Question></Survey>


Exceptions: None

Method Call: GetSurveyInformation




Method Call: GetSurveyFieldInformation

Description: Returns an XML representation giving the question headings, choice and topic labels, for all defined cultures. This is easier than examining the questionnaire XML directly. The latest questionnaire is used, which may not match the published questionnaire.


projectId (int) A project ID columnName (string) The database name for a

question; can be fetched with GetColumnList. If blank, we will return information for all columns (avoid doing this for huge surveys).


XMLNodeReturns: An XML structure, as follows:

<SurveyFields xmlns=""><SurveyField>

<Heading><Text type="plain">Choose One Question Type</Text>

</Heading><Body>

<Text>Choose One Question text</Text>

</Body><Choices>

<Choice dbvalue="1"><Text>Monday</Text>

</Choice><Choice dbvalue="2">

<Text>Wednesday</Text></Choice><Choice dbvalue="3">

<Text>Friday</Text></Choice><Choice dbvalue="4">

<Text>Other (please specify)</Text>

</Choice></Choices>

</SurveyField><--! The following XML represents the text in

"Other (please specify)" above-->





<SurveyField><Heading>

<Text type="plain">Choose One Question Type Additional comments</Text>

</Heading><Body>

<Text></Text></Body>

</SurveyField><SurveyField>

<Heading><Text type="plain">Choose Many Question Type</Text>

</Heading><Body>

<Text>Choose Many Question text</Text>

</Body><Choice>

<Text>Monday</Text></Choice><Choice>

<Text>Wednesday</Text></Choice><Choice>

<Text>Friday</Text></Choice>


<Heading><Text type="plain">Essay Question Type</Text>

</Heading><Body>

<Text>Essay Question text</Text></Body>


<Heading><Text type="plain">Matrix Question Type</Text>

</Heading><Body>

<Text>Matrix Question text</Text></Body><Category>

<Text></Text></Category><Topic>

<Text>Topic One</Text></Topic>






<Topic><Text>Topic Two</Text>

</Topic><Choices>

<Choice dbvalue="1"><Text>Choice A</Text>

</Choice><Choice dbvalue="2">

<Text>Choice B</Text></Choice><Choice dbvalue="3">

<Text>Choice C</Text></Choice>

</Choices></SurveyField><SurveyField>

<Heading><Text type="plain">Fill in the Blank Question Type</Text>

</Heading><Body>

<Text>Fill in the Blank Question text</Text>

</Body><Topic>

<Text>Topic X</Text></Topic><Topic>

<Text>Topic Y</Text></Topic><Topic>

<Text>Topic Z</Text></Topic>

</SurveyField></SurveyFields>


Exceptions: None


Chapter 4 - Web Services Data Survey Life Cycle



Survey Life Cycle

Method Call: RepublishProject

Description: Open, republish, or close the project.


projectId (int) A project ID publishMode (int)

0 = testing1 = open2 = closed


N/A



Chapter 4 - Web Services Data Survey Information



Survey Information

Method Call: SetEndPageURL

Description: Sets a static destination URL for an end page (e.g., submission page, exit page, etc.). The project must be published using RepublishProject before the change takes effect.


projectId (int) A project ID endPageType (int):

0 = submission page1 = save and resume page2 = exit page3 = closed page4 = invalid access5 = completed response6 = quota reached7 = opt out

URL (string) A valid URL (no validation is performed)


N/A






Method Call: GetProjectInformation

Description: Get basic information about a project.

NOTE The URL is provided for Open Participation surveys only.




XMLNodeReturns: An XML representation, as follows:

<Project id="PROJECTID" type="Survey|Profile" owner="USERID"

publish="Created|Testing|Open|Closed" status="Deleted|Active"

source="Panel|Access List|Email List|Open Participation"

modifier="MODIFIER"modified_date="MODIFIED"close_date="CLOSE_DATE"publish_date="PUBLISHED"open_date="OPEN_DATE"create_date="CREATE_DATE"> <Name>PROJECT NAME</Name> <Description>PROJECT DESCRIPTION

</Description> <URL>URL</URL>

</Project>


Exceptions: None




Method Call: SetProjectInformation

Description: Change one or more fields of basic project information. Blank or missing fields will not be changed; so to just change the project name, include only the Name node. Only name, description, source, or owner can be changed (and source can only be changed to Open Participation); other elements cannot be changed.


projectId (int) A project ID String (string) An XML string in the same format

returned by GetProjectInformation, but only including attributes and nodes which are to be changed.


N/A


Exceptions: The respondent source can only be changed if the survey is not open.The respondent source can only be changed to Open Participation.The respondent source cannot be changed for SMS surveys.

Chapter 4 - Web Services Data Survey Management



Survey Management

Method Call: DeleteProject

Description: Delete a project. (This actually just sets the status to deleted). This will close the survey if it's open.




N/A

Permissions: Delete Surveys

Exceptions: None




Method Call: GetResponseCount

Description: Tell how many responses this survey has received.

NOTE For potential responses (people authorized to take the survey, but who have not yet done so), see GetAuthorizedParticipantCount.


projectId (int) A project ID completedOnly (bool) If true, return completed

responses only; otherwise, return all started responses.


intReturns: The number of responses of the specified type.

Permissions: View Results

Exceptions: None




Method Call: GetSurveyData

Description: Return a DataSet containing all the responses for a specified project. This call returns all data (including responses started but not completed). Web Services was not designed to handle large amounts of data, so GetSurveyData can only be used when there are 5,000 or less responses. This means it may not be able to handle all of your survey data. Use GetSurveyDataEx or GetSurveyDataPaged to restrict the data returned, using a filter or paging by modified time.




DataSetReturns: A DataSet:http://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.


Exceptions: None

http://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx




Method Call: GetSurveyDataEx

Description: Returns a DataSet of responses (max 10,000) filtered by time or a set of test criteria. If you have thousands of records this call will only return 10,000 records at a time; the data is chunked, and we limit data on a per chunk basis. Use the startTime parameter to page through the data (you can use the modified time from the last record in the data set as the startTime for the next call or as GetSurveyDataPaged).


projectId (int) A project ID dataMapXml (string) If not null, this must be XML

specifying a DataMap; same format as returned by GetDataMap. This allows fields to be omitted or renamed, and allows replacing choice question numeric values with the labels defined in the questionnaire--or any other mapping the client desires.

filterXml (string) If not null, this must be XML specifying a set of Criterion objects used to filter the data.<CriteriaCollection>

<Criterion leftparen="NUMBER OF LEFT PARENS"heading="DATABASE COLUMN" expression="OPERATOR"value="COMPARED VALUE"rightparen="NUMBER OF RIGHT PARENS" rule="AND|OR" />

</CriteriaCollection>

Operator is one of = != < > <= >= startTime(dateTime) Return only data modified

past this date; use null or DateTime.MinValue if there is no early cutoff.

endTime (dateTime) Return only data modified before this date; use null or DateTime.MaxValue if there is no late cutoff.

completedOnly (bool) If true, return completed responses only; otherwise, return all started responses.

NOTE Time is specified in Coordinated Universal Time (UTC) format.




WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.


DataSetReturns: A DataSethttp://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.

NOTE Times returned in the DataSet are in the API user preferred time zone as set in My Account.The DataSet returned is sorted by modified time.


Exceptions: None

Method Call: GetSurveyDataEx





Method Call: GetSurveyDataPaged

Description: Returns a DataSet of responses - one page at a time. The page size is determined by the caller but can't be more than 10,000 records. To get the next page of data, pass in the highest recordId from the last call.


projectId (int) A project ID dataMapXml (string) If not null, this must be

XML specifying a DataMap; same format as returned by GetDataMap. This allows fields to be omitted or renamed, and allows replacing choice question numeric values with the labels defined in the questionnaire-- or any other mapping the client desires.

filterXml (string) If not null, this must be XML specifying a set of Criterion objects used to filter the data. <CriteriaCollection>

<Criterion leftparen="NUMBER OF LEFT PARENS"heading="DATABASE COLUMN" expression="OPERATOR"value="COMPARED VALUE"rightparen="NUMBER OF RIGHT PARENS" rule="AND|OR" />


Operator is one of = != < > <= >= completedOnly (bool) If true, return completed

responses only; otherwise, return all started responses.

prevRecordId (long) Returns only records greater than this. If 0, start with the lowest record ID

recordCount (int) Return this number of records up to a max of 10,000.






DataSetReturns: A DataSethttp://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.

NOTE Started, Completed, and Modified are valid database columns.


Exceptions: None

Method Call: GetSurveyDataPaged





Method Call: GetResponse

Description: Get the answers for one response.


projectId (int) A project ID recordId (long) The internal ID of this response

can be found with GetSurveyData(Ex).


XMLNodeReturns: An XML representation of the response as follows:

<Rows><Row id="RECORDID">

<Field id="DBHEADING"type="Int|BigInt|Varchar|Text|Float">VALUE</Field>...

</Row></Rows>


Exceptions: None




Method Call: ChangeResponse

Description: For the specified record - change a single data point.


projectId (int) A project ID recordId (long) The internal ID of the

respondent can be found with GetSurveyData(Ex).

columnName (string) The database name for the column to be changed.

newValue (string) A string representation of the new value.


stringReturns: Blank if successful; else an error message

Permissions: Edit Results

Exceptions: Exceptions are thrown for invalid record ids or other errors updating the response.This Web Service Method is not available for data sets.




Method Call: ChangeMultipleResponses

Description: Change one or more respondent records. Only the values to be changed should be specified.


projectId (int) A project ID dataString (string) An XML representation of the

row(s) to be changed, in the same format as returned by GetResponse and SetParticipantInformation. Leave out columns that are not to be changed and the type attribute. Sample XML:<Rows>

<Row id="RECORDID"invite_status="STATUS"user_key1="KEY"user_key2="KEY"user_key3="KEY"last_page="LAST PAGE USER VISITED" started="START TIME" modified="MODIFICATION TIME" completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"campaign_status="CAMPAIGN STATUS">

<Field id="DBHEADING">VALUE</Field></Row>

</Rows>


stringReturns: Blank if successful; otherwise an exception message.






Method Call: AddResponse

Description: Add a new response to the survey.


projectId (int) A project ID dataString (string) An XML representation of

values to be added to the new row, this is in the same format as returned by GetResponse and GetParticipantInformation. For an Open Participation survey, the "id=" attribute is optional. It will be returned by the method call.For any other kind of survey, recordid is required and must be supplied as the id attribute on the Row node.The type attribute is not required. Sample XML:<Rows>

<Row id="RECORDID" invite_status="STATUS"user_key1="KEY"user_key2="KEY"user_key3="KEY"last_page="LAST PAGE USER VISITED"started="START TIME" modified="MODIFICATION TIME" completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"campaign_status="CAMPAIGN STATUS">

<Field id="DBHEADING">VALUE</Field></Row>

</Rows>


longReturns: New Record ID of the added response


Exceptions: This Web Service Method is not available for profile surveys.

This Web Service Method is not available for data sets.




Method Call: GetPreloadData

Description: Get the preload data for a participant.


projectId (int) A project ID recordId (long) The record ID of this participant

can be found with GetParticipantData(Ex).


XMLNodeReturns: An XML representation of the response in the same format as returned by GetResponse. If the preload data was set by borrowing panel questions, it will contain a source attribute identifying where the question came from.

Permissions: View Participants

Exceptions: None




Method Call: SetPreloadData

Description: Change the preload data for a participant.

NOTE This method only works on participant records that have not yet been started by a survey participant. To change field values after a participant has started a survey response, use ChangeResponse or ChangeMultipleResponses.

The "type=" attribute of the <Field> node in the dataString is required. See GetResponse for details. To obtain the correct "type=" attribute value for each question, use GetColumnList.



the row(s) to be changed in the same format as returned by GetResponse.


N/A



Note The <Row> node will accept either id = (as returned by ChangeMultipleResponses) or recordid = for the record ID.




Method Call: DeleteParticipant

Description: Delete a participant and their response. That is, remove the participant from the Participant Selector (they are no longer authorized to take the survey), and remove any responses they may have entered.


projectId (int) A project ID recordId (long) The record ID of this participant;

can be found with GetParticipantData(Ex).


N/A

Permissions: Delete Participants





Method Call: ClearResponse

Description: Clear a response without deleting the participant. That is, remove any responses they may have entered, and mark the participant as not having started the survey. They are still authorized to take it.


projectId (int) A project ID recordId (long) The internal ID of this response

can be found with GetSurveyData(Ex).


N/A

Permissions: Delete Results


Chapter 4 - Web Services Data Aggregate Data



Aggregate Data

Method Call: GetFrequencyInformation

Description: Get frequency data for a question.

NOTE Currently not supported for matrix questions.



question can be fetched with GetColumnList.


XMLNodeReturns: An XML representation of the frequency table, as follows:

<Question name="QUESTION HEADING"side="SIDE ID" topic="TOPIC ID">

<Frequency column="DBHEADING"valid="VALID COUNT" asked="ASKED COUNT">

<Response count="RESPONSECOUNT">RESPONSE LABEL</Response>

</Frequency></Question>

Where:Asked = is the count of respondents who were asked this questionValid = is the count of respondents who answered this questionFrequency count = is the frequency that this response occurs in the underlying data set


Exceptions: None

Chapter 4 - Web Services Data Aggregate Data



Method Call: GetStatistics

Description: Get statistics data for a question.



question can be fetched with GetColumnList.


XMLNodeReturns: An XML representation of the statistics, as follows:

<Question name="QUESTION HEADING"><Statistics column="DBHEADING"><Item name="STATISTIC">VALUE</Item></Statistics>

</Question>


Exceptions: None

Chapter 4 - Web Services Data Add Participants



Add Participants

Method Call: AuthorizeMultiplePanelistsForSurvey

Description: Adds multiple panelists to the invitation queue for the specified project. The panelists will not be invited until invitations are sent from the project in EFM. This method does not support user keys, which in turn means that a given panelist can be invited to a survey just once.


projectId (int) A project ID panelistIdList (int[]) An array of panelist IDs


long[]Returns: An array of longs of the same size, with the corresponding new recordid (or zero, if there is an error for a specific panelist).

Permissions: Import Panelists

Exceptions: This Web Service Method is not available for data sets. This Web Service Method only works with the workgroup panel surveys. An exception is thrown if the survey type is not panel.




Method Call: AuthorizePanelistForSurvey

Description: Adds one panelist to the invitation queue for the specified project. The panelist will not be invited until invitations are sent from the project in EFM. This method supports user keys, which allows panelists to take the survey multiple times, (e.g., for course evaluations, userkey1 could be the course ID, userkey2 the professor's name, etc.)


projectId (int) A project ID panelistID (int) The panelist ID userkey1 (string) A key to allow the same

person to be invited multiple times; pass null if not used.

userkey2 (string) A key to allow the same person to be invited multiple times; pass null if not used.



longReturns: The new recordId


Exceptions: This Web Service Method is not available for data sets.This Web Service Method only works with workgroup panel surveys. An exception is thrown if the survey type is not panel.




Method Call: AuthorizeParticipantForSurvey

Description: Adds a participant to an email list or passcode survey. An exception will be thrown if the participant already exists. A participant is considered to already exist if email, key 1, key 2, and key 3 are identified to an existing record.


projectId (int) A project ID email (string) The participant's email address;

optional for Access List surveys; max 255 characters.




culture (string) The culture to be set for this participant, e.g. en-US. See http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx

NOTE For the Require a Passcode distribution method, a participant must specify at least one key. The email, key combination must be unique.








Method Call: AuthorizeParticipantForSMSSurvey

Description: Adds a participant to an SMS survey. An exception will be thrown if the participant already exists.


projectId (int) A project ID phoneNumber (string) The participant's phone

number (required, max 255 characters) userkey1 (string) A key to allow the same

person to be invited multiple times; pass null if not used.



culture (string) The culture to be set for this participant, e.g. en-US. See http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx





Chapter 4 - Web Services Data View Participant Information



View Participant Information

Method Call: GetAuthorizedParticipantCount

Description: Count the participants for this survey. To get a response count instead, use GetResponseCount.

NOTE Not valid for Open Participation surveys or for panel profiles.




intReturns: The number of participants authorized to respond to this survey - panelists for a panel survey, authorized participants for email List or Access List surveys.


Exceptions: None




Method Call: GetParticipantData

Description: Returns information about the participants for this survey including their completion status. See also: GetParticipantInformation.

NOTE Maximum of 10,000 records returned per call.




XMLNodeReturns: An XML representation of information about the participants, as follows:

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"culture="ISO-CODE"last_page="LAST PAGE USER VISITED"user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"url="URL TO START THE SURVEY"campaign_status="CAMPAIGN STATUS"http_referer="REFERRING URL"http_user_agent="WEB BROWSER'S USER AGENT"remote_addr="RESPONDENT'S IP ADDRESS"remote_host="RESPONDENT'S HOST NAME"initial_date="INITAL INVITATION SENT DATE"initial_status="INITIAL INVITATION STATUS"reminder1_date="FIRST REMINDER SENT DATE"reminder1_status="FIRST REMINDER STATUS"reminder2_date="SECOND REMINDER SENT DATE"reminder2_status="SECOND REMINDER STATUS"reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"





last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS

USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/></Participants>

Where Invite status:0 = Not Sent1 = Initial Invitation Sent2 = First Reminder Sent3 = Second Reminder Sent4 = Third Reminder Sent5 = Fourth Reminder Sent100 = Thank You Sent50 = Invalid Address51 = Unsubscribed

NOTE For SMS surveys, email= is replaced with: phone_number="123"


Exceptions: None

Method Call: GetParticipantData




Method Call: GetParticipantDataEx

Description: Returns information about a subset of participants for this survey, including their completion status.

NOTE Maximum of 10,000 records returned per call. See also: GetParticipantInformation.


projectId (int) A project ID inviteStatus (int) If not null, restrict results to this

invite status. Where Invite status:0 = Not Sent1= initial invite2 = 1st reminder etc.50 = invalid address

startTime (dateTime) If not null, restrict results to responses modified after this time

endTime (dateTime) If not null, restrict results to responses modified before this time

completedOnly (bool) If true, restrict results to participants who have completed the survey


XMLNodeReturns: Null if no matching records or an XML representation of information about the participants, as follows:

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"culture="ISO-CODE"last_page="LAST PAGE USER VISITED"user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"url="URL TO START THE SURVEY"campaign_status="CAMPAIGN STATUS"http_referer="REFERRING URL"http_user_agent="WEB BROWSER'S USER AGENT"remote_addr="RESPONDENT'S IP ADDRESS"remote_host="RESPONDENT'S HOST NAME"initial_date="INITAL INVITATION SENT DATE"initial_status="INITIAL INVITATION STATUS"reminder1_date="FIRST REMINDER SENT DATE"reminder1_status="FIRST REMINDER STATUS"





reminder2_date="SECOND REMINDER SENT DATE"reminder2_status="SECOND REMINDER STATUS"reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS




Exceptions: None

Method Call: GetParticipantDataEx




Method Call: GetParticipantDataPaged

Description: Returns information about participants for this survey.



projectId (int) A project ID inviteStatus (int) If not null, restrict results to this

invite status.0 = Not Sent1 = initial invite2 = 1st reminder etc.50 = invalid address

surveyStatus (enum) Restrict results to this participant status. surveyStatus is a serialized ParticipantStatus enumeration defined in thehttp://www.perseus.com/Pdc.WS namespace.Development tools such as Visual Studio willautomatically create this enum when generating aproxy class for the ProjectData web service.0 = Any status (all participants returned)1 = NotStarted2 = Started (excludes completed , branched out orover quota)3 = Completed (excludes branched out or over quota)4 = branched out (excludes completed or over quota)5 = over quota (excludes completed or branched out)

startRecordId (long) Return records greater than this record ID. If 0, start with the lowest record ID.

recordCount (int) Return no more records than this.


Returns: Null if no matching records or an XML representation of information about the participants, as follows:

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"culture="ISO-CODE"last_page="LAST PAGE USER VISITED"





user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"url="URL TO START THE SURVEY"campaign_status="CAMPAIGN STATUS"http_referer="REFERRING URL"http_user_agent="WEB BROWSER'S USER AGENT"remote_addr="RESPONDENT'S IP ADDRESS"remote_host="RESPONDENT'S HOST NAME"initial_date="INITAL INVITATION SENT DATE"initial_status="INITIAL INVITATION STATUS"reminder1_date="FIRST REMINDER SENT DATE"reminder1_status="FIRST REMINDER STATUS"reminder2_date="SECOND REMINDER SENT DATE"reminder2_status="SECOND REMINDER STATUS"reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/>

</Participants>

Where invitation status:0 - 30 = unopened31 - 40 = undelivered41 - 60 = bounce back



Exceptions: None

Method Call: GetParticipantDataPaged




Method Call: GetParticipantDataFiltered

Description: Returns information about filtered participants for this survey.



ProjectId (int) A project ID startTime (DateTime) Will add a filter to the query

for the following time fields:modifiedemailedinitial_datereminder1_datereminder2_datereminder3_datereminder4_datethankyou_date

so if any of them are greater than the one specified that record will be included

filterXml (string) XML specifying a set of Criterion objects used to filter the data<CriteriaCollection>

<Criterion leftparen="NUMBER OF LEFT PARENS"heading="DATABASE COLUMN" expression="OPERATOR"value="COMPARED VALUE"rightparen="NUMBER OF RIGHT PARENS"rule="AND|OR"/>

</CriteriaCollection>Operator is one of =, !=, <, >, <=,

>=



XMLNodeReturns: Null if no matching records or an XML representation of information about the participants, as follows:

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"started="START TIME"completed="COMPLETED TIME"





branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"modified="MODIFICATION TIME"invite_status="INVITATION STATUS"campaign_status="CAMPAIGN STATUS"culture="CULTURE ISO-CODE"user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"http_referer="URL OF THE REFERRING PAGE AT THE START THE SURVEY"http_user_agent="BROWSER USER AGENT STRING"remote_addr="IP ADDRESS"remote_host="HOSTNAME OR IP ADDRESS"initial_date="INITIAL INVITE TIME"initial_status="INITIAL INVITE STATUS"reminder1_date="1ST REMINDER SENT DATE"reminder1_status="1ST REMINDER STATUS"reminder2_date="2ND REMINDER SENT DATE"reminder2_status="2ND REMINDER STATUS"reminder3_date="3RD REMINDER SENT DATE"reminder3_status="3RD REMINDER STATUS"reminder4_date="4TH REMINDER SENT DATE"reminder4_status="4TH REMINDER STATUS"thankyou_date="THANK YOU TIME"thankyou_status="THANK YOU STATUS"close_date="INDIVIDUAL SURVEY CLOSE TIME"last_page="LAST PAGE USER VISITED"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"\url="URL TO START THE SURVEY"last_page_number="LAST PAGE NUMBER USER VISITED"modifier="MODIFICATION ID"/>

</Participants>

Where invitation status:0 - 30 = unopened31 - 40 = undelivered41 - 60 = bounce back70 = opened not started80 = started90 = unsubscribed98 = branched out99 = over quota100 = completed survey







Exceptions: SOAP exception for invalid project IDs, start time, or filter XML.





Method Call: SetParticipantInformation

Description: Change information about one or more participants.

CAUTION If you are working with a workgroup-panel survey and change the value of the "culture" attribute, it will override the panelist's default language and culture for that survey response. In addition, please note that the started, modified, and completed timestamp fields cannot be set to zero with this method.



the row(s) to be changed, in this format:<Rows>

<Row id="RECORDID"invite_status="STATUS" user_key1="KEY" user_key2="KEY" user_key3="KEY" culture="ISO-CODE" last_page="LAST PAGE USER VISITED" started="START TIME" modified="MODIFICATION TIME" completed="COMPLETED TIME" branched_out="BRANCHED OUT TIME" over_quota="OVER QUOTA TIME"campaign_status="CAMPAIGN STATUS"/>

</Rows>

Time syntax for started, modified, and completed: .Net UTC DateTime.Ticks.Where invite status:

1 = initial invite2 = 1st reminder etc.50 = invalid address


N/A




Permissions: Edit Participants

Exceptions: This Web Service Method is not available for data sets and does not apply to Open Participation surveys and Panel profiles.SOAP exceptions are immediately returned for all of the following fatal error conditions for all calls: If no participants with the provided recordID

are found. For Passcode survey, if userkeys combination

for a respondent record is already in use. For Email survey, if the email and userkeys

combination for a respondent record are already in use.

For Panel survey, if the panelID and userkeys combination for a respondent record are already in use.

For SMS survey, if the phone number and userkeys combination for a respondent record are already in use.

Method Call: SetParticipantInformation




Method Call: GetParticipantInformation

Description: Returns information about just one participant.See also: GetParticipantData.


projectId (int) A project ID recordId (long) Record ID for the participant


XMLNodeReturns: An XML representation of information about the participant, as follows:

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"culture="ISO-CODE"last_page="LAST PAGE USER VISITED"user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"url="URL TO START THE SURVEY"campaign_status="CAMPAIGN STATUS"http_referer="REFERRING URL"http_user_agent="WEB BROWSER'S USER AGENT"remote_addr="RESPONDENT'S IP ADDRESS"remote_host="RESPONDENT'S HOST NAME"initial_date="INITAL INVITATION SENT DATE"initial_status="INITIAL INVITATION STATUS"reminder1_date="FIRST REMINDER SENT DATE"reminder1_status="FIRST REMINDER STATUS"reminder2_date="SECOND REMINDER SENT DATE"reminder2_status="SECOND REMINDER STATUS"reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS








Exceptions: None

Method Call: GetParticipantInformation




Method Call: FindPanelistRecord

Description: Finds a respondent record ID given a panelist ID (and user keys, if necessary).


projectId (int) A project ID panelistId (int) ID of the panelist key1 (string) A key to allow the same panelist to

be invited multiple times; pass null if not used key2 (string) A key to allow the same panelist to

be invited multiple times; pass null if not used key3 (string) A key to allow the same panelist to

be invited multiple times; pass null if not used


longReturns: The recordId for the given panelist, or -1 if not found.


Exceptions: None

Method Call: FindPanelistsRecord

Description: Find participants given a panelist ID and user keys (if user keys are used in your survey).

NOTE Maximum of 1,000 records returned per call.


projectId (int) A project ID panelistsXml (string) An XML representation of

panelists to be found, in this format:<Panelists>

<Panelist> <ID>1234</ID> <UserKey1> optional </UserKey1> <UserKey2> optional </UserKey2> <UserKey3> optional </UserKey3>

</Panelist></ Panelists>


Returns an XML representation of found participants:, as follows:

<Result><Participant id="123456" /><Error>Incorrect data: Exception.Message</

Error><Error>Missing field: ID</Error></Result>


Exceptions: None




Method Call: FindParticipantRecord

Description: Find a participant using an email address and user keys (if user keys are used in your survey).


projectId (int) A project ID emailAddress (string) The email address of the

participant key1 (string) A key to allow the same participant

to be invited multiple times; pass null if not used key2 (string) A key to allow the same participant

to be invited multiple times; pass null if not used key3 (string) A key to allow the same participant

to be invited multiple times; pass null if not used


longReturns: The recordId for the given participant or -1 if not found.


Exceptions: None

Method Call: FindParticipantsRecord

Description: Find participants using an email address and user keys (if user keys are used in your survey).


projectId (int) A project ID participantsXml (string) An XML representation

of participants to be found, in this format:<Participants>

<Participant>

<EmailAddress>[email protected]</EmailAddress><PhoneNumber>123456</PhoneNumber><UserKey1> optional </UserKey1><UserKey2> optional </UserKey2><UserKey3> optional </UserKey3>

</Participant></Participants>


Returns an XML representation of found participants, as follows:

<Result><Participant id="123456" />< Participant id="-1" /><Error>Missing field: EmailAddress</Error></Result>


Exceptions: None




Method Call: FindSMSParticipantRecord

Description: Find a participant given a phone number (and user keys, if necessary).


projectId (int) A project ID phoneNumber (string) The phone number of the

participant key1 (string) A key to allow the same person to

be invited multiple times; pass null if not used. key2 (string) A key to allow the same person to

be invited multiple times; pass null if not used. key3 (string) A key to allow the same person to

be invited multiple times; pass null if not used.


LongThe recordId for the given participant, or -1 if not found.


Exceptions: None

Chapter 4 - Web Services Data Invitations



Invitations

Method Call: GetInvitationText

Description: Returns a re-creation of the email sent to this participant. Invitations are not saved when sent; we use the current text of the invitation in the survey.Compare GetInvitationTemplate, which returns the template for the email, without participant-specific information.


projectId (int) A project ID recordId (long) The internal ID of this

participant. invitationType (int)

0 = initial invite1 = 1st reminder etc.


StringReturns: An XML representation of the email of the given type for this participant.

Permissions: View Invitations

Exceptions: This Web Service Method is not available for SMS surveys




Method Call: GetInvitationTemplate

Description: Returns the invitation template for a given invitation type. The template is what is seen in the Invitation Designer, with placeholders (such as %URL%) that are replaced with participant information when previewing or sending invitations.


projectId (int) A project ID invitationType (int)



An XML representation of the invitation, as follows. If there are multiple cultures, there will be multiple Text elements.

<Message type="INVITATIONTYPE"><Subject>

<Text type="plain">SUBJECT LINE</Text>

</Subject><TextBody>

<Text type="plain">EMAIL BODY FOR NON-HTML MAILERS</Text>

</TextBody><HtmlBody>

<Text>EMAIL BODY FOR HTML MAILERS</Text>

</HtmlBody></Message>


Exceptions: None




Method Call: SetInvitationTemplate

Description: Change the invitation template for this invitation type. The components are the same as those returned by GetInvitationTemplate; don't include the elements, though.It's advisable to create invitations in the Invitation Designer, use GetInvitationTemplate to see how these invitations are saved, and use that information to create the strings to pass to this function.


projectId (int) A project ID subject (string) The subject line for the email htmlBody (string) The body of the email, for

mailers that support HTML textBody (string) The body of the email, for

mailers that can't display HTML culture (string) The culture this invitation is for,

e.g. en-US. For translated surveys, call this function once for each culture. Seehttp://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx

invitationType (int)0 = initial invite 1 = 1st reminder etc.


N/A


Exceptions: None




Method Call: SetMultipleInvitationStatus

Description: Change the invitation status level for a list of participants. This does not send email!This call does not trigger email to be sent out. The next time the system sends out an email the new status level of the participant will be used to determine if they are eligible to receive that email. For example, if you set a participant's status to Not Invited (0) and trigger the initial invite email to be sent that participant will be included in the emailing.


projectId (int) A project ID recordIds (long[]) List of record IDs. Invalid

record id values will be ignored. invitationStatus (int) The new invite status level.

One of the following values0 = Not Invited1 = Initial Invitation Sent2 = First Reminder Sent3 = Second Reminder Sent4 = Third Reminder Sent5 = Fourth Reminder Sent50 = Invalid Address


N/A






Method Call: SetInvitationStatus

Description: Change the invitation status for a participant. This does not send mail! But EFM will process further invitations as if it did. For example, if you set the status to 0 (not yet invited), then issue invites, this participant will get an initial invite.


projectId (int) A project ID recordId (long) The record ID for the participant invitationType (int)

0 = Not Invited1 = Initial Invitation Sent2 = First Reminder Sent3 = Second Reminder Sent4 = Third Reminder Sent5 = Fourth Reminder Sent50 = Invalid Address51 = Unsubscribed100 = Thank You Sent


N/A


Exceptions: None




Method Call: SendInvitationsEx

Description: Send out invitations of the specified type to a subset of participants.This call will send an email to a subset of participants that are at a status level that is one level back from the level of the email being sent. For example, if the email being sent is "Initial Invitation," it will be sent to participants with a status of "Not Sent."In another example, if you add 100 participants to a survey you can use this call to send out the initial invitation to a subset of them, say 50. If you want to resend an earlier email and there are participants at a later status you must first change the status of those participants using either SetInvitationStatus or SetMultipleInvitationStatus. Any participants not at the status level eligible for the requested email will be ignored.After the call the participants will be incremented to the next status level. Using SetInvitationStatus or SetMultipleInvitationStatus you can move them to another status after this call.


projectId (int) A project ID invitationType (int) The type of the email to go

out. One of the following values:0 = Initial Invitation1 = First Reminder2 = Second Reminder3 = Third Reminder4 = Fourth Reminder100 = Thank You

participantIds (long[]) An array of participant IDs. Invalid participant id values will be ignored.


N/A

Permissions: Send Invitations

Exceptions: This Web Service Method is not available for data sets and SMS surveys.




Method Call: SendInvitations

Description: Send out invitations of the given type.


projectId (int) The project ID. invitationType (int)



N/A

Permissions: Send Invitations

Exceptions: This Web Service Method is not available for data sets and SMS surveys




Method Call: GetCampaignHistory

Description: For the specified survey participant return an XML structure detailing the status of the emails sent to them.


projectId (int) A project ID for an email based survey.

participantId (long) The internal ID of this participant


XmlNode in the following format:<CampaignHistory>

<InitialInvite status="MAILING STATUS" time="MAILING TIME" /><FirstReminder status="MAILING STATUS" time="MAILING TIME" /><SecondReminder status="MAILING STATUS" time="MAILING TIME" /><ThirdReminder status="MAILING STATUS" time="MAILING TIME" /><FourthReminder status="MAILING STATUS" time="MAILING TIME" /><ThankYou status="MAILING STATUS" time="MAILING TIME" />

</CampaignHistory>

Where MAILING TIME is a human readable date/time of the last action associated with that mail (UTC).


Exceptions: None

NOTE For more details on MAILING STATUS, see Campaign Statuses, page 312.

Chapter 4 - Web Services Data Respondent Reports



Respondent Reports

Method Call: EmailLiveResultsReport

Description: Emails a Live Results report to the specified email address.

NOTE EmailLiveResultsReport sends the Live Results Report (a report that shows aggregate survey response statistics for multiple-choice questions) to a specified email address. If you want to send a Respondent Report (which shows a single individual's responses to a survey), use either the EmailResultsReport or EmailResultsReportToRespondent methods instead of this method.

The Live Results Report is attached to the email message as an HTML attachment, and the messageBody parameter controls what is displayed in the body of the email message. You can use properly-formed HTML text in this parameter.


projectId (int) A project ID fromAddress (string) Valid Sender Address toAddress (string) Valid Recipient Address messageSubject (string) Email Subject messageBody (string) Email Body


N/A

Permissions: View Results and Edit Panel Profiles

Exceptions: This Web Service Method is not available for Open Participation and SMS surveys




Method Call: EmailResultsReport

Description: Emails a Results report to the specified email address.

NOTE If you want to send a report to a survey respondent and do not know the respondent's email address (or you want EFM to automatically use the email address associated with the survey response), use EmailResultsReportToRespondent instead. EmailResultsReportToRespondent has almost exactly the same function signature and behavior as EmailResultsReport but eliminates the toAddress parameter.

If you select the "Respondent Report" type, the report is inserted inline into the body of the email message, and any text you pass in the messageBody parameter will be ignored. If you select the "Live Results Report" type, the report is attached to the email message as an HTML attachment, and the messageBody parameter controls what is displayed in the body of the email message. You can use properly-formed HTML text in this parameter.


projectId (int) A project ID respondentId (long) Respondent ID reportType (int)

0 = Respondent Report,1 = Live Results Report

highlightAnswers (bool) Whether to highlight answers if using Live Results Report

fromAddress (string) Valid Sender Address toAddress (string) Valid Recipient Address messageSubject (string) Email Subject messageBody (string) Email Body if using Live

Results Report


N/A






Method Call: EmailResultsReportToRespondent

Description: Emails a Results report to the Respondent's email address.

NOTE If you want to send a report to someone other than the survey respondent, use EmailResultsReport instead of this method. EmailResultsReport has almost exactly the same function signature and behavior as EmailResultsReportToRespondent but adds a toAddress parameter.

If you select the "Respondent Report" type, the report is inserted inline into the body of the email message, and any text you pass in the messageBody parameter will be ignored. If you select the "Live Results Report" type, the report is attached to the email message as an HTML attachment, and the messageBody parameter controls what is displayed in the body of the email message. You can use properly-formed HTML text in this parameter.


projectId (int) A project ID respondentId(long) Respondent ID reportType (int)

0 = Respondent Report,1 = Live Results Report

highlightAnswers (bool) Whether to highlight answers if using Live Results Report

fromAddress (string) Valid Sender Address messageSubject (string) Email Subject messageBody (string) Email Body if using Live

Results Report


N/A



Chapter 4 - Web Services Data Unsubscribed Emails



Unsubscribed Emails

Method Call: GetUnsubscribedStatus

Description: Return whether the specified email address is on the unsubscribed list or not.


emailAddress (string) Email address to query the unsubscribe list


BoolReturns true if the email address is on the unsubscribe list. False is returned for all other cases this includes being passed invalid addresses.

Permissions: View Unsubscribes

Exceptions: None




Method Call: UnsubscribeListAdd

Description: Add the specified email addresses to the unsubscribe list. People on this list will no longer receive email from the system.


emailAddresses (string[]) List of Email addresses to add to the unsubscribe list. Invalid or duplicate addresses will be ignored.


N/A

Permissions: Edit Unsubscribes

Exceptions: None




Method Call: UnsubscribeListRemove

Description: The specified email addresses to be removed from the unsubscribe list. People on this list will again receive email from the system.


mailAddresses (string[]) List of email addresses. Invalid addresses or addresses not already in the list will be ignored.


N/A

Permissions: Edit Unsubscribes

Exceptions: None

Chapter 4 - Web Services Data Update Borrowed Questions



Update Borrowed Questions

Method Call: UpdateBorrowedQuestions

Description: Questions can be borrowed from profiles into a survey, and responses sent back to the profile. Find the borrowed questions in the survey, look up the responses, and write the information back to the profiles for the associated panelists. It's not considered an error if there are no borrowed questions, or there are no responses to the survey, but of course nothing will be done in either of these cases.




N/A



Chapter 4 - Web Services Data Update Borrowed Questions



Method Call: UpdateBorrowedQuestionsForRespondent

Description: Questions can be borrowed from profiles into a survey, and responses sent back to the profile. Find the borrowed questions in the survey, look up the responses, and write the information back to the profiles for the referenced respondent (corresponding to the supplied record id).It's not considered an error if there are no borrowed questions, or there are no responses to the survey, but of course nothing will be done in these cases.


projectId (int) A project ID recordId (Long) Record ID of a respondent to

the survey


N/A



Chapter 4 - Web Services Data Validate a Single Response



Validate a Single Response

Method Call: ValidateSingleResponse

Description: Given a project id and record id this method will walk the values in the response and validate it against question destination, choice destinations, advanced branching, choice visibility and drill-down questions in the questionnaire. If responses are found that would not be possible with taking the survey normally they will be cleared. The list of cleared field names will be returned.


projectId (int) A project ID recordId (Long) Record ID of a respondent to

the survey


List of cleared fields:<Result>

<f id="QUESTION DB HEADING"></f></Result></returns>


Exceptions: SOAP exceptions for invalid access and invalid parameters.This Web Service Method is not available for data sets.




Method Call: GetSurveyEventHandler

Description: Get survey event handler properties for given project id.




<WebServiceHandlerProperties><URL>URL</URL><Format>JSON|XML</Format><AuthenticationToken>authentication token</AuthenticationToken><Events responseAmount="All|Page|None">

<Event type="StartPreResponse" enabled="true|false" /><Event type="StartPreSave" enabled="true|false" /><Event type="PagePreResponse" enabled="true|false" /><Event type="PagePreSave" enabled="true|false" /><Event type="EndPreResponse" enabled="true|false" /><Event type="EndPreSave" enabled="true|false" />

</Events></WebServiceHandlerProperties>


Exceptions: None




Method Call: SetSurveyEventHandler

Description: Set survey event handler properties for given project id.

NOTE The equivalent of clicking the Test button is performed. The event handler must correctly respond to the Test button.

The <URL> node is required. If it is empty, the event handler will be cleared.If specified, it must be a valid URL.The <Events> node is required. It can be empty.


projectId (int) A project ID eventHandlerProperties (string) String of XML,

in the same format returned by GetSurveyEventHandler


N/A



Chapter 4 - Web Services Data Translations



Translations

Method Call: GetSurveyTranslations

Description: Add language to survey in UI Call GetSurveyTranslations to get XML with

placeholders for translation Returns string in XLIFF format with translatable

strings of the survey project (XML Localization Interchange File Format - http://en.wikipedia.org/wiki/XLIFF)


projectId (int) A project ID targetCulture (string) A comma-separated list of

target cultures. Cultures not already added to the survey will be ignored. If null or empty, all languages in the survey will be returned.


<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"><file original="18d1fdae.que" source-language="en-US" target-language="fr-CA" datatype="plaintext">

<body><trans-unit id="WebLabels_NextCaption" datatype="plaintext">

<source>Next</source><target>Suivant</target>

</trans-unit></body>

</file><file original="18d1fdae.que" source-language="en-US" target-language="es-ES" datatype="plaintext">


<source>Next</source><target>Siguiente</target>


</file></xliff>

Permissions: Translate Survey

Exceptions: None




Method Call: SetSurveyTranslations

Description: Set or change the translations of survey items. Call SetSurveyTranslations with modified XML.


projectId (int) - A project ID. translatedXml (string) - Text in XLIFF format

(XML Localization Interchange File Format - http://en.wikipedia.org/wiki/XLIFF) with translatable strings of the survey project.

Structure of XLIFF string <xliff> - root tag with XLIFF xml namespace

attribute <file> - child tag of xliff document

- "original" attribute - questionnaire file extension

- "source-language" attribute - base culture, by default it is "en-US"

- "target-language" attribute - translation language

<body> - child tag of the <file> tagFor every survey translatable label xml should contain <trans-unit> tags with 4 attributes: id - translated label id datatype - optional attribute, by default it is

"plaintext" <source> - child tag of <trans-unit>, contains

label in base language <target> - child tag of <trans-unit>, contains

translated labels for target language<trans-unit id="LabelId"

datatype="plaintext"><source>value</source><target>value</target>

</trans-unit>





Example of translatedXml parameter:<xliff version="1.2"

xmlns="urn:oasis:names:tc:xliff:document:1.2"><file original="18d1fdae.que" source-language="en-US" target-language="fr-CA" datatype="plaintext">


<source>Next</source><target>Suivant</target>


</file><file original="18d1fdae.que" source-language="en-US" target-language="es-ES" datatype="plaintext">


<source>Next</source><target>Siguiente</target>


</file></xliff>


N/A

Permissions: Translate Survey

Exceptions: The languages have to be added to the survey through the UI. You can't pass in an XML string with new languages and have them show up in the survey.

If project was deleted or permanently deleted - method returns exception.

If XML string has incorrect structure - method generates parsing exception.

NOTE For a "trans-unit" that does not have a unique "id=" like "Text Blocks", lookup is done using "source" text.

Method Call: SetSurveyTranslations




Method Call: EvaluateTriggers

Description: Evaluate survey triggers for the specified responses (record IDs).


projectId(int) - A project IDrecordIds (long[]) - Array of record IDs.


Returns: String with XML which describes what triggers were evaluated.Example:

<Result><Error id="635125146990977610">No response for the specified record id.</Error><Record id="635050091948477676">

<Trigger Description="t2" sentEmail="True" createdCase="True"/><Trigger Description="t" createdCase="True"/>

</Record><Error id="635125146991133669">No response for the specified record id.</Error>

</Result>

Permissions: Email Triggers

Exceptions: None

Chapter 4 - Web Services Data Web Service paneldata.asmx



Web Service paneldata.asmxThis Web Service exposes the panel system.


Add/Modify/Delete Panelists

Method Call: AddPanelist

Description: Adds or updates a panelist with the given information; returns panel ID. If externalId matches an existing panelist that record will be updated


email (string) Email address firstname (string) First name; maximum 255

characters lastname (string) Last name; maximum 255

characters culture (string) Culture, e.g. "en-US". See http:/

/msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx

externalId (string) External ID; these must be unique per panelist. Can be the key for a foreign data system; or just use the email address if desired. Maximum 255 characters.

sourcedesc (string) Can be used to identify where this panelist comes from. Maximum 255 characters.


intReturns: The new panelistid (or the existing one, if there is an update)

Permissions: Create Members

Exceptions: None

Chapter 4 - Web Services Data Add/Modify/Delete Panelists



Method Call: RemovePanelist

Description: Removes a panelist. This is actually a soft delete; the panelist is simply marked as deleted.


panelistID (int) The panelist ID


N/A

Permissions: Delete Members

Exceptions: None

Chapter 4 - Web Services Data Add/Modify/Delete Panelists



Method Call: SetExternalId

Description: Change the external ID for a panelist. (By contrast, AddPanelist will assume that a new external ID is a new panelist.)


panelistId (int) The panelist ID key (string) The new external ID


N/A

Permissions: Edit Members

Exceptions: None

Chapter 4 - Web Services Data Find Panelists



Find Panelists

Method Call: GetPanelistCount

Description: Return the number of defined panelists.


status (int)-1=all, 0=active, 1=suspended, 2=deleted


intReturns: The count

Permissions: View Members

Exceptions: None




Method Call: FindPanelist

Description: Find the panel ID of the panelist with the given external ID.


key (string) The external ID to search for


intReturns: The internal panelist ID, if found, otherwise 0


Exceptions: None




Method Call: FindPanelistsLike

Description: Finds panelists with a first name, last name, or email address like the target. We use soundex to test approximations to the name.


name (string) The target name


int[]Returns: An array of integer panelist IDs


Exceptions: None




Method Call: GetPanelistList

Description: Return the IDs of all active panelists. This method may return a very large array; use other methods (i.e., EVAL and FIND) to search more selectively.


sortColumn (int)0 = no sort 1 = panelistID2 = email3 = first name4 = last name


int[]Returns: An array of integer panelist IDs


Exceptions: None




Method Call: GetPanelistData

Description: Get basic information about a set of panelists.


panelists (int[]) An array of integer panelistIds, such as returned by several other Web Methods

index (int) Where in the array to start; this and the next parameter can be used to page through the array.

count (int) How many panelists to return. Maximum of 500 at a time.


XMLNodeReturns: An XML representation of the data, as follows:

<Panelists><Panelist recordid="RECORD ID" panelistid="PANELIST ID" status="Active|Suspended|Deleted" created="CREATION TIME" modified="LAST MODIFICATION TIME" invited="PORTAL INVITE TIME" reminded="PORTAL REMINDER TIME" joined="PORTAL JOIN TIME" externalid="EXTERNAL ID">

<Email>EMAIL</Email><FirstName>FIRST NAME</FirstName><LastName>LAST NAME</LastName><Source source="SOURCE TYPE">SOURCE DESCRIPTION</Source>

</Panelist></Panelists>


Exceptions: None

Chapter 4 - Web Services Data



Method Call: GetPanelistInformation

Description: Returns the information stored in the master panel (that is, the basic information profile) for the specified panelist.


panelistID (int) The panelist ID


XmlNodeReturns: An XML representation of the data, in the same format as GetPanelistData


Exceptions: None

Chapter 4 - Web Services Data Audit Panelists Actions



Audit Panelists Actions

Method Call: GetPanelistActions

Description: Return all the actions undertaken by this panelist for this project.


panelistID (int) The panelist ID projectID (int) The project ID


DataSetReturns: A DataSet: http://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.Action:

Invitation Emails:Initial InviteFirst ReminderSecond ReminderThird ReminderFourth ReminderThankYouPortal Emails:LostPassword MemberAccountChangeNewMemberInvitationEmailReminderInvitationEmailWelcomeEmailRegisteredMemberConfirmationMembershipPendingApprovalMiscellaneous:ReserveStartedSurveyCompletedSurveyMailFailurePortalLoginOptOut

= 0= 1= 2= 3= 4= 100

= 1000= 1001= 1002= 1003= 1004= 1005= 1006

= 40= 20= 21= 50= 75= 76

Permissions: Audit Users

Exceptions: None



Chapter 4 - Web Services Data Saved Panel Filters Query



Saved Panel Filters Query

Method Call: AddPanelFilter

Description: Given an XML representation (same format returned by GetPanelFilter), create a new private panel filter and return its filterId.


filterName (string) The name of the saved panel filter.

filterXml (string) The filter in the same format returned by GetPanelFilter.


filterId(int)

Permissions: Edit Panel Filters

Exceptions: None




Method Call: GetPanelFilterCount

Description: Return the number of saved panel filters visible to the logged-in user.If the user is a group or Survey Administrator, they will be able to see all filters.If the user is not an administrator, they can always see their own shared and private filters; but they must have the "View Filters" permission to see other users' shared filters.


status (int)0 = shared filters1 = private filters


intReturns: The number of saved panel filters

Permissions: View Panel Filters

Exceptions: None




Method Call: GetPanelFilterList

Description: Returns a list of the panel filters visible to the logged-in user. See GetPanelFilterCount above for details on what filters are visible.


status (int)0 = shared filters1 = private filters


XmlNodeReturns: An XML representation of the filters, as follows:

<Filters><Filter id="FILTER ID" userid="OWNER ID" created="CREATION DATE" shared="Shared|Private">

<Name>FILTER NAME</Name></Filter>

<Filters>


Exceptions: None




Method Call: GetPanelFilter

Description: Returns a representation of a particular panel filter.


filterid (int) The ID of the saved panel filter


XmlNodeReturns: An XML representation, as follows:

<CommunityFilter numbercompleted="NUMBER" numbercompletedcompare="COMPARE" lastcompleteddays="# DAYS" lastcompletedcompare="COMPARE" lastinviteddays="# DAYS" lastinvitedcompare="COMPARE" createddays="# DAYS" createdcompare="COMPARE" portalstatus="Undefined|NotInvitedNotJoined|InvitedNotJoined|Joined"sourcetype="SOURCE" status="STATUS" soundex="true|false"><Criterion leftparen="NUMBER OF LEFT PARENS" namespace="PROFILE ID" heading="DATABASE COLUMN" expression="OPERATOR" value="COMPARED VALUE" rightparen="NUMBER OF RIGHT PARENS" rule="AND|OR" />

</CommunityFilter>

Status is one of: 0 = active 1 = suspended 2 = deleted

Source is one of:-1 = unknown 0 = unknown 2 = profile 3 = UI 4 = Web Service 5 = external program 6 = data table 7 = previous EFM version 8 = Active Directory 9 = Respondent Portal

Operator is one of = != < > <= >=.The COMPARE fields are one of None, Equal, NotEqual, LessThan, GreaterThan, LessThanOrEqual, GreaterThanOrEqual, Soundex.





Exceptions: None

Method Call: GetPanelFilter




Method Call: SetPanelFilter

Description: Replaces a panel filter with the filter as specified in an XML representation.

CAUTION Be very careful, as no validation is done.


filterid (int) The ID of the saved panel filter. filterXml (string) The filter in the same format

returned by GetPanelFilter.


N/A


Exceptions: None




Method Call: SharePanelFilter

Description: Set the shared/private status for a particular panel filter.


filterid (int) The ID of the saved panel filter. share (bool) Whether the filter should be visible

to others in the workgroup


N/A


Exceptions: None

Chapter 4 - Web Services Data Add/Remove Panel Filters



Add/Remove Panel Filters

Method Call: RemovePanelFilter

Description: Removes a panel filter.

CAUTION This is a hard delete; the panel filter cannot be recovered after deletion.




N/A

Permissions: Delete Panel Filters

Exceptions: None

Chapter 4 - Web Services Data Evaluate Filters (Saved or Ad Hoc)



Evaluate Filters (Saved or Ad Hoc)

Method Call: EvaluateSavedPanelFilter

Description: Evaluates the given saved panel filter.




int[]Returns: An array of matching panelistIds which can be passed to GetPanelistData

Permissions: View Member Filters and View Members

Exceptions: None




Method Call: EvaluateSimplePanelFilter

Description: Evaluates a simple panel filter, with just one criterion, returning a list of matching panelist IDs. This method is provided to allow quick tests without the complexities of writing filtering XML as for EvaluateXmlPanelFilter


projectId (int) The project ID of the panel profile to test against; pass 1000 for the basic profile

heading (string) The database heading of the column to test operationStr (string) The operation: = != < > <= >=

value (string) The value to test against


int[]Returns: An array of matching panelistIds which can be passed to GetPanelistData


Exceptions: None




Method Call: EvaluateXmlPanelFilter

Description: Evaluate an ad hoc panel filter. (The filter is not saved in the database.)


filterXml (string) The filter in the same format returned by GetPanelFilter


int []Returns: An array of matching panelistIds which can be passed to GetPanelistData


Exceptions: None

Chapter 4 - Web Services Data Profile Data



Profile Data

Method Call: GetProfileInformation

Description: Get the information for the panelist in a particular profile.

NOTE For additional filtering options, you can also query profile surveys using the GetSurveyDataEx and GetSurveyDataPaged project web service functions.


panelistID (int) The ID of the panelist profileID (int) The project ID of the panel profile


XmlNodeReturns: An XML representation of the data, as follows; or null if there is none. type=Text is used for Essay questions only.

<Rows><Row id="RECORDID" panelistid="PANELISTID">

<Field id="DBHEADING" type="Int|BigInt|Varchar|Text|Float">VALUE</Field>

</Row></Rows

Permissions: View Panel Profiles

Exceptions: None

Chapter 4 - Web Services Data Profile Data



Method Call: SetProfileInformation

Description: Set column values for a particular profile for a panelist, for one or more rows.


profileID (int) The ID of the profile valuesXml (string) XML specifying the data to

change, in the same format returned by GetProfileInformation. The Row nodes must contain a panelistid; any recordid will be ignored. Rows with invalid panelistid will be ignored. To update multiple panelists, include several Row nodes.


N/A

Permissions: Edit Member Profiles

Exceptions: None

Chapter 4 - Web Services Data Authorized Surveys



Authorized Surveys

Method Call: GetSurveysForPanelist

Description: For a specific panelist id, return a list of surveys for all the survey projects that the panelist has been invited to, checking the publishing mode and completion status as desired.A panelist may be invited to the same survey multiple times using different user keys; in this case there will be multiple Survey nodes, with different recordids.


panelistId (int) The ID of the panelist publishMode (int)

-1 = all 0 = design 1 = open 2 = closed

uncompletedOnly (bool) Whether to restrict the query to ignore completed surveys

startedAfter (dateTime) If not null or DateTime.MinValue, return only responses started after this date/time

startedBefore (dateTime) If not null or DateTime.MaxValue, return only responses started before this date/time


XmlNodeReturns: An XML representation, as follows. There can be up to three Userkey* nodes.

<Surveys><Survey id="PROJECT ID" publish="Created|Testing|Open|Closed" recordid="RECORDID" started="START TIME" modified="MODIFICATION TIME" completed="COMPLETED TIME" branched_out="BRANCHED OUT TIME" over_quota="OVER QUOTA TIME" >

<Name>SURVEY NAME</Name><Userkey1>USERKEY</Userkey1><URL>SURVEY URL</URL>

</Survey></Surveys>

Permissions: View Members and View Surveys

Exceptions: None

Chapter 4 - Web Services Data Authorized Surveys



Method Call: GetSurveyStatusForPanelist

Description: Returns the panelist's status in regard to the specified survey.


projectId (int) The project ID of the survey panelistId (int) The ID of the panelist


intReturns:

0 = not started1 = started but not completed9999 = completed

Permissions: View Members and View Surveys

Exceptions: None

NOTE This method has been deprecated. Use GetParticipantInformation or one of the GetParticipantData methods instead.

Chapter 4 - Web Services Data Portal Emails



Portal Emails

Method Call: SendPortalEmails

Description: Send out the requested email to a group of panelists.


panelistIds (int[])An array of 32bit integers representing a subset of panelists to receive the email. Maximum 500 panelists at a time. Invalid panelist IDs will halt the mailing process.

mailingType (int) The type of the email to go out.1 = SendPortalInvitation2 = SendPortalReminder3 = SendPortalWelcome


N/A

Permissions: View Members and Send Invitations

Exceptions: None

Chapter 4 - Web Services Data Web Service bulk.asmx



Web Service bulk.asmxWhen handling XML responses from the Web Service calls, your applications should be able to handle additional, undocumented values in the XML as we may add additional attributes or elements in future versions of this API.

Method Call: BulkImportPanelists

Description: This web service allows you to upload up to 500 panelists and their associated profile data at one time. In addition to the 500 panelist limit, there is a limit of 500 megabytes on the size of the transmitted XML. For each panelist the external id will be checked, if it matches an existing panelist that record will be updated otherwise a new panelist will be added. If an external id is not specified the email field will be used.For each panelist node passed in, one will be returned in the same order indicating success or failure of the insert or update. For success the new panelist id will be returned otherwise it will be information about the error that occurred. For profile data only errors are returned. If there are errors with the panelist data no profile data will be processed. If there are errors with the profile data the error will be recorded and processing will skip to the next profile or panelist.


panelistsXml (string)<Panelists importNew="Optional: indicate that

this is an initial load of new panelists. Default being false."><Panelist id="Optional: panelist id">

<Email>Email address (max 255)</Email> (Can be blank if ExternalId is specified)<FirstName>First name (max 255)</FirstName><LastName>Last name (max 255)</LastName><Culture>Optional: Culture </Culture>(see http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx)

<ExternalId>Optional: (max 255)</ExternalId>(Must be unique per panelist. Can be the key for a foreign data system; or if not specified the email address will be used.)<Source> Optional: String that describes the source of panelist (imported filename) </Source><Status>Optional value: 'Active|Deleted'</Status><Unsubscribe>Optional value: true|false. </Unsubscribe>(Use 'true' to mark the panelist unsubscribed)<DisplayName>Display name used in the portal</DisplayName><Password>Password for panelist to login into VCBM</Password><Approved>DateTime</Approved><Invited>DateTime</Invited><Registered>DateTime</Registered><Reminded>DateTime</Reminded><Profile id="12345678">

<f id="Q1">Value</f></Profile>

</Panelist></Panelists>


XMLNodeReturns an XML representation, as follows:

<!-One Panelist element for every Panelist element passed in. Returned order is same as sent.

Unless explicit errors are returned all data is successfully committed. If there are errors only the items that are noted should be addressed (i.e., no rollback of other data). -->

<Result><!-- New panelist added and new id returned -

-><Panelist id="123456"/><!-- Existing panelist updated. Id returned -

->

<Panelist updated="true" id="123456" /><Error>Incorrect data: Exception.Message</Error>

<Error>Missing fields: Email, First Name, Last Name</Error>

</Panelist><Panelist id="123456">

<Profile id="64989878"><Error>Incorrect data: Exception.Message</Error><Error>Incorrect data: Exception.Message</Error>

</Profile></Panelist>

</Result>


Exceptions: This Web Service Method is not available for data sets. SOAP exceptions are immediately returned for all the following fatal error conditions for all calls. Invalid Access Incorrect Permission Invalid Survey Type for the requested action Invalid passed in XML




Method Call: BulkAuthorizeParticipants

Description: This web service allows you to upload and authorize up to 500 participants to take the specified survey. For each participant, you can also optionally include preload data (this is data that will be loaded into a participant's response record when they start the survey).The specified project must either be an email list or phone numbers list, external access or panel survey. If the project is in open participation mode an error will be returned. For email list or external access surveys email address will be the key. For panel surveys you can pass in the panelist id or the external id (we will look up the panelist id). For SMS surveys phone numbers list will be the key.For each participant the email address or phone number (for SMS surveys) or panelist id plus up to three user keys will be checked, if it matches an existing participant that record will be updated otherwise a new participant will be added. For each participant node passed in one will be returned in the same order indicating success or failure of the insert or update. For success the new participant id will be returned otherwise it will be information about the error that occurred.If this is a new participant being added and there are errors with the preload data, the participant will not be authorized to take the survey. However, if this is an update to an existing record and there are preload errors, the participant will not be unauthorized.The key field for identifying a panelist is the external id. This can be the same as the email or different. If you do not specify an explicit external id, the email field is used to look in the external id field (for those customers that use email as the external id). If your external id is different from the email address that is the value, you have to pass to the method.

projectId (int) A Project ID participantsXml (string)

<Participants><Participant>





<Email>Email</Email><PhoneNumber>Phone number</PhoneNumber><PanelistId>Panelist Id</PanelistId><ExternalId>Panelist external Id</ExternalId>



<UserKey1>Optional user key</UserKey1><UserKey2>Optional user key</UserKey2><UserKey3>Optional user key</UserKey3><Culture>Culture </Culture>

(see http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx)

<Preload><f id="Q1">Value</f>

</Preload></Participant>

</Participants>


XmlNodeReturns an XML representation, as follows:



<Result><Participant id="12345678" url="http://example.com/se.ashx?s=ABCD1234" />

<Participant>

<Error>Incorrect data: Exception.Message</Error>

</Participant>

<Participant>

<Error>Incorrect data: Exception.Message</Error><Error>Incorrect data: Exception.Message</Error>

</Participant></Result>

Permissions: Import Participants

Exceptions: This Web Service Method is not available for data sets. SOAP exceptions are immediately returned for all of the following fatal error conditions for all calls. Invalid Access Incorrect Permission Invalid Survey Type for the requested action Invalid passed in XML

Method Call: BulkImportResponses

Description: This web service allows you to upload up to 500 survey records (and associated response data) in one call. For each Record node passed in one will be returned in the same order indicating success or failure.If you want to evaluate survey triggers for the specified imported responses, include an attribute <Records evaluateTriggers="true">If a “modified” value is not passed, the current time will be used.If campaign status is not specified, it will be set based on the non-null dates.


projectid (int) A Project ID responseXml (string)

<Records evaluateTriggers="true|false"><Record>

<f id="Q1"></f>

<id> Record ID of participant </id><started> DateTime </started><completed> DateTime </completed><branched_out> DateTime </branched_out><over_quota> DateTime </over_quota><modified> DateTime </modified>

(e.g. 2011-06-29T10:29:52.5711135)<culture> Culture </culture>

(e.g. en-US)(see http://msdn2.microsoft.com/en-us/library/

system.globalization.cultureinfo.aspx)<http_referer> Referrer </http_referer>

(e.g. http://www.example.com)<http_user_agent> Browser string</http_user_agent>

(e.g. Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)<remote_addr> e.g. 127.0.0.1</remote_addr><remote_host> e.g. 127.0.0.1</remote_host><last_page> Last page viewed </last_page>

(e.g. /surveys/621885253/5d3ec38e.htm)<last_page_number> Last page number viewed (e.g. 10) </last_page_number>

<panelistid> Panelist Id (Panel surveys only) </panelistid><email> Email address </email><phone_number> Phone Number (Required for SMS surveys instead of email)</phone_number><user_key1> User key 1 </user_key1><user_key2> User key 2 </user_key2><user_key3> User key 3 </user_key3>

<invite_status> Invitation Status</invite_status><campaign_status> Overall Campaign Status </campaign_status><initial_date> Initial email date</initial_date><initial_status> Initial email status</initial_status><reminder1_date> Reminder 1 email date</reminder1_date><reminder1_status> Reminder 1 email status </reminder1_status><reminder2_date> Reminder 2 email date</reminder2_date><reminder2_status> Reminder 2 email status </reminder2_status><reminder3_date> Reminder 3 email date </reminder3_date><reminder3_status> Reminder 3 email status </reminder3_status><reminder4_date> Reminder 4 email date </reminder4_date><reminder4_status> Reminder 4 email status </reminder4_status><thankyou_date> Thank You email date </thankyou_date><thankyou_status> Thank You email status </thankyou_status><close_date> Close date for this response </close_date>

(transactional surveys only)</Record>

</Records>

<Result><Record id="123456"/>

<Trigger Description="Description1" sentEmail="True" createdCase="True"/><Trigger Description="Description2" createdCase="True"/>

</Record><Error> Incorrect data: Exception.Message</Error>

</Result>


Exceptions: This Web Service Method is not available for data sets. This Web Service Method is not available for profile surveys.SOAP exceptions are immediately returned for all the following fatal error conditions for all calls. Invalid Access Incorrect Permission Invalid Survey Type for the requested action Invalid passed in XML

Method Call: BulkChangeResponses

Description: Allows you to update existing responses (up to 500) for a project in one call even if there are errors (non-fatal) in the transmitted XML. For each Record node passed in, one will be returned in the same order indicating success or failure.


projectId (int) - A project ID dataString (string) - XML for each record:

<Records><Record id="634635537507737461">

<f id="Q1"></f>

<started> DateTime </started><completed> DateTime </completed><branched_out> DateTime</branched_out><over_quota> DateTime </over_quota><modified> DateTime </modified>

(e.g. 2011-06-29T10:29:52.5711135)<culture> culture </culture>

(e.g. en-US)(see http://msdn2.microsoft.com/en-us/library/

system.globalization.cultureinfo.aspx)<http_referer> Referrer (e.g. http://www.example.com) </http_referer><http_user_agent> Browser string </http_user_agent>

(e.g. Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0))

<remote_addr> eg 127.0.0.1</remote_addr><remote_host> eg 127.0.0.1</remote_host><last_page> Last page viewed </last_page>

(eg /surveys/621885253/5d3ec38e.htm)<last_page_number> Last page number viewed (eg 10) </last_page_number

<panelistid> Panelist Id </panelistid><email> Email address </email><phone_number> Phone Number (Required for SMS surveys instead of email)</phone_number><user_key1> User key 1 </user_key1><user_key2> User key 2 </user_key2><user_key3> User key 3 </user_key3>

<invite_status> Invitation Status </invite_status><campaign_status> Overall Campaign Status </campaign_status><initial_date> Initial email date </initial_date><initial_status> Initial email status </initial_status><reminder1_date> Reminder 1 email date </reminder1_date><reminder1_status>Reminder 1 email status</reminder1_status><reminder2_date> Reminder 2 email date </reminder2_date><reminder2_status>Reminder 2 email status</reminder2_status><reminder3_date> Reminder 3 email date </reminder3_date><reminder3_status>Reminder 3 email status</reminder3_status><reminder4_date> Reminder 4 email date </reminder4_date><reminder4_status>Reminder 4 email status </reminder4_status><thankyou_date> Thank You email date </thankyou_date><thankyou_status> Thank You email status </thankyou_status><close_date> Close date for this response </close_date>(transactional surveys only)

</Record></Records>




<Result><Record id="634635537507737461"/><Error> Incorrect data: Exception.Message </Error>

</Result>



Method Call: BulkChangeResponses

Method Call: BulkGetPreloadData

Description: Allows you to get preload data for participants (up to 500).


projectId(int) - A project ID recordIds (long[]) - Array of record IDs



<PreloadData><Preload id="634665465332558180">

<f id="Q1">Value</f></Preload>

<Preload id="634665465332558181"/>

<!-- Participant not found error messages. --

><Error> Invalid record id specified: id </Error>

</PreloadData>


Exceptions: None

Method Call: BulkSetPreloadData

Description: Allows you to set or clear the preload data for participants. To clear a specific field the field element should not have any value(i.e <f id="Q1"/>). To clear all fields the preload element should not have any value (i.e <Preload id="634665465332782796"/>).


projectId (int) - A project IDpreloadDataXml (string) - XML of preload data<PreloadData>

<Preload id="634665465332558180"><f id="Q1">Value</f>

</Preload>

<Preload id="634665465332558181"/>

<Preload id="634665465332558182"><f id="Q1" /><f id="Q2">Value</f>

</Preload></PreloadData>




<Result><Participant id="634665465332558180" />

<Participant id="634665465332558181"><Error>Incorrect data: Exception.Message</Error><Error>Field name: Q11 does not match any questions in this survey.</Error>

</Participant><Error> Invalid record id specified: id </Error>

</Result>




Permissions: Import Participants


Method Call: BulkSetPreloadData

Method Call: BulkSetParticipantInformation

Description: Allows you to change information about one or more participants.


projectId (int) A project ID dataString (string) An XML representation of the

row(s) to be changed, in this format:<Rows>

<Row id="RECORDID"invite_status="STATUS" user_key1="KEY"user_key2="KEY" user_key3="KEY"culture="ISO-CODE" last_page="LAST PAGEUSER VISITED" started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME"branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"campaign_status="CAMPAIGN STATUS"/>

</Rows>

Time syntax for started, modified, and completed:.Net UTC DateTime.Ticks.Where invite status:

1 = initial invite2 = 1st reminder etc.50 = invalid address


<Result><Participant id="634665465332558181">

<Error>User with the same email and user keys already exist.</Error>

</Participant><Error> No record id specified. </Error><Error> Invalid participant id: id </Error>

</Result>




Method Call: BulkClearResponses

Description: Allows you to clear responses without deleting theparticipants.

Parameters:(name, type,description)

projectId (int) - A project ID recordIds (long[]) - List of record IDs edit

Return Value &Description:


<Result><Record id="634635537507737461" /><Error>Unable to clear the specifiedrecord: 634635537507737462.</Error>

</Result>

Permissions: Delete results.

Exceptions: This Web Service Method is not available for datasets.

Chapter 4 - Web Services Data Web Service for casedata.asmx



Web Service for casedata.asmx When handling XML responses from the Web Service calls, your applications must be able to handle additional, undocumented values in the XML as we may add additional attributes or elements in future versions of this API.

Method Call: FindMatchingCases

Description: Find matching cases.


owner (int) If a userid is passed, cases currently assigned to that user will be returned. If zero is passed, this parameter will be ignored.

status (int) Filters cases based on status. Values are as follows:Open = 0Closed = 1OnHold = 2

priority (int) Filters cases based on priority. If zero is passed, this parameter will be ignored.


int[]Returns:Array of matching case IDs.

Permissions: View Cases or View All Cases

Exceptions: SOAP exceptions for invalid parameters specification.




Method Call: CreateCase

Description: Create new case from specified XML string


caseXml (string) An XML representation of the case, as follows:<Case priority="CASE PRIORITY">

<Title>Case title</Title><Description>Case description</Description><ProjectId>Project id</ProjectId><RecordId>Record id</RecordId><Assigned>UserID or user name of user to whom the case is to be assigned. Omit this node to create an unassigned case.</Assigned><ContactFirstName>The first name of the contact person</ContactFierstName><ContactLastName>The last name of the contact person</ContactLastName><ContactPhone>The phone number of the contact person</ContactPhone><ContactBusiness>The company name of the contact person</ContactBusiness><ContactEmail>The email of the person who can provide the detailed information about the case</ContactEmail>

</Case>

Note: With the EFM 15.1 FP3, the case description can contain up to 65 K characters.


intReturns:The CaseID of a new case.

Permissions: Create Cases

Exceptions: Exceptions are thrown if Title is not specified.




Method Call: CreateCaseEx

Description: Create new case from specified xml string with the notifyUsers option.


caseXml (string) An XML representation of the case, as follows:<Case priority="CASE PRIORITY">

<Title>Case title</Title><Description>Case description</Description><Assigned>UserID or user name of user to whom the case is to be assigned. Omit this node to create an unassigned case.</Assigned><ContactFierstName>The first name of the contact person</ContactFierstName><ContactLastName>The last name of the contact person</ContactLastName><ContactPhone>The phone number of the contact person</ContactPhone><ContactBusiness>The company name of the contact person</ContactBusiness><ContactEmail>The email of the person who can provide the detailed information about the case</ContactEmail>

</Case>

notifyOwner (bool) Defines whether to send notification to case owner (if user setting allows case emails.)

notifyUsers (List<string>) List of EFM users, can consist of UserID, email, or username. For example, [email protected]: With the EFM 15.1 FP3, the case description can contain up to 65 K characters.


intReturns:The CaseID of a new case.

Permissions: Create Cases

Exceptions: Exceptions are thrown if Title is not specified.




Method Call: EditCase

Description: Edit case.


caseId (int) Case ID to edit caseXml (string) XML representation of the case

as follows:<Case priority="1-7" status="CASE STATUS">

<Title>Case title</Title><Description>Case description</Description><ProjectId>Project id</ProjectId><RecordId>Record id</RecordId><Assigned>UserID or user name to whom the case is to be assigned</Assigned><ContactFirstName>The first name of the contact person</ContactFirstName><ContactLastName>The last name of the contact person</ContactLastName><ContactPhone>The phone number of the contact person</ContactPhone><ContactBusiness>The company name of the contact person</ContactBusiness><ContactEmail>The email address of the person, who can provide the detailed information about the case</ContactEmail><CustomProperties>

<Propertyname="PROPERTY_NAME">PROPERTY_VALUE</Property>

</CustomProperties></Case>

Where case status:Open = 0Closed = 1OnHold = 2

Note: With the EFM 15.1 FP3, the case description can contain up to 65K characters.

NOTE The id= attribute of the Assigned node will be ignored if present.





XMLNodeReturns:XML representation, as follows:

<Result><Case id="CASE_ID" status="success" /> - this element returns for cases where the case has been edited successfully<Error>ERROR_TEXT</Error> - this element returns for cases where the case edit has failed to add

</result>


Exceptions: SOAP exceptions for invalid case ID.

Method Call: EditCase




Method Call: EditCaseEx

Description: Edit case with the notifyUsers option.


caseId (int) Case ID to edit caseXml (string) XML representation of the case

as follows:<Case priority='CASE PRIORITY'>

<Title>Case title</Title><Description>Case description</Description><ProjectId>Project id</ProjectId><RecordId>Record id</RecordId><Assigned>UserID or Username of user for which the case should be assigned. Omit this node to create an unassigned case.</Assigned><ContactFirstName>The first name of the contact person</ContactFirstName><ContactLastName>The last name of the contact person</ContactLastName><ContactPhone>The phone number of the contact person</ContactPhone><ContactBusiness>The company name of the contact person</ContactBusiness><ContactEmail>The email address of the person, who can provide the detailed information about the case</ContactEmail><CustomProperties>

<Property name="PROPERTY_NAME">PROPERTY_VALUE</Property>

/CustomProperties></Case>

notifyOwner (bool) Defines whether to send notification to case owner (if user setting allows case emails.)

notifyUsers (List<string>) List of EFM users, can consist of UserID, email, or username. For example, [email protected]: With the EFM 15.1 FP3, the case description can contain up to 65K characters.

NOTE The id= attribute of the Assigned node will be ignored if present.






<Result><Case id="CASE_ID" status="success" /> - this element returns for cases where the case has been edited succesfully<Error>ERROR_TEXT</Error> - this element returns for cases where the case edit has failed to add

</result>



Method Call: EditCaseEx




Method Call: GetCases

Description: Get cases.


caseIds (int[]) An array of case IDs.



<Cases><Error>Invalid ID: 5</Error><Case id="ID" priority="1-7" status="CASE STATUS"created="UTC timestamp">

<ProjectId>Project id</ProjectId><RecordId>Record id</RecordId><Title>Case title</Title><Description>Case description</Description><Assigned id="UserID">User name</Assigned>

</Case></Cases>


NOTE The XML returned by GetCases for a single case can be passed to EditCase with or without modification.


Exceptions: Exceptions are thrown if there more than 500 casesrequested.




Method Call: SetCasePriority

Description: Set case priority.


caseIds (int[]) The array of case IDs for which the priority needs to be set

priority (int) Priority value 1-7 comment (string, optional)



<Result><Case id="CASE_ID"/> - this element returns for cases where priority has been set successfully<Error>ERROR_TEXT</Error> - this element returns for cases where priority has been failed to set

</Result>

Permissions: Edit Cases

Exceptions: None




Method Call: SetCasePriorityEx

Description: Set case priority with the notifyUsers option.


caseIds (int[]) The array of case IDs for which the priority needs to be set

priority (int) Priority value 1-7 comment (string, optional) notifyOwner (bool) Defines whether to send

notification to case owner (if user setting allows case emails.)

notifyUsers (List<string>) List of EFM users, can consist of UserID, email, or username. For example, [email protected].



<Result><Case id="CASE_ID"/> - this element returns for cases where priority has been set successfully<Error>ERROR_TEXT</Error> - this element returns for cases where priority has been failed to set

</Result>


Exceptions: None




Method Call: GetCaseDetail

Description: Get case details.


caseId (int) The case ID

Return Value & Description


<Case id="ID" priority="1-7" status="CASE STATUS"><Title>Case title</Title><Description>Case description</Description><ProjectId>Project id</ProjectId><RecordId>Record id</RecordId><Assigned id="UserID">User name</Assigned><ContactFirstName></ContactFirstName><ContactLastName></ContactLastName><ContactPhone></ContactPhone><ContactEmail></ContactEmail><ContactBusiness></ContactBusiness><CustomProperties>

<Property name="">Value</Property></CustomProperties><History>

<Event type="Event type" time="UTC timestamp">Comment</Event>

</History></Case>



Exceptions: Exceptions are thrown for invalid case ID




Method Call: SetCaseOwner

Description: Assign case owner.


caseIds (int[]) The array of case IDs for which the owner needs to be set

owner (int) The case UserID comment (string, optional)



<Result> <Case id="CASE_ID"/> - this element returns for cases where owner has been set successfully<Error">ERROR_TEXT</Error> - this element returns for cases where owner has failed to set

</Result>


Exceptions: None




Method Call: SetCaseOwnerEx

Description: Assign case owner with the notifyUsers option.


caseIds (int[]) The array of case IDs for which the owner needs to be set

owner (int) The case UserID comment (string, optional) notifyOwner (bool) Defines whether to send





<Result> <Case id="CASE_ID"/> - this element returns for cases where owner has been set successfully<Error">ERROR_TEXT</Error> - this element returns for cases where owner has failed to set

</Result>


Exceptions: None




Method Call: AddCaseComment

Description: Add comment to cases.


caseIds (int[]) The array of case IDs for which the comment needs to be added

comment (string)


XML NodeReturns:XML representation, as follows:

<Result><case id="CASE_ID" status="success" /> - this element returns for cases where comment has been added successfully<error id="CASE_ID">ERROR_TEXT</error> - this element returns for cases where comment has been failed to add

</Result>


Exceptions: Exceptions are thrown for invalid case IDs




Method Call: AddCaseCommentEx

Description: Add comment to cases with the notifyUsers option.


caseIds (int[]) The array of case IDs for which the comment needs to be added.

comment (string) notifyOwner (bool) Defines whether to send





<Result><case id="CASE_ID" status="success" /> - this element returns for cases where comment has been added successfully<error id="CASE_ID">ERROR_TEXT</error> - this element returns for cases where comment has been failed to add

</Result>


Exceptions: Exceptions are thrown for invalid case IDs




Method Call: SetCaseStatus

Description: Set case status.


caseIds (int[]) The array of case IDs for which the status needs to be set

status (int) Values are as follows:Open = 0Closed = 1OnHold = 2

comment (string, optional) duplicateCaseId (int, optional) Case id that

these cases being updated are a duplicate of



<Result><Case id="CASE_ID"/> - this element returns for cases where status has been set succesfully<Error>ERROR_TEXT</Error> - this element returns for cases where status has been failed to set

</Result>


Exceptions: None




Method Call: SetCaseStatusEx

Description: Set case status with the notifyUsers option.


caseIds (int[]) The array of case IDs for which the status needs to be set

status (int) Values are as follows:Open = 0Closed = 1OnHold = 2

comment (string, optional) duplicateCaseId (int, optional) Case id that

these cases being updated are a duplicate of notifyOwner (bool) Defines whether to send





<Result><Case id="CASE_ID"/> - this element returns for cases where status has been set succesfully<Error>ERROR_TEXT</Error> - this element returns for cases where status has been failed to set

</Result>


Exceptions: None




Method Call: DeleteCases

Description: Delete cases.


caseIds (int[]) The array of case IDs which need to be deleted.



<Result><Case id="CASE_ID"/> - this element returns for cases where status has been set successfully<Error id="CASE_ID">ERROR_TEXT</error> - this element returns for cases which deletion has been failed

</Result>

Permissions: Delete Cases


Chapter 4 - Web Services Data Web Service admin.asmx



Web Service admin.asmxWeb Service for user and workgroup management.


All methods require the logged-in user to be mapped to a workgroup, except the following: ResetUserPassword, ChangeUserPassword, GetWorkgroupList, GetWorkgroupUsers, AddUserToWorkgroup, DeleteUserFromWorkgroup, GetWorkgroupRoleList, GetWorkgroupRole, SetWorkgroupRole, SetUserWorkgroup, DeleteUser, GetUserData, GetUserInformation, and SetUserInformation.

Add/Change/Remove Users

Method Call: AddUser

Description: Adds a new user to the system.A subsequent AddUserToWorkgroup call should bemade with the returned userid to assign the user toa workgroup.

CAUTION You cannot add a user with the same user name or email as that of an existing user.


username (string) User name; max 255 characters

displayname (string) Display name; max 255 characters

email (string) User's email address; max 255 characters


intReturns: The userid for the added user

Permissions: Create Users

Exceptions: None

Chapter 4 - Web Services Data Add/Change/Remove Users



Method Call: DeleteUser

Description: Deletes the user with the given userid. Only System Administrators may delete users from the system. This is a soft delete: the user will not be removed from the database, but is marked inactive.Users are stored at the system level and can be assigned to multiple workgroups. Workgroup Administrators can remove a user from their workgroup but they can't delete a user since the user may belong to another workgroup. Thus only the System Administrator can delete users.


Userid (int) The User's ID


N/A

Permissions: System Administrator Account

Exceptions: None




Method Call: GetUserData

Description: Shows information about all users of the given status.


status (int)0 = active 1 = suspended2 = deleted


DataSetReturns: A DataSet (serialized data table in a System.Data.DataSet): http://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx. See an example of the data table below.

Column Data Type

Description/Comments

USERID Int32 internal unique identifier

USERNAME String Username used to authenticate into EFM

PASSWORD String Hashed - Password

EMAIL String Email address

DISPLAYNAME String First and last name

CURR_GROUP Int32 Current EFM workgroup ID

CULTURE String Culture (http://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx)

UTC_OFFSET Double

Offset in hours from Greenwich Mean Time zone. A null value should be interpreted as 0.

AD_GUID String Active Directory GUID. Only used when integrating with Active Directory for Single Sign On.







LICENSE String Reserved*

STATUS Int32 User status - Reserved

DEPTID Int32 Reserved*

SETTINGS String Reserved*

LAST_SELECTION

Int32 Reserved*

USER_INFO String Reserved*

CREATED Int64 UTC timestamp in Microsoft DateTime.Ticks when user was created in EFM.

MODIFIED Int64 Reserved - UTC timestamp in Microsoft DateTime.Ticks when user was last modified.

MODIFIER Int32 Reserved - EFM userid that last modified this user record.

PASS_REQ_ID Int64 Reserved*

*This value is currently not in use and Verint reserves the right to remove or modify this value in the future.

Permissions: View Users

Exceptions: None

Method Call: GetUserData




Method Call: GetUserInformation

Description: Returns information about a user.


userid (int) The user's ID



<User id="USERID" group="CURRENT GROUP ID" culture="CULTURE" status="Deleted|Suspended|Active" reviewerStatus = "Standard|Reviewer|Supervised"><Name>USER NAME</Name><Display>DISPLAY NAME</Display><Email>EMAIL</Email><ExternalDataSources>

<DataSource key="DataSource" id="DataSourceId" ></DataSource>

</ExternalDataSources><ExtendedInformation>

<Organization>Organization Name</Organization><Department>Department Name</Department><Country>Country</Country><Province>Province</Province><Fax>1233456789</Fax><EmployeeCount>3000</EmployeeCount><RegistrationDate>2013-07-29T12:26:00.5555555</RegistrationDate><Industry>IT</Industry><JobTitle>Manager</JobTitle><State>State</State><Telephone>1234567890</Telephone><Interests>None</Interests><RegistrationPortal>RegistrationPortal Name</RegistrationPortal><ReferredBy>Referrer</ReferredBy>

</ExtendedInformation><OrganizationMembership name="organization name">

<OrganizationData key="organization key" id="organization id"/>

</OrganizationMembership>





<OrganizationAccess name="organization name">


</OrganizationAccess></User>

Culture definitions: http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx


Exceptions: None

Method Call: GetUserInformation




Method Call: SetUserInformation

Description: Set basic information about a user (username, display name, email, culture, reviewer status), extended information (organization, department, country, province, fax, employee count, registration date, industry, job title, state, telephone, interests, registration portal, referred by), workgroup (organization membership, organization access), and external ID.

NOTE You can't change the user name to that of an existing user, nor the email to that of an active existing user.


userid (int) The user's ID xmlString (string) An XML representation in the

same format as returned by GetUserInformation. Omit any nodes you are not changing.


N/A

Permissions: Edit Users

Exceptions: None




Method Call: ResetUserPassword

Description: Reset the user's password. This sends the new password to the user's email.


userid (int) The user's ID


N/A


Exceptions: None




Method Call: ChangeUserPassword

Description: Change the user's password.


userid (int) The user's ID newPassword (string) The new password

(plaintext)


N/A


Exceptions: None




Method Call: GetUserInfoByEmail

Description: Get a user's information by using an email address


emailAddress (string) User's email address



















Exceptions: None

Method Call: GetUserInfoByEmail




Method Call: GetUserInfoByExternalId

Description: Return information about a user with specified external data source key/id pair as an XML string.


userDataSourceKey (string) External data source key (can be blank)

userDataSourceId (string) External data source ID




<DataSource key="DataSource"id="DataSourceId"></DataSource>


<Organization>Organization Name</Organization><Department>Department Name</Department><Country>Country</Country><Province>Province</Province><Fax>1233456789</Fax><EmployeeCount>3000</EmployeeCount><RegistrationDate>2013-07- 29T12:26:00.5555555</RegistrationDate><Industry>IT</Industry><JobTitle>Manager</JobTitle><State>State</State><Telephone>1234567890</Telephone><Interests>None</Interests><RegistrationPortal>RegistrationPortal Name</RegistrationPortal><ReferredBy>Referrer</ReferredBy>













Exceptions: None

Method Call: GetUserInfoByExternalId

http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx




Method Call: SetUserInfoByExternalId

Description: Set basic information about a user (username, display name, email, culture, reviewer status), extended information (organization, department, country, province, fax, employee count, registration date, industry, job title, state, telephone, interests, registration portal, referred by), workgroup (organization membership, organization access), and external ID.

NOTE You cannot change the user name to that of an existing user, nor the email to that of an active existing user.

Parameters:(name, type, description):

userDataSourceKey (string) External data source key (can be blank)

userDataSourceId (string) External data source ID

xmlString (string) An XML representation in the same format as returned by GetUserInformation. Omit any nodes you are not changing.


N/A


Exceptions: SOAP exceptions for the authorized user that does not belong to a workgroup.




Method Call: GetUserInfoByUsername

Description: Get a user's information by username


username (string) The user's username



















Exceptions: None

Method Call: GetUserInfoByUsername




Method Call: GetOrganizationHierarchy

Description: Extract current Organization Hierarchy for aspecified Workgroup in XML representation.


groupId (int) The workgroup ID



<Organizations workgroup="Group Name"><Organization name="OrganizationName" parent="">

<ExternalDataSources/></Organization>

<Organization name="OrganizationName" parent="Parent OrganizationName">

<ExternalDataSources><DataSource key="Source Name"id="SourceValue"><DataSource>

</ExternalDataSources></Organization>

</Organizations>


Exceptions: None




Method Call: ImportOrganizationHierarchy

Description: Import Organization Hierarchy in XML representation.


isNewStructure (bool) If true, import new organization hierarchy; if false, update existing organization hierarchy

importHierarchyXML (string) XML representation of organization hierarchy in the same format as returned by GetOrganizationHierarchy



<Organizations workgroup="Group Name"><Organization name="OrganizationName" parent="">

<ExternalDataSources/></Organization><Organization name="OrganizationName" parent="Parent OrganizationName">

<ExternalDataSources><DataSource key="Source Name"id="Source Value"></DataSource>

</ExternalDataSources></Organization>

</Organizations>

Permissions: Import Users

Exceptions: Workgroup in XML is empty.Broken file structure.No group found.

Chapter 4 - Web Services Data Workgroup Access



Workgroup Access

Method Call: GetWorkgroupList

Description: Get a list of workgroups accessible to the API user.


None



<Workgroups><Workgroup id="GROUP ID">

<Name>GROUP NAME</Name><Description>DESCRIPTION</Description>

</Workgroup></Workgroups>


Exceptions: None




Method Call: GetWorkgroupUsers

Description: Get a list of users in a workgroup.


groupId (int) The workgroup ID


intReturns: An array of integer userids


Exceptions: None




Method Call: GetWorkgroupUnsubscribes

Description: Get the list of unsubscribed email addresses in a workgroup.


pageSize (int) Return this number of records up to a max of 10,000.

pageIndex (int) Return page with a page number greater than this. Use 0 for the first page.

startTime (dateTime) Optional filter to query for all emails where the unsubscribe date is greater than the one specified.

searchString (string) Optional search string. If specified, it will return emails that contain the string. If not specified, all email addresses are returned.


Returns an XML representation, as follows:<Unsubscribes total="74656">

<Unsubscribe date="1/12/2012 05:34:12" panelist="true">[email protected]</Unsubscribe><Unsubscribe date="3/12/2014 13:43:22" panelist="false">[email protected]</Unsubscribe>

<Unsubscribes>

Permissions: View Unsubscribes

Exceptions: None




Method Call: AddUserToWorkgroup

Description: Add a user to a Workgroup. No operation is performed if the user already belongs to the Workgroup. The user's current Workgroup, if blank, will be set to that Workgroup; if it's not blank it will be left alone.


groupId (int) The Workgroup ID userid (int) The user's ID


N/A


Exceptions: None




Method Call: DeleteUserFromWorkgroup

Description: Removes a user from a Workgroup. No operation is performed if the user doesn't belong to the Workgroup. If the user is removed from their current Workgroup, they will not be able to login.Use AddUserToWorkgroup to add them to a different Workgroup, or SetUserWorkgroup to set their current Workgroup to one they already belong to.




N/A


Exceptions: None




Method Call: GetWorkgroupRoleList

Description: Get a list of the Security Roles in this Workgroup


groupId (int) The Workgroup ID



<Roles> <Role id="ROLE ID">ROLE NAME</Role>

</Roles>


Exceptions: None




Method Call: GetWorkgroupRole

Description: Get the ID of the Security Role this user has in this group.




intReturns: The role ID; call GetWorkgroupRoleList for a list of roles.


Exceptions: None




Method Call: SetWorkgroupRole

Description: Set the role of this user in this Workgroup to the given role.


groupId (int) The Workgroup ID userid (int) The user's ID roleId (int) The ID of the role to assign


N/A


Exceptions: None




Method Call: SetUserWorkgroup

Description: Change a user's current Workgroup. This is the Workgroup they'll start out with next time they login; this includes Web Service logins.


userId (int) The user's ID groupID (int) The Workgroup ID


N/A


Exceptions: None

Chapter 4 - Web Services Data Web Service reportdata.asmx



Web Service reportdata.asmxThis Web Service exposes memorized reports.


Memorized Reports

Method Call: GetMemorizedReports

Description: Get the memorized reports for a given project.




XMLNodeReturns: An XML structure describing the reports, as follows. The report ID is needed for the remaining calls.

<Reports><Report id="ID" creatorid="USER" created="DATE">

<Name>REPORT NAME</Name><Description>REPORT DESCRIPTION</Description>

</Report></Reports>

Permissions: View Reports and View Project

Exceptions: None

Chapter 4 - Web Services Data Memorized Reports



Method Call: DeleteMemorizedReport

Description: Delete the given memorized report.


projectId (int) A project ID reportId (int) The report ID; see

GetMemorizedReports


N/A

Permissions: Delete Reports

Exceptions: None




Method Call: CloneReport

Description: Create a new memorized report for a given project from an existing report.


projectId (int) A project ID copiedReportId (int) The reportId of an existing

report to copy reportName (string) A name to identify the

cloned report reportDescription (string) An optional

description of the report


intReturns: The new report ID

Permissions: Create Reports

Exceptions: None




Method Call: CreateSharedReport

Description: Create a new memorized report for a given project from an existing report. Equivalent to calling CloneReport, then SetMemorizedReportSharing, then SetMemorizedReportFilter.


projectId (int) A project ID copiedReportId (int) The reportId of an existing

report to copy reportName (string) A name to identify the

cloned report reportDescription (string) An optional

description of the report usersXml (string) The XML giving a list of users

to share this report with; can be null. Same format as returned by GetMemorizedReportSharing

filterXml (string) XML specifying a set of Criterion objects used to filter the data. See GetMemorizedReportFilter for the format.



intReturns: The report ID of the new report.

Permissions: Create Reports

Exceptions: None




Method Call: GetMemorizedReportSharing

Description: Returns a list of users authorized to view the specified report.



GetMemorizedReports


XMLNodeReturns: An XML representation of the shared users, as follows:

<Report><Userid="ID" />

</Report>

Permissions: View Reports

Exceptions: None




Method Call: SetMemorizedReportSharing

Description: Change the list of users who are authorized to view this report. A report can be viewed by users who have view access to the portfolio without explicitly giving them sharing access. Explicit access is intended for users who are restricted to viewing reports but not portfolios. To eliminate all shared access, provide no User nodes, or pass null for usersXml.



GetMemorizedReports usersXml (string) A XML list of users, in the

same format as returned by GetMemorizedReportSharing.


N/A

Permissions: Edit Reports

Exceptions: None




Method Call: GetMemorizedReportFilter

Description: Returns an XML representation of the filter for a memorized report. The format (shown below) is the same as used for GetSurveyDataEx. The same filter will appear as part of the report XML returned by GetMemorizedReports. If there is no filter, it will return a blank CriteriaCollection.



GetMemorizedReports


XMLNodeReturns: An XML representation of the filter for this report.

<CriteriaCollection><Criterion leftparen="NUMBER OF LEFT PARENS"heading="DATABASE COLUMN" expression="OPERATOR"value="COMPARED VALUE"rightparen="NUMBER OF RIGHT PARENS" rule="AND|OR"/>


Operator is one of = != < > <= >=

Permissions: View Reports and View Project

Exceptions: None




Method Call: SetMemorizedReportFilter

Description: Change the filter for a memorized report. The format is the same as returned by GetMemorizedReportFilter.



GetMemorizedReports filterXml (string) XML specifying a set of

Criterion objects used to filter the data.



N/A

Permissions: Edit Reports and View Project

Exceptions: None

Chapter 4 - Web Services Data Report Users



Report Users

Method Call: GetReportingUsers

Description: Get a list of users authorized to view reports. The users passed to SetMemorizedReportSharing must come from the list.


None


XMLNodeReturns: An XML representation of the authorized users, as follows:

<Users><Userid="ID">

<username>USERNAME</username><displayname>DISPLAY NAME</displayname>

</User></Users>


Exceptions: None

C h a p t e r 5

Survey Event Handler

Topics Survey Event Handler Overview, page 206

Use Examples, page 207

Requirements, page 208

Using the Visual Studio website provided, page 209

Creating a New Web Service (Classic) or HTTP Handler (Modern), page 212

Creating a Web Method for Use with Classic Survey Engine, page 214

Creating an HTTP Handler for use with Modern Survey Engine, page 216

Using the WSDL file, page 217

Web Service Event Handler Properties for the Modern Survey Engine, page 218

Survey Event Handler Configuration, page 227

Survey Event Descriptions, page 237

Sample Survey Event Handler, page 239

Chapter 5 - Survey Event Handler Survey Event Handler Overview



Survey Event Handler OverviewThe Survey Event Handler1 provides the ability for the survey engine to call a Web Service2 based on events in a survey. This Web Service is called using information about the current state of the survey and can return information to affect the behavior of the survey or the data stored with the survey. The returned information can be used to stop the survey from going to the next page, redirect the respondent to a custom URL or modify the values stored in the database.

1 Survey Event Handler - This is a Web Service that is hosted on a customer's server that the EFM surveyengine calls out to. The Web Service can be hosted anywhere but it has a single predefined and calling pa-rameters. It is passed to the current state of the survey and can be used to record information about the surveyin real time or modify the operation of the survey as the participant is in the process of taking the survey.The survey event handler can turn around and call back to EFM Web Services for additional information.2 The W3C defines a Web Service as a software system designed to support interoperable machine-to-ma-chine interaction over a network. Web Services are frequently just Web APIs that can be accessed over anetwork, such as the Internet, and executed on a remote system hosting the requested services. Web Servicedefinition can be found on the following Wikipedia website: https://en.wikipedia.org/wiki/Web_service.

IMPORTANT In Classic survey rendering mode, Web Service Event Handler call outs are made as SOAP calls; in Modern survey rendering mode, Web Service Event Handler call outs are made as REST calls (in JSON or XML format.)

https://en.wikipedia.org/wiki/Web_service

https://en.wikipedia.org/wiki/Web_service

Chapter 5 - Survey Event Handler Use Examples



Use Examples A receipt code survey where custom business logic validates what the respondent

enters

Recording survey responses simultaneously to alternative data stores within your company

Changing the rendering of the survey for specific participants

Custom validation

Piping in custom data for the participant from an alternative data store (such as a CRM system)

You can configure what "event" triggers the survey engine will call out to the Web Service (like survey start or end) or the amount of response data sent in the call. In addition, for a SOAP-based Web Service, you can also specify a custom token which ensures that the Web service is called only from your survey.

Chapter 5 - Survey Event Handler Requirements



Requirements1 EFM API License.

2 Host the Web Service.

The following example provides you details of creating a Web Service in Visual Studio using ASP.Net technology. However, any language that supports SOAP Web Services or REST Web Services (in the case of Modern rendering surveys) can be used.

We have provided an ASP.NET website application written in C# that defines the Web Method and the structures passed back and forth from the survey engine. In addition, for a SOAP-based Web Service, a Web Services Description Language (WSDL) file is supplied that defines those structures.

Chapter 5 - Survey Event Handler Using the Visual Studio website provided



Using the Visual Studio website providedYou can use the Visual Studio website that is provided as a basis for developing your own website or you can use it as an example for creating a website.

Steps1 Open the contents of the .zip file in Visual Studio as a C# file-based website.

Visual Studio Interface - Survey Engine Services

Chapter 5 - Survey Event Handler Steps



2 For both Classic and Modern surveys, the class SurveyEventService contains the definition of the Web Method or HTTP handler called from the respective survey engine.

SurveyEventService.ashx for Modern survey:public class SurveyEventService : BaseHttpHandle{

public override void ProcessRequest (HttpContext context{// This can be checked in your code to ensure that the web service is only// called from the EFM survey engine. The token is specified in the UI on// the same dialog as where you specify the URL of your web service.var authenticationHeader = Context.Request.Headers["AuthenticationHeader"];var wsRequest = GetRequest(context);var wsResponse = new WebServiceResponse();SendResponse(context, wsResponse);}

public override bool IsReusable{

get { return false; }}

}

SurveyEventService.asmx for Classic survey:/// <summary>/// This file defines the Web method that is called by the survey engine./// </summary>[WebService(space = "http://www.vovici.com/v5/surveyevent")][WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]public class SurveyEventService : WebService{

/// <summary>/// Implement this field if you want to pass in a unique token to your Web /// Service. This can be checked in your code to ensure that the Web Service is /// only called from the EFM survey engine. The token is specified in/// the UI on the same dialog as where you specify the URL of your Web/// service./// </summary>public AuthenticationHeader AuthenticationHeader;

/// <summary>/// This is the Web method called by the survey engine. It must be d /// WebSurveyEventHandler./// </summary>/// <param ="eventArgs">SurveyEventArgs that describe the current /// survey action.</param>/// <returns>WebServiceResponse that will be used to affect survey /// operation.</returns>[SoapHeader("AuthenticationHeader", Direction = SoapHeaderDirection.In)][WebMethod]

Chapter 5 - Survey Event Handler Steps



public WebServiceResponse WebSurveyEventHandler(SurveyEventArgs eventArgs) {

WebServiceResponse response = new WebServiceResponse();return response;

}}

CAUTION To avoid issues at runtime, the parameter "eventArgs" must be entered exactly as shown here. In addition, it is case-sensitive, so do not deviate from this format including change in capitalization or change in naming (for example, eventarguments).

Chapter 5 - Survey Event Handler Creating a New Web Service (Classic) or HTTP Handler (Modern)



Creating a New Web Service (Classic) or HTTP Handler (Modern)

You can create a new Web Service for the Classic Survey Engine or an HTTP Handler for the Modern Survey Engine that can be called by the Survey Engine at runtime. To create a new Web Service file:

1 Go to the Add New Item dialog box.

2 For use with the Classic Survey Engine, click the "Web Service" template; for use with the Modern Survey Engine, click the “Generic Handler” template.

3 Enter a in the ":" text field.

NOTE Go to File>New>File to get to Add New Item.

Chapter 5 - Survey Event Handler Creating a New Web Service (Classic) or HTTP Handler (Modern)



4 Select the Language (for this example, it is Visual C# - see image below).

5 Click "Add."

Add New Item dialog

NOTE When choosing “Web Service”, a new .asmx file is added to the project; when choosing “Generic Handler”, a new .ashx file is added to the project.

Chapter 5 - Survey Event Handler Creating a Web Method for Use with Classic Survey Engine



Creating a Web Method for Use with Classic Survey Engine

1 In the Web service file, you must create a Web Method with the following signature and return values:

/// <summary>/// This is the Web method that is called from the survey engine at runtime./// It must exactly match this signature./// </summary>[WebMethod]public WebServiceResponse WebSurveyEventHandler(SurveyEventArgs eventArgs) {

WebServiceResponse response = new WebServiceResponse();return response;

}

NOTE This assumes that you know how to create the method with the sample code. You can type information into the code editor or you can copy and paste in the sample code below.

CAUTION The parameter "eventArgs" must be entered exactly as shown here. In addition, it is case-sensitive, so do not deviate from this format including change in capitalization or change in capitalization or change in naming (e.g., eventarguments).

Chapter 5 - Survey Event Handler Creating a Web Method for Use with Classic Survey Engine



2 At this point the Solution Explorer will look like this:

Solution Explorer window for Classic Survey Engine

Chapter 5 - Survey Event Handler Creating an HTTP Handler for use with Modern Survey Engine



Creating an HTTP Handler for use with Modern Survey Engine

1 In the Generic Handler file, create an HTTP Handler with the following signature and return values:

public class ExampleModernSurveyEventHandler : BaseHttpHandler{

public void ProcessRequest(HttpContext context){

var wsRequest = GetRequest(context);var wsResponse = new WebServiceResponse();SendResponse(context, wsResponse);

}

public bool IsReusable{

get {return false;}}

}You will also want to add in the following using statement:“using Verint.SurveyEngineServices;”

2 At this point, the Solution Explorer will contain the ExampleModernSurveyEventHandler.ashx file.

NOTE This assumes that you know how to create the method with the sample code. You can type information into the code editor or you can copy and paste in the sample code.

Chapter 5 - Survey Event Handler Using the WSDL file



Using the WSDL fileYou can also use the WSDL3 file that is provided to generate class structures for the values passed back and forth in the Web Method call.

The Web Method must have the following signature:/// <summary>/// This is the Web method that is called from the survey engine at runtime./// It must exactly match this signature./// </summary>[WebMethod]public WebServiceResponse WebSurveyEventHandler(SurveyEventArgs eventArgs)

3 WSDL is an XML format for describing network services as a set of endpoints operating on messagescontaining either document-oriented or procedure-oriented information. The operations and messagesare described abstractly, and then bound to a concrete network protocol and message format to definean endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is ex-tensible to allow description of endpoints and their messages regardless of what message formats or net-work protocols are used to communicate. Reference: http://www.w3.org/TR/wsdl

IMPORTANT For a Modern Survey Event Handler, the WSDL file is not provided, as it is REST based.

CAUTION The parameter "eventArgs" must be entered exactly as shown here. In addition, it is case-sensitive, so do not deviate from this format including change in capitalization or change in naming (for example, eventarguments).

Chapter 5 - Survey Event Handler Web Service Event Handler Properties for the Modern Survey Engine



Web Service Event Handler Properties for the Modern Survey Engine

WebServiceRequest

Parameter Description

GroupID Gets the ID of the workgroup that the survey is associated with.

ProjectID Gets the ID of the project that the survey is associated with.

RecordID Gets the database record ID that is associated with the survey respondent.For open participation surveys, this is first available from the PreResponse event on the first page and not earlier (for example, any event on SurveyStart or PreSave on the first page). This is because the actual db record is not created until the Save event on the first page occurs.

PanelistID* Gets the panelist ID that is associated with the survey respondent.

UserKey1* Gets the value of User Key 1 for the survey respondent.



Culture Gets the ISO Culture Code for the survey respondent.

Started Gets the DateTime the respondent started the survey.All DateTimes are stored in XML/JSON in Coordinated Universal Time (UTC) format.For example, 2015-06-15T13:05:03.39Z

OverQuota Gets DateTime the respondent was branched out of the survey.

BranchedOut Gets DateTime the respondent completed the survey.

Chapter 5 - Survey Event Handler WebServiceRequest



Completed Gets DateTime the Respondent completed the survey.

EventType Gets the type of the event that the Web Service is firing for.Options are the following: Test – Test button from the Web Service Event

Handler dialog box. PreSave – Called before data is saved to the

database. Allows the Web Service to stop or change data from being saved to the response table.

PreResponse – Called before the page is rendered back to the respondent. Allows the Web Service to return a table of replacement fields that the survey engine will expand and replace on the page that is to be displayed to the respondent.

Command Gets the survey action for the survey respondent (for example, Next, Back, Submit, and so on.)Options are the following:Survey Start Event Start – Survey StartedPage Submit Event Next – the Next button is clicked.Survey End Event Submit – the Submit button is clicked. Save – the Save button is clicked. Branched Out – Respondent was branched out

due to branch settings. Quota Reached – Quota was reached due to

quota settings. Closed – Survey is closed or passed access

revoked date. Invalid Access – Respondent URL or Passcode

values are invalid. Completed Response – Respondent tried to

resume a survey that was set not to allow updates.

View Results – the View Results button is clicked (DNN/FB).


Chapter 5 - Survey Event Handler WebServiceRequest



CurrentPageID Gets the ID of the current page displayed for the survey respondent.

NextPageID Gets the ID of the next page to be displayed for the survey respondent.Zero for a non-content page (for example, Submit, Branched Out, Over Quota, etc.)

RequestURL Gets a fully qualified URL that was used to request the survey.

ResumeURL Gets a fully qualified URL to be used to resume the survey for the respondent.

SurveyType Gets the Survey TypeOptions are the following: OpenParticipation – Open Participation Panel – Send to Panelists EmailList – Send to an Email List AccessList – Require a Passcode SMSList – SMS Survey

PublishStatus Gets the Publish StatusOptions are the following: Testing Open Closed

Fields* Gets the Requested Response Data.Options are the following: Only Preload Data None (fast) Only the responses submitted for the page All non-empty responses for the survey (slow)In all cases, only “Answered” fields will be included. Blank or Not Asked Verbatim responses and Asked Choice Questions will not be included.For more information on the Field parameter, see “Field” on page 226

TIP * These properties will not be included in the JSON or XML response if they are not applicable to the survey or selected options.


Chapter 5 - Survey Event Handler JSON Example



JSON Example{

"GroupId":1321926139,"ProjectId":1774839387,"RecordId":635636002253414068,"PanelistId":450265956,"UserKey1":"A","UserKey2":"B","UserKey3":"C","Culture":"en-US","Started":"2015-06-15T13:19:35.6739129Z","EventType":"PreResponse","Command":"Next","CurrentPageId":1,"NextPageId":2,"RequestUrl":"http://localhost/EFM/se/4ECAFDFB69C9E65B","ResumeUrl":"http://localhost/EFM/se/4ECAFDFB69C9E65B08D23B9388C39EB47B","SurveyType":"OpenParticipation","PublishStatus":"Testing","Fields":[{

"":"Q1","Value":"1","Type":"SmallInt"

},{"":"Q2_1","Value":"1","Type":"TinyInt"



},{"":"Q3_1","Value":"FITB","Type":"Text"

},{"":"Q3_2","Value":"123","Type":"Int"

},{"":"Q3_3","Value":"123.456","Type":"Float"

},{"":"Q3_4","Value":"624598560000000000","Type":"BigInt"

Chapter 5 - Survey Event Handler XML Example



},{"":"Q4","Value":"Essay","Type":"Memo"

}],

}

XML Example<?xml version="1.0" encoding="utf-16"?><WebServiceRequest>

<GroupId>1321926139</GroupId><ProjectId>1774839387</ProjectId><RecordId>635636003942117525</RecordId><PanelistId>450265956</PanelistId><UserKey1>A</UserKey1><UserKey2>B</UserKey2><UserKey3>C</UserKey3><Culture>en-US</Culture><Started>2015-06-15T13:19:35.67Z</Started><EventType>PreSave</EventType><Command>Next</Command><CurrentPageId>1</CurrentPageId><NextPageId>2</NextPageId><RequestUrl>http://localhost/EFM/se/4ECAFDFB69C9E65B</RequestUrl><ResumeUrl>http://localhost/EFM/se/4ECAFDFB69C9E65B08D23B93ED6B30957B</ResumeUrl><SurveyType>OpenParticipation</SurveyType><PublishStatus>Testing</PublishStatus><Fields>

<Field ="Q1" type="SmallInt">1</Field><Field ="Q2_1" type="TinyInt">1</Field><Field ="Q2_2" type="TinyInt">0</Field><Field ="Q2_3" type="TinyInt">1</Field><Field ="Q3_1" type="Text">FITB</Field><Field ="Q3_2" type="Int">123</Field><Field ="Q3_3" type="Float">123.456</Field><Field ="Q3_4" type="BigInt">624598560000000000</Field><Field ="Q4" type="Memo">Essay</Field>

</Fields></WebServiceRequest>

Chapter 5 - Survey Event Handler WebServiceResponse



WebServiceResponse


Culture Sets the ISO Culture Code for the survey respondent.

RedirectURL Sets a URL to redirect to.

NOTE To set Campaign Status as appropriate, use Command.For example, Completed (Submit), Branched Out (BranchedOut) or Quota Reached (QuotaReached).

Command Sets the survey action for the survey respondent.Options are the following: ValidationFailed – Show the current page; use

with the ReplacementTable to show custom validation errors.

Submit – End the survey; the respondent is marked as Completed and the Survey Completed page is shown.

Jump to - Shows page or Custom End page with specified ID.

Save – End the survey; the respondent stays at current status (for example, Started) and the Survey Save page is shown.

BranchedOut – End the survey; the respondent is marked as Branched Out and the Branched Out page is shown.

QuotaReached – End the survey; the Respondent is marked as Over Quota and the Quota Reached page is shown

Fields Sets the specified Response Data to update.Only valid for PreSave event.Changes to values will affect quotes and triggers but not question validation.Values are not validated to ensure in proper range.For more information on the Field parameter, see “Field” on page 226

Chapter 5 - Survey Event Handler WebServiceResponse



JSON or XML response should be returned in Response Body. The Content Type should be set as appropriate:

application/json; charset=utf-8

or

application/xml; charset=utf-8

HideElements Hides the specified element IDs.Can be added from both the PreSave and PreResponse Events. Is reset after the next survey engine request.If the element for the specified ID exists on the page, it is not visible to the respondent.No HTML is generated, including hidden fields.

Replacements Dictionary of Replacements to perform to returned page.Replacements are only performed on the survey content (for example, question, topic, choice, labels, etc), not dynamically generated HTML elements.Keys are case-sensitive. Values will be replaced as is to support inserting of HTML tags. Text must be HTML-encoded as appropriate.

JumpPageId Sets the ID of the page to jump to if Command is Jump to.

JumpEndPageId Sets the Id of the custom end page to jump to if Command is JumpTo.

NOTE All properties are optional and should be excluded to use the current settings.

TIP * These properties will not be included in the JSON or XML response if they are not applicable to the survey or selected options.


Chapter 5 - Survey Event Handler JSON Example



JSON Example{

"Culture":"es-ES","RedirectUrl":"http://www.example.com","Command":"ValidationFailed","Fields":[{

"":"Q1","Value":"1","Type":"SmallInt"


}]}"HideElements": [

"Q1","Q7"

]}

"ReplacementTable": {"[[error]]":"<div style=\"color:red\">Field cannot be blank</div>"

}}

XML Example

<?xml version="1.0" encoding="utf16"?><WebServiceResponse>

<Culture>es-ES</Culture><RedirectUrl>http://www.example.com</RedirectUrl><Command>ValidationFailed</Command><Replacements>

<Replacement key="[[error]]"><div style="color:red">Field cannot be blank</div></Replacement>

</Replacements><Fields>

<Field ="Q1" type="SmallInt">1</Field><Field ="Q2_1" type="TinyInt">1</Field>

</Fields><HideElements>

<HideElement>Q1</HideElement><HideElement>Q7</HideElement>

</HideElements></WebServiceResponse>

Chapter 5 - Survey Event Handler Field



Field


of Data Point as stored in response table.

Value Field Value.For WebServiceRequest, Numeric Values are returned in the English (US) format.For WebServiceResponse , Numeric Values should also be specified in the English (US) format to be parsed correctly by Survey Engine.

Type Data Type.Options are the following: TinyInt – Used for the Choose Many questions.

No Value – Not asked0 – Not checked1 – Checked

SmallInt – Used for the Choose One questions.No Value – Not asked0 – Not answered-1, -2, -3 Coded Values1 – N Choice Value

Int – Used for the Fill in the Blank (Whole Number) questions (-2,147,483,648 to 2,147,483,647).

BigInt – Used for the Fill in the Blank (Date) questions (Stored as UTC Ticks (Midnight)).

Float – Used for the Fill in the Blank (Real Number) questions (+/- 5.0x10-324 to +/- 1.7x10308).

Text – Used for the Fill in the Blank (Text) questions (Max length 255).

Memo – Used for the Essay questions (Unlimited length).

Chapter 5 - Survey Event Handler Survey Event Handler Configuration



Survey Event Handler ConfigurationThe Web Service Survey Event Handler enables you to use your own Web service to handle survey events.

NavigationSelect your survey from the My Surveys page. On the Design page, click Advanced from the side panel, and then select Web Services Event Handler from the options.

My Surveys page

NOTE You must purchase the Web Services API product to use the Web Service Survey Event Handler. If you already have the API product, you will have access to this feature. As mentioned in the Introduction Requirements - you must host the Web Service yourself.

Chapter 5 - Survey Event Handler Navigation



Web Services Event Handler

Chapter 5 - Survey Event Handler Use



Web Service dialog box

UseThis advanced functionality is used if you want your own Web Service to handle some of the Events in the Survey process to include Survey Start, Page Submit, and Survey End.

Setting Up the Survey Event Handler in EFM (V15.1)1 Open the EFM V15.1 Application.

2 On the My Surveys page, select a survey.

3 Select Advanced from the side panel and click "Web Services Event Handler" from the Options pane.

Chapter 5 - Survey Event Handler Setting Up the Survey Event Handler in EFM (V15.1)



Web Service dialog boxThis functionality allows you to specify where your Web service is located. In addition, you can configure which events trigger the survey engine to call the Web Method and the amount of response data included.

Chapter 5 - Survey Event Handler Enter URL of External Web Service



Enter URL of External Web ServiceTo use the Web Service Event Handler, you are required to provide the URL of an external Web Service. The image has an example, but you need to provide your Web Service URL.

Web Service URL

Chapter 5 - Survey Event Handler Format



FormatYou can select the format of the request/response data to be used by the Web Service: JSON or XML.

Format fieldNOTE This option is available only for surveys in Modern rendering mode.

For more information about survey rendering modes, see http://efmhelp.net/robohelp/robohelp/server/EFMHelp15.1FP3/projects/EFMHelp/Survey_rendering_overview.htm.

Chapter 5 - Survey Event Handler Authentication Token



Authentication TokenThe Web Service Event Handler also enables you to add an Authentication Token. By using this feature, you can pass a custom value to your web service to ensure that it is only called from the EFM survey engine. See the following image for the location of the Authentication Token.

Authentication Token field

If specified, the Authentication Token is included as a Request Header named "AuthenticationHeader."

.NET Examplespace WebApplication1{

/// <summary>/// Summary description for Handler1/// </summary>public class WsEventHandler : IHttpHandler{

public void ProcessRequest(HttpContext context)

NOTE Even though the Authentication Token is optional, EFM recommends that you use it along with HTTPS (and not HTTP) for invoking the Web Service.

Chapter 5 - Survey Event Handler Show error page on event handler errors



{var authenticationHeader = context.Request.Headers["AuthenticationHeader"];

// Invalid Tokenif (authenticationHeader != "1234"){

context.Response.End();}

// TODO: Do Work

}

public bool IsReusable{

get { return false; }}

}

}

Show error page on event handler errorsIf the survey event handler is unavailable, then the error page is shown notifying you that the web browser could not link to the requested survey page and listing possible solutions. This option is clear by default.

Chapter 5 - Survey Event Handler Notify the email address about Web Service Errors



Show error page on event handler errors

Notify the email address about Web Service ErrorsYou can specify an email address to receive notifications when the survey event handler generates an error. Enter the email address in the text box. The survey author email address is pre-populated by default.

The following information is available in the email message:

Event

URL

Survey

Respondent

Error

This option is selected by default.

Chapter 5 - Survey Event Handler Notify the email address about Web Service Errors



Notify the email address

Chapter 5 - Survey Event Handler Survey Event Descriptions



Survey Event Descriptions

Survey StartSelect this option to call the Web Service when participants click the link to begin the survey. Only preloaded data is sent from the survey engine to the Web service during this event.

Page SubmitUse Page Submit to send survey data while the survey participant is going from page to page in the survey. Options in the Page Submit drop-down menu include:

None (fast)

Only the Responses Submitted for the Page (average)

All non-empty Responses for the Survey (slow)

Survey EndSelect this option to call the Web Service when participants complete the survey. All data is sent from the survey engine to the Web Service during this event. This is typically either from clicking the Submit button or a branch to End option. Options in the Survey End drop-down menu include:

None (fast)

Only the Responses Submitted for the Page (average)

All non-empty Responses for the Survey (slow)

Pre-Save and Pre-Response Check BoxesPre-Save - Called before data is saved to the database. Allows the Web Service to stop or change data from being saved to the response table.

Pre-Response - Called before the page is rendered back to the respondent. This allows the Web Service to return a table of replacement fields that the survey engine will expand and replace on the page about to be displayed to the respondent.

Chapter 5 - Survey Event Handler Response Data Sent



Response Data SentYou can select when you want events to occur in your survey. For example, the survey author can have the event occur at the start of a survey or at the start of the survey and every page in the middle of the survey.

Survey event options

Chapter 5 - Survey Event Handler Sample Survey Event Handler



Sample Survey Event HandlerIncluded along with the starter project is a sample Web Service Survey Event Handler. It is a simple code validation survey meant to showcase basic usage of the survey event process.

The first page of the survey has a single entry field. If you enter the secret code of "1234", you pass normally into the survey. If you click Next without entering anything, the HTML replacement feature is used to display an error message. If you enter a wrong code, you are redirected to a custom URL.

Steps for Using the Sample Code Provided1 Compile and run the EFM.SEWS.Demo solution. Note where the website is running.

This is where you are hosting your Web Service.

2 Upload the ReceiptCode.que to a new survey.

3 Edit the Survey Event Handler dialog box for this survey to point to the new Web Service endpoint.

4 Save and republish the survey.

5 Clicking the survey link will display the following screen:

Chapter 5 - Survey Event Handler Steps for Using the Sample Code Provided



6 No entry will result in an error message displayed (inline).

7 An incorrect entry will redirect to www.verint.com.

8 Entering the secret code "1234" will take you to the second page.

NOTE If you did not receive the .zip file that contains the sample code, please contact Verint Support for assistance http://www.vovici.com/support, Phone 1.866.827.7474, Email [email protected] or call Information Development at 571-521-0516.

[email protected]

[email protected]

C h a p t e r 6

Hierarchical Questions Web Service1

Topics Setup, page 242

Adding a Hierarchical Question to Your Survey, page 243

Example of Using a Web Service for Hierarchical Questions, page 245

Sample Web Service, page 246

1 Hierarchical Question Web Service - This is a Web Service that is hosted on the customer's server thatEFM can call out to. You can use the User Interface (UI) in the EFM Library to design a hierarchical ques-tion but if you have hundreds or even thousands of items in your hierarchy the UI is unusable. Instead youcan write a Web Service that can call to populate the hierarchy as a participant is shown the survey. Thesurvey engine calls the Web Service to get the first list of items on the page (e.g., make of car). Every timethe participant makes a selection, EFM calls the Web Service to get the next list (e.g., participant selectsToyota and the Web Service is called to get a list of Toyota models).

Chapter 6 - Hierarchical Questions Web Service Setup



Setup1 Go to the Library main page (select the Library tab). The Library main page

defaults to the Questions tab.

2 Click Hierarchical Questions, and then click New. The page for creating a new hierarchical question opens.

3 At the top of the page, enter the title of your hierarchical question. By default, the question title is Untitled (N), where N is the sequence number of the created hierarchical question.

4 Enter your Question Heading text and add your question to the Question Text area.

5 Create a List Caption (optional).

6 In the Instructions text box, provide extra instructions to the question (optional).

7 Select the Web Service tab.

Web Service tab8 Type in the URL of your Web Service into the Web Service URL text box field.

9 Type in the Step Labels (one per line, for example, Make, Model, and Year)

NOTE In Classic survey rendering mode, instructions text is not displayed in the survey.

NOTE The Web Service option is used to integrate with your Web Service client. You must have the EFM Enterprise edition to use Hierarchical Question functionality.

Chapter 6 - Hierarchical Questions Web Service Adding a Hierarchical Question to Your Survey



Adding a Hierarchical Question to Your Survey

Hierarchical Questions are added to your survey through the Add drop-down menu within the Design page. Select Add from Library from the Add drop-down menu and go to the Hierarchical Questions tab. Select the check box next to the hierarchical question you want to add and click OK.

Design/ Add from Library

Chapter 6 - Hierarchical Questions Web Service Adding a Hierarchical Question to Your Survey



Hierarchical Questions tabNOTE You can select multiple questions to be added to your survey at a time in

the order they appear in the Questions list.

Chapter 6 - Hierarchical Questions Web Service Example of Using a Web Service for Hierarchical Questions



Example of Using a Web Service for Hierarchical Questions

You can create a Web Service call that gets a list of choices from an external database. When your survey participant selects a choice from step one, the Web Service is called with that choice as an argument and goes to the external database, takes the choices associated with that list, and populates the next step's drop-down.

The same process occurs when your participant selects a choice from the second step list. The Web Service is called with that choice as an argument, goes to the external database, takes the choices associated with that list, and populates the next step. This process continues based on how many steps are in your hierarchical question. Each time a step needs to be populated with choices, the Web Service is called.

Chapter 6 - Hierarchical Questions Web Service Sample Web Service



Sample Web ServiceIncluded along with the starter project is a sample Web Service Hierarchical Question. It is a simple code sample meant to illustrate the basic structure of the hierarchical question web service. In the .zip file provided, there are two sample files - HierarchicalListService.asmx and TestHierarchicalListService.asmx.

Zip file contentsThe following sample code is the skeleton for a hierarchical question Web Service from HierarchicalListService.asmx. The other file in the .zip file: TestHierarchicalListService.asmx is a self-contained functioning Web Service sample.

<%@ WebService Language="C#" Class="HierarchicalListService" %>using System.Web.Services;using System.Web.Services.Protocols;using System.Xml;using EFM.SurveyEngineServices;[WebService(Namespace = "http://www.vovici.com/v5/hierarchicallist")][WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]public class HierarchicalListService : WebService {

public AuthenticationHeader AuthenticationHeader;/// <summary>/// Return the items for a particular step in a hierarchical list./// The parameters are passed in XML for future expansion./// </summary>/// <param name="xmlString">XML string with format:/// <List Question="DBHEADING" Step="STEPNUMBER" Culture="ISO-CODE">/// <Previous>VALUE OF PREVIOUS STEP</Previous>/// </List>/// </param>/// <returns>XML with the following format; ListItem node repeats:/// <ListItems>/// <ListItem value="CODE">/// <Text>STRING TO DISPLAY</Text>/// </ListItem>/// </ListItems>/// </returns>

Chapter 6 - Hierarchical Questions Web Service Steps for Using the Sample Code Provided



[SoapHeader("AuthenticationHeader", Direction = SoapHeaderDirection.In)][WebMethod(EnableSession = true, Description = "Get a list of items for a hierarchical list.")]public XmlNode GetHierarchicalList(string xmlString) {

XmlDocument doc = new XmlDocument();XmlElement root = doc.CreateElement("ListItems");doc.AppendChild(root);return doc;

}}

Steps for Using the Sample Code Provided1 Load the sample file TestHierarchicalListService.asmx onto a server you own that is

accessible by the EFM survey engine.

2 Create a hierarchical question as follows:

a. Select the Library tab

b. Select Hierarchical Questionsc. Click Newd. Fill in the Question tab.

Hierarchical Questions/Question tab

NOTE To use the hierarchical question in a translated survey, use the Culture passed in the List element to translate the Text elements in the ListItems node.




3 Fill in the Web Service tab.

Web Service tab

4 Create a new survey.

5 From within the Design page, select Add from Library.

6 Select the Hierarchical Questions tab.

7 Select Country & State/Province.

NOTE Change the Web Service URL field to point to the Web Service on your server.




8 Click OK.

9 Click Test to publish the survey. The displayed survey looks similar to the following image.

Testing Your Survey

NOTE If you did not receive the .zip file with the sample code, contact Verint Support at http://www.vovici.com/support, Phone 1.866.827.7474, Email [email protected] or call Information Development at 571-521-0516.

[email protected]

[email protected]

C h a p t e r 7

Survey Engine API - Getting Started

Topics General Introduction, page 251

Initial request, page 252

Working with survey, page 256

Survey page elements, page 258

Survey pages, page 306

Custom Properties, page 312

Chapter 7 - Survey Engine API - Getting Started General Introduction



General IntroductionWith the Survey Engine API, the survey taking experience can be delivered into any device with a display such as a company’s mobile application or even a wearable device application. The Survey Engine API supports all question types and conditional logic that are available within the traditional web respondent experience. The Survey Engine API puts the power of collecting in-the-moment feedback into the hands of the developer.

The Survey Engine API allows you to combine the survey logic in the EFM application with a customized User Interface to produce advanced application and device-specific surveys.

The Survey Engine API application communicates with the EFM Survey Engine using JSON data structures. The JSON representation of the survey describes all the rendering options specified by the survey author. This enables the API application to render the questions in its own way. Question responses are presented back to the Survey Engine using similar JSON data structures.

Chapter 7 - Survey Engine API - Getting Started Initial request



Initial request

Submit initial request and trigger the APITo submit the initial request, complete the following steps:

Procedure1 In EFM, open the needed survey in survey designer, and then on the Properties

panel, select the Enable Survey Engine API option.

2 Obtain a link to the needed EFM survey.

3 Submit the initial HTTP-protocol request method: "GET" or "POST".

4 Provide Request Header:

For "GET" request: Accept: application/json

For "POST" request: Content-Type: application/json

5 For "Post" request, leave the request body empty or include an object with the properties Culture and Formatting: (for an example, see “Initial "GET" and "POST" requests” on page 314)

Culture – Indicates request language in which survey should be represented. The default value is the survey default language. Example: “Culture”: “en-US”.

Formatting – Indicates format of strings in the JSON response returned by Survey Engine API with possible values of "html” or “text.” This property defines whether strings are formatted as HTML tags (for example, <b>text</b>) or plain text (for example, text). The default value is “html”. Example: {“Formatting”: “html”}.

NOTE If the Enable Survey Engine API option is cleared, the request to Survey Engine API returns a JSON error page with the corresponding message.

NOTE If any or both of these properties are not specified, the default values are used to generate the response.

Chapter 7 - Survey Engine API - Getting Started JSON response returned after initial request



JSON response returned after initial requestAfter submitting the initial request, you receive a JSON response from the Survey Engine API. The response is the first Content Page of the survey, which is presented with the properties provided in the table. Each property is provided in the form "Property Name": "value" (For an example, see “Initial Content Page response” on page 315)

Property Type Description

"Type" String Type of the page. The value can be "Content Page" or "End Page".

"SurveyID" String Automatically generated ID of the survey, which is a combination of Group ID, Project ID, and Record ID in hexadecimal format. This property is not required for the initial request; for the following requests, the values provided in the Survey Engine API response are used.

"SessionKey" String Automatically generated unique key of the respondent session, which is represented as a GUID value. This property is not required for the initial request; for the following requests, the values provided in the Survey Engine API response are used.

"Culture" String Culture of the survey:"Culture": "en-US"

"CurrentPageID" String Number of the current survey page. Possible values are 1 to n, where n is the number of the last survey page.

"Title" String Title of the survey.

Chapter 7 - Survey Engine API - Getting Started JSON response returned after initial request



"CustomProperties"(optional)

Object Custom properties set when designing a survey (if present). Object property name is custom property name, and object property value is custom property value (See “Custom Properties” on page 312):"CustomProperties": {

"custom_property_1": "1"

"custom_property_2":

}

"Elements" Array All questions and page elements of the current page. The section can be empty if there are no elements on the page.

"Buttons" Object List of buttons available on the current page. For the list of buttons, see “List of buttons” on page 255:"back": "Back"

"Tagline" String Survey tagline that is set during survey design on the Formatting side tab > General drawer.

"Progress" Object Object that specifies progress bar options. The Progress object is included only if the page type is a Content Page and the Show Progress Indicator option is selected during survey design on the Formatting side tab > Progress Bar drawer. For the object properties, see “"Progress" properties” on page 255.


Chapter 7 - Survey Engine API - Getting Started "Progress" properties



"Progress" properties

The "Progress" object includes the properties listed in the following table:

List of buttons

The survey can contain some or all the buttons provided in the table. The buttons are defined in the "Buttons" object of the Content Page JSON.


"Percent" Integer Percent of survey completed. Possible values are from 0 to 100.

"Text" String Progress bar text. Example: "Page 1 of 10". The property is included only if the Show Page Number option is selected during survey design on the Formatting side tab > Progress Bar drawer.

"Appearance" String Progress bar appearance. Possible values are default, striped, or striped animated.

Button Value

"back" "Back"

"next" "Next"

"save" "Save"

"jump" "Jump"

"reset" "Reset"

"submit" "Submit Survey"

NOTE All JSON properties sent by Survey Engine API must be sent back to the server.

Chapter 7 - Survey Engine API - Getting Started Working with survey



Working with survey

Actions performed on a surveySurvey Engine API allows you to perform various actions on a survey, which are provided in the table. The needed action must be defined in the "Action" property of the Request Body.

NOTE The requested action should be applicable to the current survey page. For example, you cannot submit "Action": "next" if the survey contains only one page.

Action value Description

"back" Returns previous page.

"next" Returns next page.

"submit" Submits the survey.

"save" Saves respondent session.

"reset" Resets responses on the current page.

"jump" Returns survey Jump Page.

"jumpto" Returns the page defined in the "JumpPageID" property. See “Jump to request” on page 320.

"lang" Sets respondent’s culture to the one provided in the "Culture" property. See “Language Selection page” on page 308.

Chapter 7 - Survey Engine API - Getting Started Requests



RequestsTo perform actions on your survey, after receiving data from the initial request, preserve the Request Header and add the Request Body with the following properties defined:

"SurveyID" (Required) - The same as in the response returned after the initial request.

"SessionKey" (Required) – The same as in the response returned after the initial request.

"CurrentPageID" (Required) – The same as in the response returned after the initial request.

"Action" (Required) – Includes actions requested to be performed on the survey. For example, "Action": "next".

"Data" – Includes answers to survey questions, which is sent to the server. For example, "Q1": "1".

"Formatting" – Indicates format of strings in the JSON response returned by Survey Engine API with possible values of "html" or "text." If the property is not specified, all strings in JSON response is returned with HTML tags.

Answering questionsYou can answer survey questions using a JSON request. Answers to the questions are specified in the Data property of the Request Body, which is provided after all the required properties. For example:

"Data": {"Q1": "4","Q2": "1","Q3": "2"

}

In this example, "Q1" is the DB Heading of the question (Choose One) and "4" is the number of a choice for this question. (For an example of the full request, see “Page data in request” on page 319.)

NOTE In addition, the Formatting property should be sent in the request with possible values of "html" or "text." If the property is not specified, all strings in JSON response is returned with HTML tags.

Chapter 7 - Survey Engine API - Getting Started Survey page elements



Survey page elements

All page elements rendered in a survey are provided in the Elements property of the Content Page JSON as an array of elements. The following sections explain the JSON structure and representation of these elements.

Simple page elementsThe following page elements are rendered similarly in a survey and have similar JSON properties:

Text Section Heading Comment Code Block

These elements contain the following properties: Id, Type, and Body. The value for the Body property is the text provided in the body of the corresponding element. For the ID and Type values, view the following table:

ID and Type values for simple page elements

NOTE Comment is Hidden by default. To view the Comment Json in the returned Survey Engine API response, change its Visibility to Shown when designing a survey.

NOTE For these elements, an answer is not expected.

Page element ID Type

Text T[1..N] TextBlock

Section Heading S[1..N] Section

Comment C[1..N] Comment

Code Block CB[1..N] CodeBlock

NOTE For an example of simple page elements JSON, see “Simple page elements” on page 321.

Chapter 7 - Survey Engine API - Getting Started Questions



Questions

Common question properties

Each question can have multiple properties in a survey, therefore the returned JSON includes the properties defined for the specific question when designing the survey. Such properties are provided for each element separately in the following sections:

All questions also contain various common properties in the JSON response, which are provided in the following table:

In addition, all questions share the following peculiarities when rendered in JSON:

Only the questions and choices defined as visible in the Question Visibility and Choice Visibility designers are included in the returned JSON.

If the Randomize Choices option is selected for the question, the corresponding choices (and groups if present) are randomized. This option is not displayed in the returned JSON.


"ID" String Unique identifier of a question (Q[1..N]).

"Type" String Question type (Choose One, Short Answer, and so on.)

"Heading"(optional)

String Question heading. The property is available only if the Show Question Heading option is selected for the current question.

"Body" String Question text.

"Instructions" (optional)

String Instructions to the question if provided.

"Validations" Array The list of required question validations, if defined. For more information, see “Validations” on page 261.

NOTE However, if the hidden (or conditionally hidden) question contains preselected values, it is included in the returned JSON. For more information, see “Hidden questions” on page 304.

Chapter 7 - Survey Engine API - Getting Started Common question properties



If the Reverse Order of Choices is selected, the corresponding choices (and groups if present) are reversed. This option is not displayed in the returned JSON.

Fixed Position option is applied if the choices are randomized or reversed. This option is not displayed in the returned JSON.

Chapter 7 - Survey Engine API - Getting Started Validations



Validations

Each validation defined for a question consists of the following properties:


"Id" String Unique identifier of a question or filed that is checked against validation criteria.

"Type" String Validation type. For example:

Answer Required("ReqAns")

Enable Characters Limitation ("CharactersMaxLength"), and so on.

Specific validations for each question type are described in the corresponding question sections below.

"Message" String The corresponding validation message.

"Setting" String Validation value. Appears for:

Essay question if character limit validation is set to maximum characters allowed

Choose Many question if the Respondent Must Pick option is set to a specific number of choices

Rank Order and Drag and Drop Rank Order questions (for "RnkTopX", "RnkAtMostX", "RankAtLeastX" validation types.)

Matrix question (see “Validations for Matrix question” on page 342)

Fill in the Blank question:

Allocation Total for Allocation validation

Length for Minimum Length validation

Ranges for Numeric Range validation

Characters for Valid Characters validation

Pattern for Text Mask validation

Operator and value for Validate Topics validation

Chapter 7 - Survey Engine API - Getting Started Validations



"Failed" Boolean Appears as true after the previous properties if validation fails upon clicking Next or Submit button: "Failed": "true"

NOTE The Validations property is provided after all question properties.


Chapter 7 - Survey Engine API - Getting Started Choose One question



Choose One question

In addition to the properties specified in “Common question properties” on page 259, the Choose One question can have all or some of the properties provided below. (For an example, see “Choose One question” on page 322.)


"Layout" String Layout of the Choose One question: "list", "scale", "row", "columns", "tablerow", "listbox", "dropdown", "star": "Layout": "list"

"Columns" Integer Property for Columns layout, which provides the number of columns:"Columns":2

"ListCaption" String Text specified for the list caption. The property is included only if Drop-down Box layout is selected:"ListCaption": "(Click here to choose)"

"ClearselectionOnRight" Boolean Property for Star Rating layout. True if the Show Clear Star Selection on Right option is selected. False if the option is cleared:"ClearSelectionOnRight": true

"DisplaySelection" Boolean Property for Star Rating layout.True if the Display Rating option is selected. False if the option is cleared:"DisplaySelection": true

"HideClearSelection" Boolean Property for Star Rating layout.True if the Hide Clear Star Selection option is selected. False if the option is cleared:"HideClearSelection": false




"Choices" Array Choice groups and choices of the question. Choice groups appear above the appropriate choices.

Choice groups properties:

"Type" Stirng Property indicating that this is a choice group:"Type": "Group"

"Label" String Label of the choice group:"Label": "Choice group label"

Choices properties:

"Type" String Property indicating that this is a choice:"Type": "Choice"

"Label" String Label of the choice:"Label": "Choice label"

"Value" Integer Value of the choice written to the database. The value can be 1..N or -1,-2,-3, etc. (for Coded values):"Value": 1

"Selected" Boolean Appears as true if the choice is selected due to Preselection settings or previously answered:"Selected":true





For an example of answering the Choose One question, see “Page data in request” on page 319.

"Specify" Object Appears if the Include "Please Specify" option is selected for the choice. It includes the Id (with column name where to store the specified response) and Value (with previous answer if available) properties:"Specify": {

"Id": "Q1SPECIFIED_2"

"Value": "Text of the answer"

}

"Validations" Array Answer Required: "ReqAns"

Answer Required for "Please Specify" Options: "ReqSpecify"

For more information, see “Validations” on page 261.


Chapter 7 - Survey Engine API - Getting Started Choose One with Image question



Choose One with Image question

In addition to the properties specified in “Common question properties” on page 259, the Choose One with Image question can have all or some of the properties provided below. (For an example, see “Choose One with Image question” on page 323.).


"Layout" String Layout of the Choose One with Image question: "smallimages" and "largeimages":"Layout": "smallimages"

"Choices" Array Choices of the question.

"Type" String Property indicating a choice:"Type": "Choice"


"Value" Integer Value of the choice written to the database. The possible values can be 1..N or -1,-2,-3, etc. (for Coded values):"Value": 1


"Specify" Object Appears if the Include "Please Specify" option is selected for the choice. For details, see “Choose One question” on page 322.

Chapter 7 - Survey Engine API - Getting Started Choose One with Image question



The Choose One with Image question is answered the same way as Choose One question (See “Page data in request” on page 319.)

"Image" String URL to the image provided in the choice:"Image": "http://.."





Chapter 7 - Survey Engine API - Getting Started Essay question



Essay question

In addition to the properties specified in “Common question properties” on page 259, the Essay question can have all or some of the following properties. (For an example, see “Essay question” on page 323.)

For an example of answering the Essay question, see “Page data in request” on page 319.


"Rows" Integer Number of lines that determine the text box height:"Rows": 5

"EnableCharacterCounter" Boolean Appears as true if the Enable Characters Limitation and Enable Characters Counter options are selected for the question:"EnableCharacterCounter": true

"CharacterLimit" Integer Maximum number of characters allowed in the answer if the EnableCharacterCounter property is true:"CharacterLimit": 1500

It is also provided in the Validations array of the question as "CharactersMaxLength" validation.

"Value" String Preselected or previously answered value:"Value": "Preselected answer"


Enable Characters Limitation: "CharactersMaxLength"


Chapter 7 - Survey Engine API - Getting Started Choose Many question



Choose Many question

In addition to the properties specified in “Common question properties” on page 259, the Choose Many question can have all or some of the following properties. (For an example, see “Choose Many question” on page 324.)


"Layout" String Layout of the Choose Many question: "list", "scale", "row", "columns", "tablerow":"Layout": "scale"

"Columns" Integer Property for Columns layout, which provides the number of columns:"Columns":2

"Choices" Array Choice groups and choices of the question. Choice groups appear above the appropriate choices.

Choice groups properties:

"Type" String Property indicating a choice group:"Type": "Group"


Choices properties:



"Id" String Column name where the choice response is stored:"Id": "Q1_1"


Chapter 7 - Survey Engine API - Getting Started Choose Many question



For an example of answering the Choose Many question, see “Page data in request” on page 319.


"Exclusive"(optional)

Boolean Appears as true if the Exclusive option is selected for the choice:"Exclusive": true



Respondent Must Pick:

At Least N Choice(s): "ChkMin"

At Most N Choice(s): "ChkMax"

Exactly N Choice(s): "ChkExc"



Chapter 7 - Survey Engine API - Getting Started Choose Many with Image question



Choose Many with Image question

In addition to the properties specified in “Common question properties” on page 259, the Choose Many with Image question can have all or some of the following properties. (For an example, see “Choose Many with Image question” on page 325.)


"Layout" String Layout of the Choose Many with Image question: "smallimages" and "largeimages":"Layout": "largeimages"

"Choices" Array Choices of the question. The Choices properties are provided below.



"Id" String Column name where the choice response is stored:"Id": "Q1_1"





Chapter 7 - Survey Engine API - Getting Started Choose Many with Image question



The Choose Many with Image question is answered the same way as Choose Many question (See “Page data in request” on page 319.)

"Image" String URL to the image provided in the choice:"Image": "http://.."



Respondent Must Pick:

At Least X Choice(s): "ChkMin"

At Most X Choice(s): "ChkMax"

Exactly X Choice(s): "ChkExc"



Chapter 7 - Survey Engine API - Getting Started Image Upload question



Image Upload question

In addition to the properties specified in “Common question properties” on page 259, the Image Upload question can have all or some of the properties provided below. (For an example, see “Image Upload question” on page 326.)


"Value" String Unique identifier of an image, which is a GUID value.This property is included only if the question is already answered:"Value": "ae9462ac-6845-4f9b-a6ab-2305ca9bfbef"

"AllowPhotoTagging" Boolean Property indicating whether Allow Photo Tagging option is selected for the question or not. Possible values are true or false:"AllowPhotoTagging": true

"Tags" Array Array of tag objects. This property is included only if the question was previously answered with tags added to the uploaded image. Tag object properties are described below.

"Text" String Tag text:"Text": "Tag text"

"X" Integer X coordinate of the tag. It is a decimal value between 1 and 0.This property is not provided for descriptive tags.

Chapter 7 - Survey Engine API - Getting Started Image Upload question



To respond to the Image Upload question, in the Data property of the Request Body, include question field of the following format: Q#_1_NAME, where Q# is the DB heading of the question. Possible values for this field are:

Empty string – If question response is not changed

Image data encoded in base64 format

"{DELETED}" – If previously selected image must be deleted.

To add tags to the uploaded image, in the Data property of the Request Body, include Tags field of the following format: Q#_1_TAGS, where Q# is a question ID. The value for this field must be a string with the serialized array of tag objects in the JSON. Tags field can be added only if image field is not empty. For the example, see “Page data in request” on page 319.

"Y" Integer Y coordinate of the tag. It is a decimal value between 1 and 0.This property is not provided for descriptive tags.


File type validation: "ImageFileType." The following image formats are supported: .bmp, .exif, .ico, .jpeg, .png, and .tiff.


NOTE If Q#_1_NAME and Q#_1_TAGS are missing or blank, previous image data is not overwritten.


Chapter 7 - Survey Engine API - Getting Started Rank Order question



Rank Order question

In addition to the properties specified in “Common question properties” on page 259, the Rank Order question can have all or some of the following properties. (For an example, see “Rank Order question” on page 326.)


"TopicCell"(optional)

String Row heading text if specified when designing the question:"TopicCell":"Row heading"

"ListCaption" String Text specified for the list caption. The property is included only if the Drop-down Box layout is selected:"ListCaption": "(Click here to choose)"

"Layout" Layout of the Rank Order question: "dropdown" and "list."Note that in JSON, the Radio Buttons layout is "list":"Layout": "dropdown"

"Topics" Array Array of topic objects. The Topics properties are provided below.

"Type" String Property indicating a topic:"Type": "Topic"

"Id" String Column name where the topic response is stored:"Id": "Q1_A_1"

"Label" String Label of the topic:"Label": "Topic label"

"Value" Integer The selected choice value for the topic. This property is included only if the question is already answered."Value": 1

Chapter 7 - Survey Engine API - Getting Started Rank Order question



For an example of answering the Rank Order question, see “Page data in request” on page 319.




"Value" Integer Value of the choice written to the database. The possible values can be 1..N or -1,-2,-3, etc. (for Coded values):"Value": 1


Unique answer for each topic (always included): "ReqRnk"

Respondent Must Rank:

At Least X Topic(s): "RnkAtLeastX"

At Most X topic(s): "RnkAtMostX"

Top X Topic(s): "RnkTopX"

All Topics: "RnkAll"



Chapter 7 - Survey Engine API - Getting Started Drag and Drop Rank Order question



Drag and Drop Rank Order question

In addition to the properties specified in “Common question properties” on page 259, the Rank Order question can have all or some of the following properties. (For an example, see “Drag and Drop Rank Order question” on page 328.)






"Image"(optional)

String URL to the image provided in the topic if present:"URL": "http//.."

"Value" Integer The selected rank value for the topic. This property is included only if the question is already answered."Value": 1




Chapter 7 - Survey Engine API - Getting Started Drag and Drop Rank Order question



The Drag and Drop Rank Order question is answered the same way as Rank Order question (See “Page data in request” on page 319.)



Unique answer for each topic (always included): "ReqRnk"

Respondent Must Rank:

At Least X Topic(s): "RnkAtLeastX"

At Most X topic(s): "RnkAtMostX"

Top X Topic(s): "RnkTopX"

All Topics: "RnkAll"



Chapter 7 - Survey Engine API - Getting Started Scale Slider question



Scale Slider question

In addition to the properties specified in “Common question properties” on page 259, the Scale Slider question can have all or some of the following properties. (For an example, see “Scale Slider question” on page 329.)


"ClearSelectionOnRight" Boolean Property for Star layout. True if the Show Clear Star Selection on Right option is selected. False if the option is cleared:"ClearSelectionOnRight": true

"DisplaySelection" Boolean Property for Star layout. True if the Display Rating option is selected. False if the option is cleared:"DisplaySelection": true

"HideClearSelection" Boolean Property for Star layout. True if the Hide Clear Star Selection Option option is selected. False if the option is cleared:"HideClearSelection": true



"Layout" String Layout of the Scale Slider question: "star" and "scale." Note that in JSON, the Slider layout is "scale":"Layout": "star"



Chapter 7 - Survey Engine API - Getting Started Scale Slider question



For an example of answering the Scale Slider question, see “Page data in request” on page 319.



"Image"(optional)


"Value" Integer The selected choice value for the topic. This property is included only if the question is already answered."Value": 1








Chapter 7 - Survey Engine API - Getting Started Matrix question



Matrix question

In addition to the properties specified in “Common question properties” on page 259, the Matrix question can have all or some of the following properties. (For an example, see “Matrix question (Choose One side)” on page 330.)




"IndicateOddEven" Boolean Property indicating if the Indicate Odd and Even Rows option is selected for the question or not. Possible values are true or false:"IndicateOddEven": true

"RepeatHeadings" Integer Number of rows after which table headings repeat. Appears if the Repeat headings every X Row(s) option is selected for the question:"RepeatHeadings": 3

"TotalLAbel" String Label text for Total row. This property is included only if the Show Running Total option is selected for any Short Answer sides with Whole Number or Real Number input types:"TotalLabel":"Total"



"Id" String Unique identifier of the topic. Possible values are 1..n:"Id": "1"


"Sides" Array Array of side objects. The Sides properties are provided below.

Chapter 7 - Survey Engine API - Getting Started Matrix question



For information about answering the Matrix question, see side type sections below.

"Type" String Type of the side (Choose One, Choose Many, Short Answer, or Essay):"Type": "Short Answer"

"Id" String Unique identifier of the side:"Id": "Q1_A"

"Category"(optional)

String Side category text if specified when designing the question:"Category": "Category text"

"Validations" Array Validations array depends on the sides of the Matrix question and options selected for the sides. For details, see “Validations for Matrix question” on page 342 and “Validations” on page 261.


Chapter 7 - Survey Engine API - Getting Started Matrix Choose One side



Matrix Choose One side

The Matrix Choose One side can have all or some of the properties provided below. (For an example, see “Matrix question (Choose One side)” on page 330.)


"Type" String Type of the Matrix side:"Type":"ChooseOne"

"Id" String Unique identifier of the side"Id": "Q1_A"



"ShowChoiceLabels" Boolean Property indicating if the Show Choice Labels option is selected for the sides or not. Possible values are true or false:"ShowChoiceLabels": true

"Layout" String Layout of the Matrix Choose One side: "list" and "dropdown":"Layout": "dropdown"

"ListCaption" String Text specified for the list caption. This Property is included only if the Drop-down Box layout is selected:"ListCaption": "(Click here to choose)"

"TopicChoices" Array Array of arrays of choice and choice group objects. Each item in TopicChoices array is an array of choices or choice groups in relation to the topic. Order of items in TopicChoices array is the same as order in Topics array of parent Matrix object. Properties of Choice and Group objects are provided below. Choice groups appear above the appropriate choices.




Choice groups properties

"Type" String Property indicating that this is a choice group:"Type": "Group"


Choices properties

"Type" String Property indicating that this is a choice:"Type": "Choice"


"Id" String Unique identifier of topic choice. Format: <side_id>_<topic_id>. All choices of the topic have the same value of Id property:"Id": "Q1_A_1"


"Selected"(optional)

Boolean Appears as true if the choice is selected due to Preselection settings or previously answered:"Selected":true

"Validations" Array See “Validations for Matrix question” on page 342 and “Validations” on page 261.





To respond to the Matrix Choose One question, in the Data property of the Request Body, include the properties that represent Choose One side fields. The name of the property is the DB Heading of the corresponding TopicChoice, and the value is the response value. For example:

"Data" {"Q1_A_1": "1","Q1_A_2": "2","Q1_A_3": "3"

}

Chapter 7 - Survey Engine API - Getting Started Matrix Choose Many side



Matrix Choose Many side

The Matrix Choose Many side can have all or some of the following properties.

(For an example, see Matrix question (Choose Many side), page 332.)


"Type" String Type of the Matrix side:"Type":"ChooseMany"




"ShowChoiceLabels" Boolean Property indicating if the Show Choice Labels option is selected for the sides or not. Possible values are true or false:"ShowChoiceLabels": true

"TopicChoices" Array Array of arrays of choice and choice group objects. Each item in TopicChoices array is an array of choices or choice groups in relation to the topic. Order of items in TopicChoices array is the same as order in Topics array of parent Matrix object. Properties of Choice and Group objects are provided below. Choice groups appear above the appropriate choices.

Choice groups properties

"Type" String Property indicating a choice group:"Type": "Group"


Chapter 7 - Survey Engine API - Getting Started Matrix Choose Many side



To respond to the Matrix Choose Many question, in the Data property of the Request Body, include the properties that represent Choose Many side fields. The name of the property is the DB Heading of the corresponding TopicChoice. The value is "1," if choice is selected, or "0" if choice is not selected. For example, the question contains three topics and each side contains three columns:

"Data" {"Q5_A_1": "1","Q5_A_2": "0","Q5_A_3": "1","Q5_A_4": "0","Q5_A_5": "1","Q5_A_6": "0","Q5_A_7": "1","Q5_A_8": "1","Q5_A_9": "1"

}

Choices properties



"Id" String Unique identifier of topic choice. Format: <side_id>_<topic_id>. All choices of the topic have the same value of Id property:"Id": "Q1_A_1"


Boolean Appears as true if the choice is selected due to Preselection settings or previously answered:"Selected":true





Chapter 7 - Survey Engine API - Getting Started Matrix Short Answer side



Matrix Short Answer side

The Matrix Short Answer side can have all or some of the following properties. (For an example, see “Matrix question (Short Answer side)” on page 334.)


"Type" String Type of the Matrix side:"Type":"FillIn"




"InputType" String Input type. For possible values, see “Input types for Matrix Short Answer side” on page 344.

"Placeholder" Input placeholder. For possible values, see “Input types for Matrix Short Answer side” on page 344.

"Alignment" String Alignment of text in the text field if specified when designing the question:"Alignment": "Left"

"UseSlider" Boolean Appears as true if the Display as Slider option is selected for the side. The property applies only to WholeNumber and RealNumber input types.

"SliderStep" Float Number specified in the Slider Step field. The property is included only if the UseSlider property is true.

"ShowRunningTotal" Boolean Appears as true if the Show Running Total option is selected for the side. The property applies only to WholeNumber and RealNumber input types.




"UseDatePicker" String Appears as true if date picker is selected to be shown for the Date input type.

"ListCaption" String Text specified for the list caption. The property is included only if the input type for the side is Autodropdown:"ListCaption": "(Click here to choose)"

"TopicResponses" Array Array of Short Answer side responses for matrix topics. This list matches the topics array of Matrix question. Properties for TopicResponses are provided below.

"Type" String Type of the response:"Type": "TopicResponse"

"Id" String Unique identifier of topic response. Format: <side_id>_<topic_id>:"Id": "Q1_A_1"

"Value"(optional)

String Preselected or previously answered value:"Value": "Preselected answer"

"AutoDropdown" Boolean Array of autodropdown objects. It is included only if input type for the side is Autodropdown. Properties for AutoDropdown are provided below.

"Key" String The Autodropdown text:"Key": "Option 1"

"Value" String The Autodropdown value:"Value": "Option 1"





To respond to the Matrix Short Answer question, in the Data property of the Request Body, include the properties that represent the Short Answer side fields. The name of the property is the DB Heading of the corresponding TopicResponse, and the value is the response value. For example:

"Data" {"Q5_A_1": "Short Answer side response for topic 1","Q5_A_2": "Short Answer side response for topic 2","Q5_A_3": "Short Answer side response for topic 3",

}

"MaxLength" String Maximum number of characters for the Text input type that is set in the Maximum Length field:"MaxLength": "20"



Chapter 7 - Survey Engine API - Getting Started Matrix Essay side



Matrix Essay side

The Matrix Essay side can have all or some of the following properties.

(For an example, see “Matrix question (Essay side)” on page 335.)


"Type" String Type of the Matrix side:"Type":"Essay"




"Rows" Integer Number of lines that determine the text box height:"Rows": 5

"EnableCharacterCounter" Boolean Appears as true if the Enable Characters Limitation and Enable Characters Counter options are selected for the question:"EnableCharacterCounter": true

"CharacterLimit" Integer Maximum number of characters allowed in the answer if the EnableCharacterCounter property is true:"CharacterLimit": 1500

It is also provided in the Validations array of the question as "CharactersMaxLength" validation.

"TopicResponses" Array Array of Essay side responses for matrix topics. This list matches the topics array of Matrix question. Properties for TopicResponses are provided below.

Chapter 7 - Survey Engine API - Getting Started Matrix Essay side



To respond to the Matrix Essay question, in the Data property of the Request Body, include the properties that represent the Essay side fields. The name of the property is the DB Heading of the corresponding TopicResponse, and the value is the response value. For example:

"Data" {"Q5_A_1": "Essay side response for topic 1","Q5_A_2": "Essay side response for topic 2","Q5_A_3": "essay side response for topic 3",

}

"Type" String Type of the response:"Type": "TopicResponse"

"Id" String Unique identifier of topic response. Format: <side_id>_<topic_id>:"Id": "Q1_A_1"

"Value"(optional)




Chapter 7 - Survey Engine API - Getting Started Scrolling Matrix question



Scrolling Matrix question

In addition to the properties specified in “Common question properties” on page 259, the Scale Slider question can have all or some of the following properties. (For an example, see “Scrolling Matrix question” on page 337.)


"Columns" Integer Number of columns in the question:"Columns": 3



"Topics" Array Array of topic objects. The Topics properties are provided below.o




"Image"(optional)


"Value" Integer The selected rank value for the topic. This property is included only if the question is already answered:"Value": "1"



"Label" String Label of the choice. The possible values can be 1..N (this property is not defined by user):"Label": "1"

Chapter 7 - Survey Engine API - Getting Started Scrolling Matrix question



To respond to the Scrolling Matrix question, in the Data property of the Request Body, include the properties that represent the question. The name of the property is the DB Heading of the corresponding Topic, and the value is the response value or "0" (if not answered). For example:

"Data" {"Q5_A_1": "1","Q5_A_2": "2","Q5_A_3": "0",

}





Chapter 7 - Survey Engine API - Getting Started Fill in the Blank question



Fill in the Blank question

In addition to the properties specified in “Common question properties” on page 259, the Fill in the Blank question can have all or some of the following properties. (For an example, see “Fill in the Blank question” on page 338.)


"ShowRunningTotal" Boolean Appears as true if the Show Running Total option is selected for the question. The property applies only to WholeNumber and RealNumber input types:"ShowRunningTotal": "true"

"TotalLabel" String Label specified in the Total Label field. The option is available only if ShowRunningTotal is true:"TotalLabel": "Total"

"ListCaption" String Text specified for the list caption. The property is included only if Autodropdown is selected as input type for the question:"ListCaption": "(Click here to choose)"

"Responses" Array Array of response objects. Responses properties are provided below.

"Type" String Property indicating a response:"Type": "Response"

"Id" String Column name where the response is stored:"Id": "Q1_1"




"InputType" String Input type of the response. Possible values are:

Text/ Password/Email Address

Whole Number/Real Number

Month, Day, and Year

Social Security Number

U.S. and Canadian Phone Number

International Phone Number

Zip Code/ Zip+4 Code

Canadian Postal Code

U.S and Canadian Postal Code

"InputType": "WholeNumber"

"Label" String Label of the response:"Label": "Topic text"

"Alignment" String Alignment of text in the text field if specified when designing the response:"Alignment": "Left"

"UseSlider" Boolean Appears as true if the Display as Slider option is selected for the response. The property applies only to WholeNumber and RealNumber input types.

"SliderStep" Number Number specified in the Slider Step field. The property is included only if the UseSlider property is true:"SliderStep": 3

"Symbol" String Symbol specified in the Symbol field:"Symbol": "%"





"SymbolOnLeft" Boolean Appears as true if symbol is selected and the Insert symbol to the left of the box option is selected.

"UseDatePicker" Boolean Appears as true if date picker is selected to be shown for the Date input type.

"Placeholder" String Placeholder value (for example, ghost text) if applicable:"Placeholder": "text"

"Value"(optional)


"Autodropdown" Array Array of autodropdown objects. It is included only if input type for the response is Autodropdown. Properties for AutoDropdown are provided below.







To respond to the Fill in the Blank question, in the Data property of the Request Body, include the properties that represent the question. The name of the property is the DB Heading of the corresponding Topic (Response), and the value is the response value, which is relevant to the response input type. For example:

"Data" {"Q5_1": "Text answer","Q5_2": "1564","Q5_3": "1564.454",

}



Allocation: "ReqSum"

Minimum Length: "MinLen"

Numeric Range: "Range"

Valid Characters: "ValidCharacters"

Text Mask: "TextMask"

Validate Topics: “MatchValue”, “NotMatchValue”, “LessThanValue”, “GreaterThanValue”, “LessThanOrEqualValue”, “GreaterThanOrEqualValue”



Chapter 7 - Survey Engine API - Getting Started Short Answer question



Short Answer question

In addition to the properties specified in “Common question properties” on page 259, the Short Answer question can have all or some of the following properties. (For an example, see “Short Answer question” on page 340.)


"ListCaption" String Text specified for the list caption. The property is included only if Autodropdown is selected as input type for the question:"ListCaption": "(Click here to choose)"

"Responses" Array Array consisting of one response object. Responses properties are provided below.

"Type" String Property indicating a response:"Type": "Response"

"Id" String Column name where the response is stored:"Id": "Q1_1"

"InputType" String Input type of the response. Possible values are:

Text/ Password/Email Address

Whole Number/Real Number

Month, Day, and Year

Social Security Number

U.S. and Canadian Phone Number

International Phone Number

Zip Code/ Zip+4 Code

Canadian Postal Code

U.S and Canadian Postal Code

"InputType": "WholeNumber"




"Alignment" String Alignment of text in the text field if specified when designing the response:"Alignment": "Left"

"UseSlider" Boolean Appears as true if the Display as Slider option is selected for the response. The property applies only to WholeNumber and RealNumber input types.

"SliderStep" Number Number specified in the Slider Step field. The property is included only if the UseSlider property is true:"SliderStep": 3

"Symbol" String Symbol specified in the Symbol field:"Symbol": "%"

"SymbolOnLeft" Boolean Appears as true if symbol is selected and the Insert symbol to the left of the box option is selected.

"UseDatePicker" Boolean Appears as true if date picker is selected to be shown for the Date input type.

"Placeholder" String Placeholder value (for example, ghost text) if applicable:"Placeholder": "text"

"Value"(optional)


"Autodropdown" Array Array of autodropdown objects. It is included only if input type for the response is Autodropdown. Properties for AutoDropdown are provided below.






The Short answer question is answered the same way as Fill in the Blank question described in the preceding table.




Allocation: "ReqSum"

Minimum Length: "MinLen"

Numeric Range: "Range"

Valid Characters: "ValidCharacters"

Text Mask: "TextMask"

Validate Topics: “MatchValue”, “NotMatchValue”, “LessThanValue”, “GreaterThanValue”, “LessThanOrEqualValue”, “GreaterThanOrEqualValue”



Chapter 7 - Survey Engine API - Getting Started Hidden questions



Hidden questions

The returned JSON includes all question types that are hidden (or conditionally hidden) and not same page conditional if these questions contain preselected values (static, piped, or calculated fields.) The hidden question properties are provided in the following table. (For an example, see “Hidden questions (with Preselected option)” on page 341.)

Customer is responsible for replacing placeholders, evaluation of mathematical formulas, and validation of answers for the hidden questions with preselected values.

To respond to a hidden question, in the Data property of the Request Body, include the properties that represent the question fields. The name of the property is the DB Heading of the corresponding Topic, and the value is the relevant field value. For example:

"Data" {"Q1_1": "static preselected","Q1_2": "15","Q1_3": "30"

}

If the field value contains a placeholder from another relevant question, that question must also be answered to avoid data loss.


"Id" String Unique identifier of a question (Q[1..N]).

"Type" String Type of question visibility:"Type": "Hidden"

"Fields" Array Array of fields with a preselected value. Fields properties are provided below

"Id" String Unique identifier of a preselected response (Q[1..N]).

"Value" String Preselected value. The value can contain:

Preselected value (static preselected)

Value containing placeholders from other questions of the current survey page (“%Q1_1%”)

Mathematical formula (2 + 3)

Chapter 7 - Survey Engine API - Getting Started Hidden questions



If the field value contains a URL placeholder, on the first survey page, write the appropriate identifier with value. For example:

“Fields [{"Id":"Q2_2","Value":"URL.first"}] answer must be added to the URL of the survey on the first page: SurveyURL?first=15.

NOTE For several identifiers, "&" symbol should be used: “?first=15&second=20”.

Chapter 7 - Survey Engine API - Getting Started Survey pages



Survey pages

End pageThe returned JSON includes all properties of the survey End page. The JSON may differ depending on the selected behavior of the End page. The following table provides the End page properties for each possible behavior. (For an example, see “End page response (Standard behavior)” on page 317.)

NOTE The End page is not expected to be answered.


Standard behavior

"Type" String Type of the page:"Type": "EndPage"

"SurveyId" String Automatically generated ID of the survey, which is a combination of Group ID, Project ID, and Record ID in hexadecimal format.

"SessionKey" String Automatically generated unique key of the respondent session, which is represented as a GUID value.

"CurrentPageId" String Type of the End page. Possible values are "Submit", "BranchedOut", "InvalidAccess", "Closed", "OptOut", "JavascriptRequired", or "Save":"CurrentPageID": "Submit"

For custom End page, the value is "ENDnnn", where nnn is a number of the End page:"CurrentPageID": "END001"

"Title" String Title of the End page.

"Body" String Body text of the End page.

"TagLine" String Survey tagline that is set during survey design on the Formatting side tab > General drawer.

Chapter 7 - Survey Engine API - Getting Started End page



Redirect to an existing Web page behavior

"Type" String Type of the page:"Type": "EndPage"



"CurrentPageId" String Type of the End page. Possible values are "Submit", "BranchedOut", "InvalidAccess", "Closed", "OptOut", "JavascriptRequired", or "Save":"CurrentPageID": "Submit"

For custom End page, the value is "ENDnnn", where nnn is a number of the End page:"CurrentPageID": "END001"

"RedirectUrl" String URL of the webpage to which the End page should be redirected. The URL is provided when designing a survey:"RedirectURL": "http://www.example.com"



Chapter 7 - Survey Engine API - Getting Started Language Selection page



Language Selection pageLanguage Selection page JSON is returned from Survey Engine API if the survey contains more than one translation and one of the following conditions is met:

The Let the user manually select the survey language option was selected when designing the survey.

Initial request method is GET or POST with empty body.

Initial request method is POST, and Request Body does not contain the Culture property or Culture property value is invalid or contains Culture ID that does not match any of the survey translations.

The returned JSON of the Language Selection page includes the following properties. (For an example, see “Language Selection page response” on page 317.)


"Type" String Type of the page:"Type": "LanguageSelectionPage"



"Title" String Title of the Language Selection page.

"Body" String Body text of the Language Selection page. Contains the “%LANGUAGES%” placeholder which indicates where language list should be placed.

"Languages" Array Array of language objects. Represents all available language translations for the survey. The Language object properties are provided below.

"Id" String Language culture name (for example, "en-US.")

"EnglishName" String Language display name in English.

Chapter 7 - Survey Engine API - Getting Started Language Selection page



To select the needed language and proceed to the translated survey, in the Request Body provide the following properties:

"Culture" with the value of the selected language.

"Action" with the value "lang"

"Formatting" with possible values of "html" or "text." If the property is not specified, all strings in JSON response is returned with HTML tags.

For example:{

"Culture": "de-De""Action": "lang""Formatting": "html"

}

"NativeName" String Language display name in native language.


NOTE The selected language ID should match the ID of one of the languages provided in the Languages array.


Chapter 7 - Survey Engine API - Getting Started Jump page



Jump pageThe returned JSON of the Jump page includes the following properties. (For an example, see Jump page response, page 318.)


"Type" String Type of the page:"Type": "JumpPage"



"Culture" String Culture of the survey:"Culture": "en-US"

"Title" String Title of the Jump page.

"CurrentPageId" String Number of the survey page, from which respondent gets to the Jump page (clicks Jump.)

"Body" String Body text of the Jump page.

"Pages" Array Array of the available survey pages. The Pages properties are provided below.

"Id" String Unique identifier of the page.

"Label" String Label of the page. For example, Page N, where N is a sequential number, which ignores unavailable pages.


Boolean Appears as true for the page, from which respondent jumped.

"Buttons" Object Object for the Back button:"back": "Back"


Chapter 7 - Survey Engine API - Getting Started Jump page



After receiving the Jump page, you can perform the following actions:

"back" action to get to the previous page (see “Actions performed on a survey” on page 256.)

"jumpto" action to proceed to the selected page. For an example of jumpto request, see “Jump to request” on page 320.

Chapter 7 - Survey Engine API - Getting Started Custom Properties



Custom PropertiesContent page and question objects’ JSON can include the CustomProperties property. This property is optional and is included in JSON only if any custom properties are set for a survey or question when designing a survey. The value for this property is an object, which contains a list of all defined custom properties. Object property name is custom property name, and object property value is custom property value. Following is an example of JSON with included custom properties:

{"Type": "ContentPage","SurveyId": "30C25E9017D0E2A2","SessionKey": "03b71e6b-d044-4d69-811b-46cc42ba1b28","Culture": "en-US","CurrentPageID" : "1","Title": "Custom Properties Survey","CustomProperties": {

"survey_custom_property_1": "1","survey_custom_property_2": "2","survey_custom_property_3": "3",

}"Elements": {

{"Id": "Q1","Type": "Essay","Body": "Question Text","Rows": 3,"CustomProperties": {

"question_custom_property_1": "1","question_custom_property_2": "2","question_custom_property_3": "3",

}}],"Buttons": {

"submit": "Submit Survey"}

}

C h a p t e r 8

Appendix

Topics Campaign Statuses, page 312

Survey Engine API - JSON examples, page 314

Validations for Matrix question, page 342

Input types for Matrix Short Answer side, page 344

Chapter 8 - Appendix Campaign Statuses



Campaign Statuses


0 No Action/Not Sent.

1 Passed to mail server - sent to Hurricane Server.

Deferred

10 Error received in response from recipients' mail server.

11 Error connecting to recipients' mail server.

12 There was an error with the DNS server.

13 Deferred.

14 Deferred by SMS service.

Delivered

20 Delivered by Hurricane or Sent to SMTP Server.

Failure

30 Error received in response from recipients' mail server.

31 Error connecting to recipients' mail server.

32 There was an error with the DNS server.

33 Failure.

34 Invalid Email Address.

Bounce

40 The message is a challenge response message, which requires further action for the original message to be delivered. For example, Click this link to verify the message is coming from a human.

41 Your message was blocked for an unknown or general reason. For example, A word in the message triggered content filtering to fail the message.

42 Your message contained a virus and was blocked.

43 Your message was identified as spam and was blocked.

Chapter 8 - Appendix Campaign Statuses



44 The server was unable to deliver the message due to a permanent error. A permanent failure is one, which is not likely to be resolved by resending the message in the current form. Some change to the message or the destination must be made for successful delivery.

45 The message was undeliverable.

46 The message was blocked.

70 User viewed message in mail client (Requested hidden image).

80 User clicked survey link. For example, Started the survey.

90 User unsubscribed from the survey.

98 User branched out from the survey.

99 User over quota for the survey.

100 User completed the survey.


Chapter 8 - Appendix Survey Engine API - JSON examples



Survey Engine API - JSON examples

Initial "GET" and "POST" requests "GET" request:

"POST" request:

GET http://survey linkAccept: application/json

//Request Header

POST http://survey linkContent-Type: application/json

//Request Header

{"Culture": "en-US""Formatting": "html"

}

//Request Body

Chapter 8 - Appendix Initial Content Page response



Initial Content Page response{

"Type": "ContentPage","SurveyId": "62DFB1BA772C8CEE","SessionKey": "21af9238-b232-43b2-8cb3-e94c6a593ea0","Culture": "en-US","CurrentPageId": "1","Title": "My Survey","Elements": [

{"Id": "Q1","Type": "ChooseOne","Heading": "1","Body": "Select your country.","Layout": "list","Choices": [

{"Type": "Choice","Label": "Germany","Value": 1},{"Type": "Choice","Label": "Italy","Value": 2},{"Type": "Choice","Label": "USA","Value": 3}

]},{

"Id": "Q2","Type": "ShortAnswer","Body": "Provide your feedback below.","Responses": [

{"Type": "Response","Id": "Q2_1","InputType": "Text","Placeholder": "Text","MaxLength": "255"}

],"Validations": [

{"Id": "Q2_1","Type": "ReqAns","Message": "Please answer question 2 before continuing."}

]

Chapter 8 - Appendix Initial Content Page response



}],"Buttons": {

"submit": "Submit Survey"},"TagLine": "Powered by Verint <a href=\"http://www.verint.com\"

target=\"_blank\">survey software</a>","Progress": {

"Percent": 100,"Appearance": "default"}

}

Chapter 8 - Appendix End page response (Standard behavior)



End page response (Standard behavior){

"Type": "EndPage","SurveyId": "6226B2B16E87F13E08D3951CE70828EE0F","SessionKey": "f93d22cb-60ea-40ae-a16b-072f7e135820","CurrentPageId": "Submit","Title": "Survey Submitted","Body": "Thank you for completing this survey.","TagLine": "Conduct your own <a href=\"http://www.verint.com/solutions/enterprise-workforce-optimization/products/enterprise-feedback-management/index\" target=\"_blank\">online surveys</a>"

}

Language Selection page response{

"Type": "LanguageSelectionPage","SurveyId": "6226B2B16E87F13E","SessionKey": "bbd69765-df91-49de-9681-f9faa8f8fc21","Title": "My Survey","Body": "Select a language to take your survey in:<br /><br />%LANGUAGES%","Languages": [

{"Id": "en-US","EnglishName": "English (United States)","NativeName": "English (United States)"},{"Id": "th-TH","EnglishName": "Thai (Thailand)","NativeName": "??? (???)"},{"Id": "de-DE","EnglishName": "German (Germany)","NativeName": "Deutsch (Deutschland)"}

],"TagLine": "Powered by Verint: Conduct your own <a href=\"http://www.verint.com/solutions/enterprise-workforce-optimization/products/enterprise-feedback-management/index\" target=\"_blank\">online surveys</a>"

}

Chapter 8 - Appendix Jump page response



Jump page response{

"Type": "JumpPage","SurveyId": "6226B2B16E87F13E08D3951CE70828EE0F","SessionKey": "f93d22cb-60ea-40ae-a16b-072f7e135820","Culture": "en-US","Title": "My Survey","Body": "Select the page you wish to jump to.","CurrentPageId": "3","Pages": [

{"Id": "1","Label": "Page 1"},{"Id": "2","Label": "Page 2"},{"Id": "3","Label": "Page 3","Selected": true},{"Id": "4","Label": "Page 4"},{"Id": "5","Label": "Page 5"}

],"Buttons": {

"back": "Back"},"TagLine": "Powered by Verint: Publish your own <a href=\"http://www.verint.com/solutions/enterprise-workforce-optimization/products/enterprise-feedback-management/index\" target=\"_blank\">web survey</a> today"

}

Chapter 8 - Appendix Page data in request



Page data in requestIn the example below, a JSON request contains answers to four questions and action that triggers the next survey page.

{

"SurveyID": "30C25E90311720A9","SessionKey": "e6f79812-55c6-409d-88c9-0eca9acb8968","CurrentPageID": "1","Action": "next",

//Required page properties

"Data": {

"Q4":"2","Q4SPECIFIED_2": "Text of the answer"

// Choose One question with Please Specify option selected for the second choice

"Q5_1": "1","Q5_2": "0","Q5_3": "1",

// Choose Many question:

"1" if choice is selected

"0" if choice is not selected

"Q6_1": "Short answer", // Short Answer question

"Q7": "Essay answer", // Essay question

"Q8_1_NAME": "<Image Content in base64 encoded string>","Q8_1_TAGS": "[{\"Text\":\"Text\",\"X\":0.1,\"Y\""0.2}]",

// Image Upload question with tags

"Q10_A_1": "1","Q10_A_2": "2","Q10_A_3": "3"

// Matrix Choose One question

"Q1_A_1": "1","Q1_A_2": "2""Q1_A_3": "0"

// Rank Order question

"Q1_A_1": "1","Q1_A_2": "2""Q1_A_3": "0"

// Scale Slider question

},"Formatting": html"

Chapter 8 - Appendix Jump to request



Jump to request{

"SurveyId": "30C25E90311720A9", // Automatically generated ID of the survey

"SessionKey": "e6f79812-55c6-409d-88c9-0eca9acb8968",

//Unique key of the respondent session

"CurrentPageId": "3" // Number of the survey page, from which respondent gets to the Jump page

"JumpPageId": "4" // Number of the survey page, to which respondent wants to jump

"Action": "jumpto" // Jump to action

"Formatting": "html" // Format of the returned strings (optional)

}

Chapter 8 - Appendix Simple page elements



Simple page elementsThe example below contains the following page elements: Section Heading, Text, Code Block, and Comment.

"Elements": [

{"Id": "S1","Type": "Section","Body": "Section Heading"},{"Id": "T1","Type": "TextBlock","Body": "Text"},{"Id": "CB1","Type": "CodeBlock","Body": "Code"}{"Id": "C1","Type": "Comment","Body": "Text"}

]

Chapter 8 - Appendix Choose One question



Choose One question"Elements": [

{"Id": "Q1","Type": "ChooseOne","Heading": "Choose One_1","Body": "Select one option below.","Instructions": "This is Choose One question instructions","Layout": "list","Choices": [

{"Type": "Group","Label": "Choice Group 1"},{"Type": "Choice","Label": "Choice2","Value": 2,"Specify": {"Id": "Q1SPECIFIED_2"}},{"Type": "Choice","Label": "Choice1","Value": 1,"Selected": true},{"Type": "Group","Label": "Choice Group 2"},{"Type": "Choice","Label": "Choice4","Value": 3},{"Type": "Choice","Label": "Choice5","Value": 4}

],"Validations": [

{"Id": "Q1","Type": "ReqAns","Message": "Please answer question Choose One_1 before continuing."}

]}]

Chapter 8 - Appendix Choose One with Image question



Choose One with Image question"Elements": [

{"Id": "Q5","Type": "ImageChooseOne","Body": "Select one option below.","Layout": "smallimages","Choices": [

{"Type": "Choice","Label": "Choice1","Value": 1,"Image": "http://.."},{"Type": "Choice","Label": "Choice2","Value": 2,"Image": "http://.."}

]}]

Essay question"Elements": [

{"Id": "Q6","Type": "Essay","Body": "Provide the answer below.","Rows": 5,"CharacterLimit": 1500,"EnableCharacterCounter": true,"Value": "Preselected answer","Validations": [

{"Id": "Q6","Type": "ReqAns","Message": "Please answer question 1 before continuing."},{"Id": "Q6","Type": "CharactersMaxLength","Message": "No more than 1500 characters allowed (%2 entered).","Setting": "1500"}

]}]

Chapter 8 - Appendix Choose Many question



Choose Many question"Elements": [

{"Id": "Q10","Type": "ChooseMany","Body": "Select one or more options below.","Layout": "list","Choices": [

{"Type": "Choice","Label": "Choice1","Id": "Q10_3"},{"Type": "Choice","Label": "Choice2","Id": "Q10_2"},{"Type": "Choice","Label": "Choice3","Id": "Q10_1","Specify": {"Id": "Q10SPECIFIED_1"},"Exclusive": true}

],"Validations": [

{"Id": "Q10","Type": "ReqAns","Message": "Please answer question Choose Many_1 before continuing."},{"Id": "Q10","Type": "ReqSpecify","Message": "Please fill in the text box next to the selected choice in question Choose Many_1."},{"Id": "Q10","Type": "ChkMin","Message": "Please select at least 2 choices for question Choose Many_1.","Setting": "2"}

]}]

Chapter 8 - Appendix Choose Many with Image question



Choose Many with Image question"Elements": [

{"Id": "Q10","Type": "ImageChooseMany","Body": "Select one or more options below.","Instructions": "Optional instructions.","Layout": "smallimages","Choices": [

{"Type": "Choice","Label": "Choice1","Id": "Q10_1","Image": "http://..","Specify": {"Id": "Q10SPECIFIED_1"},"Exclusive": true},{"Type": "Choice","Label": "Choice2","Id": "Q10_2","Image": "http://.."}

],"Validations": [

{"Id": "Q10","Type": "ReqAns","Message": "Please answer question Choose Many with Image_1 before continuing."},{"Id": "Q10","Type": "ReqSpecify","Message": "Please fill in the text box next to the selected choice in question Choose Many with Image_1."},{"Id": "Q10","Type": "ChkExc","Message": "Please select exactly 1 choices to question Choose Many with Image_1.","Setting": "1"}

]}]

Chapter 8 - Appendix Image Upload question



Image Upload question"Elements": [

{"Id": "Q1","Type": "ImageUpload","Heading": "Image Upload_1","Body": "Upload the image you like.","Value": "c876291f-ccca-43a2-9821-6840ba9bea4c","AllowPhotoTagging": true,"Tags": [

{"Text": "My tag"}

],"Validations": [

{"Id": "Q1","Type": "ReqAns","Message": "Please answer question Image Upload_1 before continuing."},{"Id": "Q1","Type": "ImageFileType","Message": "Only the following image types are supported: bmp, exif, gif, ico, jpeg, png and tiff."}

]}]

Rank Order question"Elements": [

{"Id": "Q3","Type": "RankOrder","Heading": "Rank Order_1","Body": "Rank the topics below by selecting the corresponding choice.","ListCaption": "(Click here to choose)","TopicCell": "Row heading","Layout": "dropdown","Topics": [

{"Type": "Topic","Id": "Q3_A_1","Label": "Topic_1"},{"Type": "Topic","Id": "Q3_A_2",

Chapter 8 - Appendix Rank Order question



"Label": "Topic_2"},{ "Type": "Topic","Id": "Q3_A_3","Label": "Topic_3"}

],"Choices": [

{"Type": "Choice","Label": "1","Value": 1},{"Type": "Choice","Label": "2","Value": 2},{"Type": "Choice","Label": "3","Value": 3}

],"Validations": [

{"Id": "Q3","Type": "ReqAns","Message": "Please answer question Rank Order_1 before continuing."},{"Id": "Q3","Type": "ReqRnk","Message": "You must choose a unique answer for each topic of question Rank Order_1."},{"Id": "Q3","Type": "RnkAtleastX","Message": "You must rank at least 1 topics in order.","Setting": "1"}

]}]

Chapter 8 - Appendix Drag and Drop Rank Order question



Drag and Drop Rank Order question"Elements": [

{"Id": "Q5","Type": "DragDropRankOrder","Heading": "Drag and Drop Rank Order_1","Body": "Drag and drop the images below to rank the topics accordingly.","Instructions": "Instructions to the question.","Topics": [

{"Type": "Topic","Id": "Q5_A_1","Label": "Topic_1"},{"Type": "Topic","Id": "Q5_A_2","Label": "Topic_2","Image": "http://.."},{"Type": "Topic","Id": "Q5_A_3","Label": "Topic_3","Image": "http://.."}

],"Choices": [

{"Type": "Choice","Label": "1","Value": 1},{"Type": "Choice","Label": "2","Value": 2},{"Type": "Choice","Label": "3","Value": 3}

],"Validations": [

{"Id": "Q5","Type": "ReqAns","Message": "Please answer question Drag and Drop Rank Order_1 before continuing."},{

Chapter 8 - Appendix Scale Slider question



"Id": "Q5","Type": "ReqRnk","Message": "You must choose a unique answer for each topic of question Drag and Drop Rank Order_1."},{"Id": "Q5","Type": "RnkAtleastX","Message": "You must rank at least 1 topics in order.","Setting": "1"}

]}]

Scale Slider question"Elements": [

{"Id": "Q7","Type": "ScaleSlider","Heading": "1","Body": "Question Text","ClearSelectionOnRight": true,"DisplaySelection": false,"HideClearSelection": false,"TopicCell": "Row heading","Layout": "star","Topics": [

{"Type": "Topic","Id": "Q7_A_1","Label": "Topic Text with/without Image","Image": "http://.."},{"Type": "Topic","Id": "Q7_A_2","Label": "Topic Text with/without Image","Image": "http://.."},{"Type": "Topic","Id": "Q7_A_3","Label": "Topic Text with/without Image","Image": "http://.."}

],"Choices": [

{"Type": "Choice","Label": "1","Value": 1},

Chapter 8 - Appendix Matrix question (Choose One side)



{"Type": "Choice","Label": "2","Value": 2},{"Type": "Choice","Label": "3","Value": 3}

],"Validations": [

{"Id": "Q7","Type": "ReqAns","Message": "Please answer question 1 before continuing."}

]}]

Matrix question (Choose One side)"Elements": [

{"Id": "Q1","Type": "Matrix","Body": "Question text","TopicCell": "Row heading","IndicateOddEven": true,"RepeatHeadings": 1,"Topics": [

{"Type": "Topic","Id": "1","Label": "Row Text"},{"Type": "Topic","Id": "2","Label": "Row Text"},{"Type": "Topic","Id": "3","Label": "Row Text"}

],"Sides": [

{"Type": "ChooseOne","Id": "Q1_A","Category": "Category text","ShowChoiceLabels": false,

Chapter 8 - Appendix Matrix question (Choose One side)



"Layout": "dropdown","ListCaption": "","TopicChoices": [[

{"Type": "Choice","Label": "Column Text","Id": "Q1_A_1","Value": 1},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_1","Value": 2},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_1","Value": 3}

],[

{"Type": "Choice","Label": "Column Text","Id": "Q1_A_2","Value": 1},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_2","Value": 2},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_2","Value": 3}

],[

{"Type": "Choice","Label": "Column Text","Id": "Q1_A_3","Value": 1},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_3","Value": 2

Chapter 8 - Appendix Matrix question (Choose Many side)



},{"Type": "Choice","Label": "Column Text","Id": "Q1_A_3","Value": 3}

]]"Validations": [

{"Id": "Q1_A","Type": "ReqAns","Message": "Please answer question 1 (Category text) before continuing."},{"Id": "Q1_A","Type": "ReqRnk","Message": "You must choose a unique answer for each topic of question 1 (Category text)."}

]}

Matrix question (Choose Many side)"Elements": [

{"Id": "Q8","Type": "Matrix","Heading": "Matrix Choose Many question heading ","Body": "Question text","TopicCell": "Row heading","IndicateOddEven": true,"RepeatHeadings": 1,"Topics": [

{"Type": "Topic","Id": "1","Label": "Row text"},{"Type": "Topic","Id": "2","Label": "Row teat"}

],"Sides": [

{"Type": "ChooseMany","Id": "Q8_A","Category": "Category text","ShowChoiceLabels": true,

Chapter 8 - Appendix Matrix question (Choose Many side)



"TopicChoices": [[

{"Type": "Choice","Label": "Column Text","Id": "Q8_A_1"},{"Type": "Choice","Label": "Column Text","Id": "Q8_A_2","Selected": true,"Exclusive": true}

],[

{"Type": "Choice","Label": "Column Text","Id": "Q8_A_3"},{"Type": "Choice","Label": "Column Text","Id": "Q8_A_4","Selected": true,"Exclusive": true}

]]

}],"Validations": [

{"Id": "Q8_A","Type": "ReqAns","Message": "Please answer question Matrix Choose Many question heading (Category text) before continuing."}

]}

Chapter 8 - Appendix Matrix question (Short Answer side)



Matrix question (Short Answer side)"Elements": [

{"Id": "Q1","Type": "Matrix","Heading": "1","Body": "Question text","TopicCell": "Row heading","IndicateOddEven": true,"TotalLabel": "Total","Topics": [

{"Type": "Topic","Id": "1","Label": "Row Text"},{"Type": "Topic","Id": "2","Label": "Row Text"},{"Type": "Topic","Id": "3","Label": "Row Text"}

],"Sides": [

{"Type": "FillIn","Id": "Q1_A","Category": "Category textsidSlider S","InputType": "Text","Alignment": "Left","Placeholder": "Text","MaxLength": "255","TopicResponses": [

{"Type": "TopicResponse","Id": "Q1_A_1"},{"Type": "TopicResponse","Id": "Q1_A_2"},{"Type": "TopicResponse","Id": "Q1_A_3"}

]],"Validations": [

{

Chapter 8 - Appendix Matrix question (Essay side)



"Id": "Q1_A","Type": "ReqAns","Message": "Please answer question 1 (Category textsidSlider S) before continuing."},{"Id": "Q1_A","Type": "MinLen","Message": "Your answer is shorter than the minimum allowed length of 20 characters.","Setting": "20"}

]}

Matrix question (Essay side)"Elements": [

{"Id": "Q11","Type": "Matrix","Heading": "Matrix Essay question heading","Body": "Question text","TopicCell": "Row heading","IndicateOddEven": true,"RepeatHeadings": 2,"Topics": [

{"Type": "Topic","Id": "1","Label": "Row heading"},{"Type": "Topic","Id": "2","Label": "Row heading"}

],"Sides": [

{"Type": "Essay","Id": "Q11_A","Category": "Category text","Rows": 3,"EnableCharacterCounter": true,"CharacterLimit": 1500,"TopicResponses": [

{"Type": "TopicResponse","Id": "Q11_A_1","Value": "Response for topic 1"},{"Type": "TopicResponse",

Chapter 8 - Appendix Matrix question (Essay side)



"Id": "Q11_A_2","Value": "Response for topic 2"}

]}

],"Validations": [

{"Id": "Q11_A","Type": "ReqAns","Message": "Please answer question Matrix Essay question heading (Category text) before continuing."},{"Id": "Q11_A","Type": "CharactersMaxLength","Message": "No more than 1500 characters allowed (%2 entered).","Setting": "1500"}

]}

Chapter 8 - Appendix Scrolling Matrix question



Scrolling Matrix question"Elements": [

{"Id": "Q1","Type": "ScrollingMatrix","Body": "Question Text","Columns": 2,"TopicCell": "Row heading text","Topics": [

{"Type": "Topic","Id": "Q1_A_1","Label": "Topic Text with/without Image","Image": "http://.."},{"Type": "Topic","Id": "Q1_A_2","Label": "Topic Text with/without Image","Image": "http://.."},{"Type": "Topic","Id": "Q1_A_3","Label": "Topic Text with/without Image","Image": "http://.."}

],"Choices": [

{"Type": "Choice","Label": "Choice Text","Value": 1},{"Type": "Choice","Label": "Choice Text","Value": 2},{"Type": "Choice","Label": "Choice Text","Value": 3}

],"Validations": [

{"Id": "Q1","Type": "ReqAns","Message": "Please answer question 1 before continuing."}

]}]

Chapter 8 - Appendix Fill in the Blank question



Fill in the Blank question"Elements": [

{"Id": "Q3","Type": "FillIn","Heading": "1","Body": "Question text.","Responses": [

{"Type": "Response","Id": "Q3_1","InputType": "RealNumber","Label": "Topic text_1","Alignment": "Right","Symbol": "%","SymbolOnLeft": true,"Placeholder": "123,456.78"},"Type": "Response","Id": "Q3_2","InputType": "Text","Label": "<span style=\"color: rgb(0, 0, 0);\">Topic text_2</span>","Alignment": "Left","Placeholder": "Text","MaxLength": "255"},{"Type": "Response","Id": "Q3_3","InputType": "ZipCode","Label": "<span style=\"color: rgb(0, 0, 0);\">Topic text_3</span>","Alignment": "Left","Placeholder": "12345(-6789)"}

],"Validations": [

{"Id": "Q3_1","Type": "ReqAns","Message": "Please answer question 1 (Topic text_1) before continuing." },{"Id": "Q3_1","Type": "RealNumber","Message": "Your answer to question 1 (Topic text_1) must be a real number."},{"Id": "Q3_1","Type": "Range",

Chapter 8 - Appendix Fill in the Blank question



"Message": "Your numeric answer for question 1 (Topic text_1) does not fall within the range of -999999999999999 to 999999999999999.","Setting": "-999999999999999:999999999999999"},"Id": "Q3_2","Type": "MinLen","Message": "Your answer is shorter than the minimum allowed length of 20 characters.","Setting": "20"},{"Id": "Q3_2","Type": "ValidCharacters","Message": "Your answer of %2 for question 1 (Topic text_2) may only contain the following characters A,B.","Setting": "A,B"},{"Id": "Q3_2","Type": "TextMask","Message": "Your answer to question 1 (Topic text_2) must be in the following format XX-XXX.","Setting": "XX-XXX"},{"Id": "Q3_3","Type": "ZipCode","Message": "Your answer to question 1 (Topic text_3) must be a valid ZIP Code."}

]}]

Chapter 8 - Appendix Short Answer question



Short Answer question"Elements": [

{"Id": "Q15","Type": "ShortAnswer","Heading": "Short Answer question heading","Body": "Question text","Instructions": "Question Instructions","Responses": [

{"Type": "Response","Id": "Q15_1","InputType": "WholeNumber","Alignment": "Right","UseSlider": true,"SliderStep": 1.0}

],"Validations": [

{"Id": "Q15_1","Type": "ReqAns","Message": "Please answer question Short Answer question heading before continuing."},{"Id": "Q15_1","Type": "WholeNumber","Message": "Your answer to question Short Answer question heading must be a whole number."},{"Id": "Q15_1","Type": "Range","Message": "Your numeric answer for question Short Answer question heading does not fall within the range of -2147483648 to 2147483647.","Setting": "-2147483648:2147483647"},{"Id": "Q15_1","Type": "ValidCharacters","Message": "Your answer of %2 for question Short Answer question heading may only contain the following characters A-Z.","Setting": "A-Z"}

]}

Chapter 8 - Appendix Hidden questions (with Preselected option)



Hidden questions (with Preselected option)"Elements": [

{"Id": "Q1","Type": "Hidden","Fields": [

{"Id": "Q1_1","Value": "Answer"}

]},{

"Id": "Q2","Type": "Hidden","Fields": [{

"Id": "Q2","Value": "1"}

]}]

Chapter 8 - Appendix Validations for Matrix question



Validations for Matrix question

Type Description Setting

All sides

"ReqAns" If the Answer Required option is selected

—

Essay side

"CharactersMaxLength" If the Enable Characters Limitation is option is selected.

Maximum number of chracters allowed for the answer: "50"

Short Answer side

"MinLen" If minimum length of input characters is specified in the Minimum Length field.

Minimum number of input charatcters: "3"

"ValidCharacters" Valid characters that the topic answer should contain specified in the Valid Characters field.

Specified valid characters: "ABC"

"TextMask" Format of the topic answer specified in the Text Mask field.

Specified text mask: "XX-XXX"

"EmailAddress" Email Address input type valdation.

—

"WholeNumber" Whole Number input type valdation.

—

"RealNumber" Real Number input type valdation.

—

"Range" Range for numeric input types.

Range: "1:10"

"ReqSum" Topic responses required total.

Number of total: "100"

"Date" Dates input type validation.

—

"SocialSecurityNumber" Social Security Number input type validation.

—

Chapter 8 - Appendix Validations for Matrix question



"USCAPhone" US and Canadian Phone Number input type validation.

—

"InternationalPhone" International Phone Number input type validation.

—

"ZipCode" Zip Code input type validation.

—

"Zip4Code" Zip+4 code input type validation.

—

"CACode" Canadian Postal Code input type validation.

—

"USCACode" US and Canadian Postal Code input type validation.

—

Choose One Side

"ReqRnk" Unique answer for each topic.

—

Type Description Setting

Chapter 8 - Appendix Input types for Matrix Short Answer side



Input types for Matrix Short Answer side

Type Placeholder Description

Text

Text Text Text

Password Text Password

EmailAddress [email protected] Email address

Numbers

WholeNumber 123, 456 Whole number

RealNumber 123, 456.78 Real number

Dates

Date mm/dd/yy Date

ID and Phone Numbers

SocialSecurityNumber 123-45-6789 Social Security Number

USCAPhone Text U.S. and Canadian Phone Number

InternationalPhone Text International Phone Number

Postal Codes

ZipCode 12345(-6789) Zip Code

Zip4Code 12345-6789 Zip+4 Code

CACode Text Canadian Postal Code

USCACode Text U.S. and Canadian Postal Code

I n d e x

AAddCaseComment . . . . . . . . . . . . . . . . 164AddCaseCommentEx . . . . . . . . . . . . . . . 165AddPanelFilter . . . . . . . . . . . . . . . . . . 119AddPanelist . . . . . . . . . . . . . . . . . . . . 109AddResponse . . . . . . . . . . . . . . . . . . . 56AddUser . . . . . . . . . . . . . . . . . . . . . 169AddUserToWorkgroup. . . . . . . . . . . . . . . 190AuthorizeMultiplePanelistsForSurvey . . . . . . . 63AuthorizePanelistForSurvey . . . . . . . . . . . . 64AuthorizeParticipantForSMSSurvey . . . . . . . . 66AuthorizeParticipantForSurvey . . . . . . . . . . 65

BBulkAuthorizeParticipants . . . . . . . . . . . . . 138BulkChangeResponses . . . . . . . . . . . . . . 144BulkClearResponses . . . . . . . . . . . . . . . 150BulkGetPreloadData . . . . . . . . . . . . . . . 146BulkImportPanelists . . . . . . . . . . . . . . . 135BulkImportResponses. . . . . . . . . . . . . . . 141BulkSetParticipantInformation . . . . . . . . . . 149BulkSetPreloadData. . . . . . . . . . . . . . . . 147

CChangeMultipleResponses . . . . . . . . . . . . 55ChangeResponse . . . . . . . . . . . . . . . . . 54ChangeUserPassword . . . . . . . . . . . . . . . 177ClearResponse . . . . . . . . . . . . . . . . . . 60CloneReport . . . . . . . . . . . . . . . . . . . 198CreateCase . . . . . . . . . . . . . . . . . . . . 152CreateCaseEx. . . . . . . . . . . . . . . . . . . 153CreatePanelProfile . . . . . . . . . . . . . . . . 23CreateSharedReport . . . . . . . . . . . . . . . 199CreateSurveyProject . . . . . . . . . . . . . . . 22

DDeleteCases . . . . . . . . . . . . . . . . . . . 168DeleteMemorizedReport . . . . . . . . . . . . . 197DeleteParticipant . . . . . . . . . . . . . . . . . 59DeleteProject . . . . . . . . . . . . . . . . . . . 46DeleteUser . . . . . . . . . . . . . . . . . . . . 170DeleteUserFromWorkgroup . . . . . . . . . . . . 191

EEditCase . . . . . . . . . . . . . . . . . . . . . 154EditCaseEx . . . . . . . . . . . . . . . . . . . . 156EmailLiveResultsReport . . . . . . . . . . . . . . 94EmailResultsReport . . . . . . . . . . . . . . . . 95EmailResultsReportToRespondent . . . . . . . . 96EvaluateSavedPanelFilter . . . . . . . . . . . . . 127EvaluateSimplePanelFilter . . . . . . . . . . . . 128EvaluateTriggers . . . . . . . . . . . . . . . . . 108EvaluateXmlPanelFilter . . . . . . . . . . . . . . 129

FFindMatchingCases . . . . . . . . . . . . . . . 151FindPanelist . . . . . . . . . . . . . . . . . . . 113FindPanelistRecord . . . . . . . . . . . . . . . . 81FindPanelistsLike . . . . . . . . . . . . . . . . 114FindPanelistsRecord . . . . . . . . . . . . . . . . 82FindParticipantRecord . . . . . . . . . . . . . . . 83FindParticipantsRecord . . . . . . . . . . . . . . 84FindSMSParticipantRecord . . . . . . . . . . . . . 85

GGetAuthorizedParticipantCount . . . . . . . . . . 67GetCampaignHistory . . . . . . . . . . . . . . . 93GetCaseDetail . . . . . . . . . . . . . . . . . . 161GetCases . . . . . . . . . . . . . . . . . . . . 158GetColumnList. . . . . . . . . . . . . . . . . . . 36GetCommonSurveyList . . . . . . . . . . . . . . 20GetCustomPropertiesForSurveys . . . . . . . . . 31GetDataMap . . . . . . . . . . . . . . . . . . . . 33GetExportDataMap . . . . . . . . . . . . . . . . 34GetFrequencyInformation . . . . . . . . . . . . . 61GetInvitationTemplate. . . . . . . . . . . . . . . 87GetInvitationText . . . . . . . . . . . . . . . . . 86GetMemorizedReportFilter . . . . . . . . . . . . 202GetMemorizedReports . . . . . . . . . . . . . . 196GetMemorizedReportSharing . . . . . . . . . . 200GetOrganizationHierarchy . . . . . . . . . . . . 185GetPanelFilter . . . . . . . . . . . . . . . . . . 122GetPanelFilterCount . . . . . . . . . . . . . . . 120GetPanelFilterList . . . . . . . . . . . . . . . . 121GetPanelistActions. . . . . . . . . . . . . . . . 118GetPanelistCount . . . . . . . . . . . . . . . . 112GetPanelistData . . . . . . . . . . . . . . . . . 116GetPanelistInformation . . . . . . . . . . . . . 117GetPanelistList . . . . . . . . . . . . . . . . . 115GetParticipantData . . . . . . . . . . . . . . . . 68GetParticipantDataEx . . . . . . . . . . . . . . . 70GetParticipantDataFiltered. . . . . . . . . . . . . 74GetParticipantDataPaged . . . . . . . . . . . . . 72GetParticipantInformation . . . . . . . . . . . . . 79GetPreloadData . . . . . . . . . . . . . . . . . . 57GetProfileInformation . . . . . . . . . . . . . . 130GetProfileList . . . . . . . . . . . . . . . . . . . 21GetProjectInformation . . . . . . . . . . . . . . . 44GetPublishedQuestionnaire . . . . . . . . . . . . 25GetQuestionnaire . . . . . . . . . . . . . . . . . 24GetQuestionnaireVersions . . . . . . . . . . . . . 27GetReportDataMap . . . . . . . . . . . . . . . . 35GetReportingUsers . . . . . . . . . . . . . . . 204GetResponse . . . . . . . . . . . . . . . . . . . 53GetResponseCount . . . . . . . . . . . . . . . . 47GetStatistics. . . . . . . . . . . . . . . . . . . . 62GetSurveyCustomProperties. . . . . . . . . . . . 30GetSurveyData . . . . . . . . . . . . . . . . . . 48GetSurveyDataEx . . . . . . . . . . . . . . . . . 49GetSurveyDataPaged . . . . . . . . . . . . . . . 51GetSurveyEventHandler . . . . . . . . . . . . . 103

I n d e x

Index

Index



GetSurveyFieldInformation . . . . . . . . . . . . 39GetSurveyInformation . . . . . . . . . . . . . . 37GetSurveyList. . . . . . . . . . . . . . . . . . . 19GetSurveysForPanelist . . . . . . . . . . . . . . 132GetSurveyStatusForPanelist . . . . . . . . . . . 133GetSurveyTranslations . . . . . . . . . . . . . . 105GetUnsubscribedStatus . . . . . . . . . . . . . . 97GetUserData . . . . . . . . . . . . . . . . . . . 171GetUserInfoByEmail . . . . . . . . . . . . . . . 178GetUserInfoByExternalId . . . . . . . . . . . . . 180GetUserInfoByUsername . . . . . . . . 183, 185, 186GetUserInformation. . . . . . . . . . . . . . . . 173GetWorkgroupList . . . . . . . . . . . . . . . . 187GetWorkgroupRole . . . . . . . . . . . . . . . . 193GetWorkgroupRoleList . . . . . . . . . . . . . . 192GetWorkgroupUnsubscribes . . . . . . . . . . . 189GetWorkgroupUsers . . . . . . . . . . . . . . . 188

IImportOrganizationHierarchy . . . . . . . . . . . 186

LLogin . . . . . . . . . . . . . . . . . . . . . . . 14Logout . . . . . . . . . . . . . . . . . . . . . . 15

PPing. . . . . . . . . . . . . . . . . . . . . . . . 13

RRemovePanelFilter . . . . . . . . . . . . . . . . 126RemovePanelist. . . . . . . . . . . . . . . . . . 110RepublishProject . . . . . . . . . . . . . . . . . 42ResetUserPassword . . . . . . . . . . . . . . . . 176RevertQuestionnaire . . . . . . . . . . . . . . . 29

SSendInvitations . . . . . . . . . . . . . . . . . . 92

SendInvitationsEx . . . . . . . . . . . . . . . . . 91SendPortalEmails . . . . . . . . . . . . . . . . 134SetCaseOwner. . . . . . . . . . . . . . . . . . 162SetCaseOwnerEx . . . . . . . . . . . . . . . . 163SetCasePriority . . . . . . . . . . . . . . . . . 159SetCasePriorityEx . . . . . . . . . . . . . . . . 160SetCaseStatus. . . . . . . . . . . . . . . . . . 166SetCaseStatusEx . . . . . . . . . . . . . . . . 167SetEndPageURL . . . . . . . . . . . . . . . . . . 43SetExternalId . . . . . . . . . . . . . . . . . . 111SetInvitationStatus . . . . . . . . . . . . . . . . 90SetInvitationTemplate . . . . . . . . . . . . . . . 88SetMemorizedReportFilter . . . . . . . . . . . . 203SetMemorizedReportSharing . . . . . . . . . . 201SetMultipleInvitationStatus . . . . . . . . . . . . 89SetPanelFilter . . . . . . . . . . . . . . . . . . 124SetParticipantInformation . . . . . . . . . . . . . 77SetPreloadData . . . . . . . . . . . . . . . . . . 58SetProfileInformation . . . . . . . . . . . . . . 131SetProjectInformation . . . . . . . . . . . . . . . 45SetQuestionnaire . . . . . . . . . . . . . . . . . 26SetSurveyCustomProperties . . . . . . . . . . . . 32SetSurveyEventHandler . . . . . . . . . . . . . 104SetSurveyTranslations . . . . . . . . . . . . . 106SetUserInfoByExternalId . . . . . . . . . . . . 182SetUserInformation . . . . . . . . . . . . . . . 175SetUserWorkgroup . . . . . . . . . . . . . . . 195SetWorkgroupRole . . . . . . . . . . . . . . . 194SharePanelFilter . . . . . . . . . . . . . . . . . 125

UUnsubscribeListAdd . . . . . . . . . . . . . . . . 98UnsubscribeListRemove . . . . . . . . . . . . . . 99UpdateBorrowedQuestions . . . . . . . . . . . 100UpdateBorrowedQuestionsForRespondent . . . . 101

VValidateSingleResponse . . . . . . . . . . . . . 102

© 2016 Verint Systems Inc. All Rights Reserved Worldwide. Confidential and Proprietary Information of Verint Systems Inc.

The contents of this material are confidential and proprietary to Verint Systems Inc. and may not be reproduced, published, or disclosed to others without express authorization of Verint Systems Inc.

Verint Global Headquarters330 South Service RoadMelville, NY 11747 USA

[email protected]

www.verint.com

web services technical guide 15.1 fp3...verint systems inc. does not warrant, guarantee or make any...

Documents