Web Services Technical Guide 15.1 FP3...Verint Systems Inc. does not warrant, guarantee or make any...
Transcript of 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
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
Confidential and Proprietary Information of Verint Systems Inc.
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
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 7
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 8
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 9
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 10
Confidential and Proprietary Information of Verint Systems Inc.
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 Technical Guide 11
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 12
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 13
Confidential and Proprietary Information of Verint Systems Inc.
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
Chapter 3 - Web Services API-Getting Started Confirming and Validating your Web Service Account
EFM Web Services Technical Guide 14
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
userName (string) EFM username password (string) Unencrypted user password
Return Value & Description:
string Returns:Empty string or CSRF token (if enabled) for success
Permissions: None
Exceptions: SOAP exception on failure and locking out account
Chapter 3 - Web Services API-Getting Started Confirming and Validating your Web Service Account
EFM Web Services Technical Guide 15
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
None
Return Value & Description:
None
Permissions: None
Exceptions: None
Chapter 3 - Web Services API-Getting Started Using CSRF Token in Web Service calls
EFM Web Services Technical Guide 16
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 17
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 19
Confidential and Proprietary Information of Verint Systems Inc.
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
Parameters:(name, type, description)
sharingType (int)0 = login user's surveys1 = other people's surveys visible to the user2 = both
Return Value & Description:
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
EFM Web Services Technical Guide 20
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
initialSource (string)The initial source string must exactly match what is stored in the system.
Return Value & Description:
XMLNodeReturns: 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
EFM Web Services Technical Guide 21
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetProfileList
Description: Returns a list of EFM profiles, in an XML representation.
Parameters:(name, type, description)
None
Return Value & Description:
XMLNode Returns:XML giving information about each profile, as follows:
<Projects><Project id="ID">
<Name>PROFILE NAME</Name></Project>
</Projects>
Permissions: View Panel Profiles
Exceptions: None
Chapter 4 - Web Services Data Project Creation
EFM Web Services Technical Guide 22
Confidential and Proprietary Information of Verint Systems Inc.
Project Creation
Method Call: CreateSurveyProject
Description: Create a new blank survey with specified name and description.
Parameters:(name, type, 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
Return Value & Description:
intReturns: The new project id
Permissions: Create Surveys
Exceptions: None
Chapter 4 - Web Services Data Project Creation
EFM Web Services Technical Guide 23
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: CreatePanelProfile
Description: Create a new blank panel profile with specified name and description.
Parameters:(name, type, description)
profileName (string) Short name of the profile (max 150 characters)
description (string) Description of the profile (max 255 characters)
Return Value & Description:
intReturns: The new project id
Permissions: Create Panel Profiles
Exceptions: None
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 24
Confidential and Proprietary Information of Verint Systems Inc.
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
Return Value & Description:
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.
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 25
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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.
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 26
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID surveyXml (string) An XML representation of
the questionnaire, as returned by GetQuestionnaire
Return Value & Description:
intReturns: The version number, which may be passed to RevertQuestionnaire.
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 27
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetQuestionnaireVersions
Description: Get the current list of versions of this survey
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description
XMLNodeReturns: XML specifying the versions, as follows:
<Versions><Version versionid="ID" change="CHANGETYPE" date="DATE/TIME OF CHANGE" userid="USER"/>
</Versions>
Permissions: View Surveys
Exceptions: None
Notes: CHANGETYPE ValuesThese are the values currently for CHANGETYPE.CreatedGeneralWordProcessorQuestionLogicQuestionAppearanceTablePropertiesWebFormattingSurveyPropertiesScoringValidationMessagesWebAccessibilityTranslationEndPagesAdvancedBranchingChoiceConditionsSpellCheckLibraryQuestionPageElementMovedPageElementRemovedQuestionUpdated
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 28
Confidential and Proprietary Information of Verint Systems Inc.
Notes: SectionUpdatedTextBlockUpdatedCommentUpdatedQuestionAddedSectionAddedCommentAddedPageBreakAddedTextBlockAddedPublishRollBackUpgradeQuotaPageRotationCodeBlockUpdatedCodeBlockAddedSurveyGlossary EmailTriggerActivatePageBreakDeleted
Method Call: GetQuestionnaireVersions
Chapter 4 - Web Services Data Questionnaire Access
EFM Web Services Technical Guide 29
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: RevertQuestionnaire
Description: Revert to an earlier version of the questionnaire
Parameters:(name, type, description)
projectId (int) A project ID versionId (int) ID of a version to return to; see
also GetQuestionnaireVersions
Return Value & Description:
N/A
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Custom Properties
EFM Web Services Technical Guide 30
Confidential and Proprietary Information of Verint Systems Inc.
Custom Properties
Method Call: GetSurveyCustomProperties
Description: Get the custom properties for a question, or for the entire survey.
Parameters:(name, type, description)
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
Return Value & Description:
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>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Custom Properties
EFM Web Services Technical Guide 31
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetCustomPropertiesForSurveys
Description: Get the custom properties for a list of surveys.
Parameters:(name, type, description)
projectIds (int[]) An array of project IDs targetPropertyName (string) If not null, we will
only return projects with a custom property with this name
Return Value & Description:
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>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Custom Properties
EFM Web Services Technical Guide 32
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetSurveyCustomProperties
Description: Set the custom properties for a question, or for the entire survey.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 33
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 34
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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 QUESTION EXPORT VALUE" />
</FieldMap></DataMap>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 35
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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).
<DataMap sourceType="0"><FieldMap sourceField="DBHEADING" destinationField="DBHEADING">
<ValueMap sourceValue="CHOICE QUESTION VALUE" destinationValue="CHOICE QUESTION REPORT VALUE" />
</FieldMap></DataMap>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 36
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
XMLNodeReturns: XML containing the column names, in this format:
<Columns><Field id="DBHEADING" type="TYPE"/>
</Columns>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 37
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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>
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 38
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
</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>
Permissions: View Surveys
Exceptions: None
Method Call: GetSurveyInformation
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 39
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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).
Return Value & Description:
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-->
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 40
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<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>
</SurveyField><SurveyField>
<Heading><Text type="plain">Essay Question Type</Text>
</Heading><Body>
<Text>Essay Question text</Text></Body>
</SurveyField><SurveyField>
<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>
Method Call: GetSurveyFieldInformation
Chapter 4 - Web Services Data Column Information
EFM Web Services Technical Guide 41
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<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>
Permissions: View Surveys
Exceptions: None
Method Call: GetSurveyFieldInformation
Chapter 4 - Web Services Data Survey Life Cycle
EFM Web Services Technical Guide 42
Confidential and Proprietary Information of Verint Systems Inc.
Survey Life Cycle
Method Call: RepublishProject
Description: Open, republish, or close the project.
Parameters:(name, type, description)
projectId (int) A project ID publishMode (int)
0 = testing1 = open2 = closed
Return Value & Description:
N/A
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Survey Information
EFM Web Services Technical Guide 43
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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)
Return Value & Description:
N/A
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Survey Information
EFM Web Services Technical Guide 44
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetProjectInformation
Description: Get basic information about a project.
NOTE The URL is provided for Open Participation surveys only.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Survey Information
EFM Web Services Technical Guide 45
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Edit Surveys
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
EFM Web Services Technical Guide 46
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
N/A
Permissions: Delete Surveys
Exceptions: None
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 47
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID completedOnly (bool) If true, return completed
responses only; otherwise, return all started responses.
Return Value & Description:
intReturns: The number of responses of the specified type.
Permissions: View Results
Exceptions: None
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 48
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
DataSetReturns: A DataSet:http://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.
Permissions: View Results
Exceptions: None
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 49
Confidential and Proprietary Information of Verint Systems Inc.
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).
Parameters:(name, type, description)
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.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 50
Confidential and Proprietary Information of Verint Systems Inc.
WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.
Return Value & Description:
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.
Permissions: View Results
Exceptions: None
Method Call: GetSurveyDataEx
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 51
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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 = != < > <= >= 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.
WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 52
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
DataSetReturns: A DataSethttp://msdn.microsoft.com/en-us/library/8bw9ksd6.aspx.
NOTE Started, Completed, and Modified are valid database columns.
Permissions: View Results
Exceptions: None
Method Call: GetSurveyDataPaged
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 53
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetResponse
Description: Get the answers for one response.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) The internal ID of this response
can be found with GetSurveyData(Ex).
Return Value & Description:
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>
Permissions: View Results
Exceptions: None
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 54
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: ChangeResponse
Description: For the specified record - change a single data point.
Parameters:(name, type, description)
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.
Return Value & Description:
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.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 55
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: ChangeMultipleResponses
Description: Change one or more respondent records. Only the values to be changed should be specified.
Parameters:(name, type, description)
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>
Return Value & Description:
stringReturns: Blank if successful; otherwise an exception message.
Permissions: Edit Results
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 56
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: AddResponse
Description: Add a new response to the survey.
Parameters:(name, type, description)
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>
Return Value & Description:
longReturns: New Record ID of the added response
Permissions: Edit Results
Exceptions: This Web Service Method is not available for profile surveys.
This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 57
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetPreloadData
Description: Get the preload data for a participant.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) The record ID of this participant
can be found with GetParticipantData(Ex).
Return Value & Description:
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
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 58
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Edit Results
Exceptions: This Web Service Method is not available for data sets.
Note The <Row> node will accept either id = (as returned by ChangeMultipleResponses) or recordid = for the record ID.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 59
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) The record ID of this participant;
can be found with GetParticipantData(Ex).
Return Value & Description:
N/A
Permissions: Delete Participants
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Survey Management
EFM Web Services Technical Guide 60
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) The internal ID of this response
can be found with GetSurveyData(Ex).
Return Value & Description:
N/A
Permissions: Delete Results
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Aggregate Data
EFM Web Services Technical Guide 61
Confidential and Proprietary Information of Verint Systems Inc.
Aggregate Data
Method Call: GetFrequencyInformation
Description: Get frequency data for a question.
NOTE Currently not supported for matrix questions.
Parameters:(name, type, description)
projectId (int) A project ID columnName (string) The database name for a
question can be fetched with GetColumnList.
Return Value & Description:
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
Permissions: View Results
Exceptions: None
Chapter 4 - Web Services Data Aggregate Data
EFM Web Services Technical Guide 62
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetStatistics
Description: Get statistics data for a question.
Parameters:(name, type, description)
projectId (int) A project ID columnName (string) The database name for a
question can be fetched with GetColumnList.
Return Value & Description:
XMLNodeReturns: An XML representation of the statistics, as follows:
<Question name="QUESTION HEADING"><Statistics column="DBHEADING"><Item name="STATISTIC">VALUE</Item></Statistics>
</Question>
Permissions: View Results
Exceptions: None
Chapter 4 - Web Services Data Add Participants
EFM Web Services Technical Guide 63
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID panelistIdList (int[]) An array of panelist IDs
Return Value & Description:
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.
Chapter 4 - Web Services Data Add Participants
EFM Web Services Technical Guide 64
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Parameters:(name, type, description)
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.
userkey3 (string) A key to allow the same person to be invited multiple times; pass null if not used.
Return Value & Description:
longReturns: The new recordId
Permissions: Import Panelists
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.
Chapter 4 - Web Services Data Add Participants
EFM Web Services Technical Guide 65
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID email (string) The participant's email address;
optional for Access List surveys; max 255 characters.
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.
userkey3 (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
NOTE For the Require a Passcode distribution method, a participant must specify at least one key. The email, key combination must be unique.
Return Value & Description:
longReturns: The new recordId
Permissions: Import Panelists
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Add Participants
EFM Web Services Technical Guide 66
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: AuthorizeParticipantForSMSSurvey
Description: Adds a participant to an SMS survey. An exception will be thrown if the participant already exists.
Parameters:(name, type, description)
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.
userkey2 (string) A key to allow the same person to be invited multiple times; pass null if not used.
userkey3 (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
Return Value & Description:
longReturns: The new recordId
Permissions: Import Panelists
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 67
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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.
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 68
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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"
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 69
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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"
Permissions: View Participants
Exceptions: None
Method Call: GetParticipantData
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 70
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
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"
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 71
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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>
NOTE For SMS surveys, email= is replaced with: phone_number="123"
Permissions: View Participants
Exceptions: None
Method Call: GetParticipantDataEx
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 72
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetParticipantDataPaged
Description: Returns information about participants for this survey.
NOTE Maximum of 10,000 records returned per call. See also: GetParticipantInformation.
Parameters:(name, type, description)
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.
Return Value & Description:
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"
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 73
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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
NOTE For SMS surveys, email= is replaced with: phone_number="123"
Permissions: View Participants
Exceptions: None
Method Call: GetParticipantDataPaged
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 74
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetParticipantDataFiltered
Description: Returns information about filtered participants for this survey.
NOTE Maximum of 10,000 records returned per call. See also: GetParticipantInformation.
Parameters:(name, type, description)
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 =, !=, <, >, <=,
>=
WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.
Return Value & Description:
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"
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 75
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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
NOTE For SMS surveys, email= is replaced with: phone_number="123"
Method Call: GetParticipantDataFiltered
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 76
Confidential and Proprietary Information of Verint Systems Inc.
Permissions: View Participants
Exceptions: SOAP exception for invalid project IDs, start time, or filter XML.
Method Call: GetParticipantDataFiltered
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 77
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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 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
Return Value & Description:
N/A
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 78
Confidential and Proprietary Information of Verint Systems Inc.
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
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 79
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetParticipantInformation
Description: Returns information about just one participant.See also: GetParticipantData.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) Record ID for the participant
Return Value & Description:
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
USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/></Participants>
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 80
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
NOTE For SMS surveys, email= is replaced with: phone_number="123"
Permissions: View Participants
Exceptions: None
Method Call: GetParticipantInformation
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 81
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: FindPanelistRecord
Description: Finds a respondent record ID given a panelist ID (and user keys, if necessary).
Parameters:(name, type, description)
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
Return Value & Description:
longReturns: The recordId for the given panelist, or -1 if not found.
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 82
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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>
Return Value & Description:
Returns an XML representation of found participants:, as follows:
<Result><!-- Participant found and id returned --><Participant id="123456" /><!-- Error Cases --><!-- Lookup fails. No id returned just error
messages --><Error>Incorrect data: Exception.Message</
Error><!-- Missing required field(s) --><Error>Missing field: ID</Error></Result>
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 83
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: FindParticipantRecord
Description: Find a participant using an email address and user keys (if user keys are used in your survey).
Parameters:(name, type, description)
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
Return Value & Description:
longReturns: The recordId for the given participant or -1 if not found.
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 84
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: FindParticipantsRecord
Description: Find participants using an email address and user keys (if user keys are used in your survey).
Parameters:(name, type, description)
projectId (int) A project ID participantsXml (string) An XML representation
of participants to be found, in this format:<Participants>
<Participant><!-- PhoneNumber is used only for SMS survey type instead of EmailAddress -->
<EmailAddress>[email protected]</EmailAddress><PhoneNumber>123456</PhoneNumber><UserKey1> optional </UserKey1><UserKey2> optional </UserKey2><UserKey3> optional </UserKey3>
</Participant></Participants>
Return Value & Description:
Returns an XML representation of found participants, as follows:
<Result><!-- Participant found and id returned --><Participant id="123456" /><!-- Participant not found -->< Participant id="-1" /><!-- Error Case --><!-- Missing required field(s) --><Error>Missing field: EmailAddress</Error></Result>
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data View Participant Information
EFM Web Services Technical Guide 85
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: FindSMSParticipantRecord
Description: Find a participant given a phone number (and user keys, if necessary).
Parameters:(name, type, description)
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.
Return Value & Description:
LongThe recordId for the given participant, or -1 if not found.
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 86
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID recordId (long) The internal ID of this
participant. invitationType (int)
0 = initial invite1 = 1st reminder etc.
Return Value & Description:
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
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 87
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID invitationType (int)
0 = initial invite1 = 1st reminder etc.
Return Value & Description:
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>
Permissions: View Invitations
Exceptions: None
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 88
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: View Invitations
Exceptions: None
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 89
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
N/A
Permissions: Edit Participants
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 90
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
N/A
Permissions: Edit Participants
Exceptions: None
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 91
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Send Invitations
Exceptions: This Web Service Method is not available for data sets and SMS surveys.
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 92
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SendInvitations
Description: Send out invitations of the given type.
Parameters:(name, type, description)
projectId (int) The project ID. invitationType (int)
0 = initial invite1 = 1st reminder etc.
Return Value & Description:
N/A
Permissions: Send Invitations
Exceptions: This Web Service Method is not available for data sets and SMS surveys
Chapter 4 - Web Services Data Invitations
EFM Web Services Technical Guide 93
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetCampaignHistory
Description: For the specified survey participant return an XML structure detailing the status of the emails sent to them.
Parameters:(name, type, description)
projectId (int) A project ID for an email based survey.
participantId (long) The internal ID of this participant
Return Value & Description:
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).
Permissions: View Participants
Exceptions: None
NOTE For more details on MAILING STATUS, see Campaign Statuses, page 312.
Chapter 4 - Web Services Data Respondent Reports
EFM Web Services Technical Guide 94
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID fromAddress (string) Valid Sender Address toAddress (string) Valid Recipient Address messageSubject (string) Email Subject messageBody (string) Email Body
Return Value & Description:
N/A
Permissions: View Results and Edit Panel Profiles
Exceptions: This Web Service Method is not available for Open Participation and SMS surveys
Chapter 4 - Web Services Data Respondent Reports
EFM Web Services Technical Guide 95
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
N/A
Permissions: View Results and Edit Panel Profiles
Exceptions: This Web Service Method is not available for SMS surveys
Chapter 4 - Web Services Data Respondent Reports
EFM Web Services Technical Guide 96
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
N/A
Permissions: View Results and Edit Panel Profiles
Exceptions: This Web Service Method is not available for SMS surveys
Chapter 4 - Web Services Data Unsubscribed Emails
EFM Web Services Technical Guide 97
Confidential and Proprietary Information of Verint Systems Inc.
Unsubscribed Emails
Method Call: GetUnsubscribedStatus
Description: Return whether the specified email address is on the unsubscribed list or not.
Parameters:(name, type, description)
emailAddress (string) Email address to query the unsubscribe list
Return Value & Description:
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
Chapter 4 - Web Services Data Unsubscribed Emails
EFM Web Services Technical Guide 98
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
emailAddresses (string[]) List of Email addresses to add to the unsubscribe list. Invalid or duplicate addresses will be ignored.
Return Value & Description:
N/A
Permissions: Edit Unsubscribes
Exceptions: None
Chapter 4 - Web Services Data Unsubscribed Emails
EFM Web Services Technical Guide 99
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
mailAddresses (string[]) List of email addresses. Invalid addresses or addresses not already in the list will be ignored.
Return Value & Description:
N/A
Permissions: Edit Unsubscribes
Exceptions: None
Chapter 4 - Web Services Data Update Borrowed Questions
EFM Web Services Technical Guide 100
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
N/A
Permissions: View Results and Edit Panel Profiles
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Update Borrowed Questions
EFM Web Services Technical Guide 101
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID recordId (Long) Record ID of a respondent to
the survey
Return Value & Description:
N/A
Permissions: View Results and Edit Panel Profiles
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Validate a Single Response
EFM Web Services Technical Guide 102
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID recordId (Long) Record ID of a respondent to
the survey
Return Value & Description:
List of cleared fields:<Result>
<f id="QUESTION DB HEADING"></f></Result></returns>
Permissions: Edit Results
Exceptions: SOAP exceptions for invalid access and invalid parameters.This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Validate a Single Response
EFM Web Services Technical Guide 103
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetSurveyEventHandler
Description: Get survey event handler properties for given project id.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
<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>
Permissions: View Surveys
Exceptions: None
Chapter 4 - Web Services Data Validate a Single Response
EFM Web Services Technical Guide 104
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID eventHandlerProperties (string) String of XML,
in the same format returned by GetSurveyEventHandler
Return Value & Description:
N/A
Permissions: Edit Surveys
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Translations
EFM Web Services Technical Guide 105
Confidential and Proprietary Information of Verint Systems Inc.
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)
Parameters:(name, type, description)
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.
Return Value & Description:
<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">
<body><trans-unit id="WebLabels_NextCaption" datatype="plaintext">
<source>Next</source><target>Siguiente</target>
</trans-unit></body>
</file></xliff>
Permissions: Translate Survey
Exceptions: None
Chapter 4 - Web Services Data Translations
EFM Web Services Technical Guide 106
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetSurveyTranslations
Description: Set or change the translations of survey items. Call SetSurveyTranslations with modified XML.
Parameters:(name, type, description)
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>
Chapter 4 - Web Services Data Translations
EFM Web Services Technical Guide 107
Confidential and Proprietary Information of Verint Systems Inc.
Parameters:(name, type, description)
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">
<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">
<body><trans-unit id="WebLabels_NextCaption" datatype="plaintext">
<source>Next</source><target>Siguiente</target>
</trans-unit></body>
</file></xliff>
Return Value & Description:
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
Chapter 4 - Web Services Data Translations
EFM Web Services Technical Guide 108
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: EvaluateTriggers
Description: Evaluate survey triggers for the specified responses (record IDs).
Parameters:(name, type, description)
projectId(int) - A project IDrecordIds (long[]) - Array of record IDs.
Return Value & Description:
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
EFM Web Services Technical Guide 109
Confidential and Proprietary Information of Verint Systems Inc.
Web Service paneldata.asmxThis Web Service exposes the panel system.
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.
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
Parameters:(name, type, description)
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.
Return Value & Description:
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
EFM Web Services Technical Guide 110
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: RemovePanelist
Description: Removes a panelist. This is actually a soft delete; the panelist is simply marked as deleted.
Parameters:(name, type, description)
panelistID (int) The panelist ID
Return Value & Description:
N/A
Permissions: Delete Members
Exceptions: None
Chapter 4 - Web Services Data Add/Modify/Delete Panelists
EFM Web Services Technical Guide 111
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Parameters:(name, type, description)
panelistId (int) The panelist ID key (string) The new external ID
Return Value & Description:
N/A
Permissions: Edit Members
Exceptions: None
Chapter 4 - Web Services Data Find Panelists
EFM Web Services Technical Guide 112
Confidential and Proprietary Information of Verint Systems Inc.
Find Panelists
Method Call: GetPanelistCount
Description: Return the number of defined panelists.
Parameters:(name, type, description)
status (int)-1=all, 0=active, 1=suspended, 2=deleted
Return Value & Description:
intReturns: The count
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Find Panelists
EFM Web Services Technical Guide 113
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: FindPanelist
Description: Find the panel ID of the panelist with the given external ID.
Parameters:(name, type, description)
key (string) The external ID to search for
Return Value & Description:
intReturns: The internal panelist ID, if found, otherwise 0
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Find Panelists
EFM Web Services Technical Guide 114
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
name (string) The target name
Return Value & Description:
int[]Returns: An array of integer panelist IDs
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Find Panelists
EFM Web Services Technical Guide 115
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
sortColumn (int)0 = no sort 1 = panelistID2 = email3 = first name4 = last name
Return Value & Description:
int[]Returns: An array of integer panelist IDs
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Find Panelists
EFM Web Services Technical Guide 116
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetPanelistData
Description: Get basic information about a set of panelists.
Parameters:(name, type, description)
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.
Return Value & Description:
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>
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data
EFM Web Services Technical Guide 117
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetPanelistInformation
Description: Returns the information stored in the master panel (that is, the basic information profile) for the specified panelist.
Parameters:(name, type, description)
panelistID (int) The panelist ID
Return Value & Description:
XmlNodeReturns: An XML representation of the data, in the same format as GetPanelistData
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Audit Panelists Actions
EFM Web Services Technical Guide 118
Confidential and Proprietary Information of Verint Systems Inc.
Audit Panelists Actions
Method Call: GetPanelistActions
Description: Return all the actions undertaken by this panelist for this project.
Parameters:(name, type, description)
panelistID (int) The panelist ID projectID (int) The project ID
Return Value & Description:
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
EFM Web Services Technical Guide 119
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
filterName (string) The name of the saved panel filter.
filterXml (string) The filter in the same format returned by GetPanelFilter.
Return Value & Description:
filterId(int)
Permissions: Edit Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 120
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
status (int)0 = shared filters1 = private filters
Return Value & Description:
intReturns: The number of saved panel filters
Permissions: View Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 121
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
status (int)0 = shared filters1 = private filters
Return Value & Description:
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>
Permissions: View Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 122
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetPanelFilter
Description: Returns a representation of a particular panel filter.
Parameters:(name, type, description)
filterid (int) The ID of the saved panel filter
Return Value & Description:
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.
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 123
Confidential and Proprietary Information of Verint Systems Inc.
Permissions: View Panel Filters
Exceptions: None
Method Call: GetPanelFilter
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 124
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
filterid (int) The ID of the saved panel filter. filterXml (string) The filter in the same format
returned by GetPanelFilter.
Return Value & Description:
N/A
Permissions: Edit Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Saved Panel Filters Query
EFM Web Services Technical Guide 125
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SharePanelFilter
Description: Set the shared/private status for a particular panel filter.
Parameters:(name, type, description)
filterid (int) The ID of the saved panel filter. share (bool) Whether the filter should be visible
to others in the workgroup
Return Value & Description:
N/A
Permissions: Edit Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Add/Remove Panel Filters
EFM Web Services Technical Guide 126
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
filterid (int) The ID of the saved panel filter
Return Value & Description:
N/A
Permissions: Delete Panel Filters
Exceptions: None
Chapter 4 - Web Services Data Evaluate Filters (Saved or Ad Hoc)
EFM Web Services Technical Guide 127
Confidential and Proprietary Information of Verint Systems Inc.
Evaluate Filters (Saved or Ad Hoc)
Method Call: EvaluateSavedPanelFilter
Description: Evaluates the given saved panel filter.
Parameters:(name, type, description)
filterid (int) The ID of the saved panel filter
Return Value & Description:
int[]Returns: An array of matching panelistIds which can be passed to GetPanelistData
Permissions: View Member Filters and View Members
Exceptions: None
Chapter 4 - Web Services Data Evaluate Filters (Saved or Ad Hoc)
EFM Web Services Technical Guide 128
Confidential and Proprietary Information of Verint Systems Inc.
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
Parameters:(name, type, description)
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
Return Value & Description:
int[]Returns: An array of matching panelistIds which can be passed to GetPanelistData
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Evaluate Filters (Saved or Ad Hoc)
EFM Web Services Technical Guide 129
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: EvaluateXmlPanelFilter
Description: Evaluate an ad hoc panel filter. (The filter is not saved in the database.)
Parameters:(name, type, description)
filterXml (string) The filter in the same format returned by GetPanelFilter
Return Value & Description:
int []Returns: An array of matching panelistIds which can be passed to GetPanelistData
Permissions: View Members
Exceptions: None
Chapter 4 - Web Services Data Profile Data
EFM Web Services Technical Guide 130
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
panelistID (int) The ID of the panelist profileID (int) The project ID of the panel profile
Return Value & Description:
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
EFM Web Services Technical Guide 131
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetProfileInformation
Description: Set column values for a particular profile for a panelist, for one or more rows.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Edit Member Profiles
Exceptions: None
Chapter 4 - Web Services Data Authorized Surveys
EFM Web Services Technical Guide 132
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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
Return Value & Description:
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
EFM Web Services Technical Guide 133
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetSurveyStatusForPanelist
Description: Returns the panelist's status in regard to the specified survey.
Parameters:(name, type, description)
projectId (int) The project ID of the survey panelistId (int) The ID of the panelist
Return Value & Description:
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
EFM Web Services Technical Guide 134
Confidential and Proprietary Information of Verint Systems Inc.
Portal Emails
Method Call: SendPortalEmails
Description: Send out the requested email to a group of panelists.
Parameters:(name, type, description)
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
Return Value & Description:
N/A
Permissions: View Members and Send Invitations
Exceptions: None
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 135
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
panelistsXml (string)<Panelists importNew="Optional: indicate that
this is an initial load of new panelists. Default being false."><Panelist id="Optional: panelist id">
<!-- Basic panelist data --><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)
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 136
Confidential and Proprietary Information of Verint Systems Inc.
Parameters:(name, type, description)
<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)<!-- VCBM Values. All optional and will only work with VCBM enabled. --><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 data --><Profile id="12345678">
<f id="Q1">Value</f></Profile>
</Panelist></Panelists>
Return Value & Description:
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 -
->
Method Call: BulkImportPanelists
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 137
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<Panelist updated="true" id="123456" /><!-- Error Cases --><!-- Basic panelist add or update fails. No id
returned just error messages --><Error>Incorrect data: Exception.Message</Error>
<!-- Missing required field(s) --><Error>Missing fields: Email, First Name, Last Name</Error>
<!-- Basic panelist add or update succeeds.One or more profile errors --></Panelist><Panelist id="123456">
<Profile id="64989878"><Error>Incorrect data: Exception.Message</Error><Error>Incorrect data: Exception.Message</Error>
</Profile></Panelist>
</Result>
Permissions: Import Panelists
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: BulkImportPanelists
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 138
Confidential and Proprietary Information of Verint Systems Inc.
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.
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 139
Confidential and Proprietary Information of Verint Systems Inc.
Parameters:(name, type, description)
projectId (int) A Project ID participantsXml (string)
<Participants><Participant>
<!-- Only one of the following four values can be passed.-->
<!-- PhoneNumber is used only for SMS survey type instead of Email -->
<Email>Email</Email><PhoneNumber>Phone number</PhoneNumber><PanelistId>Panelist Id</PanelistId><ExternalId>Panelist external Id</ExternalId>
<!-- Optional user keys to further identify a participant -->
<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>
Return Value & Description:
XmlNodeReturns an XML representation, as follows:
<!-- One Participant element for every Participant element passed in. Returned order is same as sent.
If there is an error with the participant info or the preload data the participant is not authorized to start the survey. -->
<Result><!-- Basic participant add or update
succeeds. Record Id returned. --><Participant id="12345678" url="http://example.com/se.ashx?s=ABCD1234" />
<!-- Error Cases --><!-- Basic participant add or update fails.
No id returned just error messages. --><Participant>
<Error>Incorrect data: Exception.Message</Error>
</Participant>
Method Call: BulkAuthorizeParticipants
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 140
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<!-- Basic participant update succeeds. One or more preload errors. No id returned just one or more error messages.--><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: BulkAuthorizeParticipants
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 141
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectid (int) A Project ID responseXml (string)
<Records evaluateTriggers="true|false"><Record>
<!-- Survey fields --><f id="Q1"></f>
<!-- Standard response fields --><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>
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 142
Confidential and Proprietary Information of Verint Systems Inc.
Parameters:(name, type, description)
<!-- Non Open Participation Fields --><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>
<!-- Campaign Status fields --><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>
Method Call: BulkImportResponses
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 143
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
XmlNodeReturns an XML representation, as follows:
<!-- One Record element for every Record element passed in. Returned order is same as sent. -->
<Result><Record id="123456"/>
<Trigger Description="Description1" sentEmail="True" createdCase="True"/><Trigger Description="Description2" createdCase="True"/>
</Record><Error> Incorrect data: Exception.Message</Error>
</Result>
Permissions: Edit Results
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: BulkImportResponses
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 144
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) - A project ID dataString (string) - XML for each record:
<Records><Record id="634635537507737461">
<!-- Survey fields --><f id="Q1"></f>
<!-- Standard response fields --><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
<!-- Non Open Particpation Fields --><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>
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 145
Confidential and Proprietary Information of Verint Systems Inc.
Parameters:(name, type, description)
<!-- Campaign Status fields --><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>
Return Value & Description:
XmlNodeReturns an XML representation, as follows:
<!-- One Record element for every Record element passed in. Returned order is same as sent. -->
<Result><Record id="634635537507737461"/><Error> Incorrect data: Exception.Message </Error>
</Result>
Permissions: Edit Results
Exceptions: This Web Service Method is not available for data sets.
Method Call: BulkChangeResponses
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 146
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: BulkGetPreloadData
Description: Allows you to get preload data for participants (up to 500).
Parameters:(name, type, description)
projectId(int) - A project ID recordIds (long[]) - Array of record IDs
Return Value & Description:
XmlNodeReturns an XML representation, as follows:
<PreloadData><Preload id="634665465332558180">
<f id="Q1">Value</f></Preload>
<!-- If no PreloadData --><Preload id="634665465332558181"/>
<!-- Error case --><!-- Participant not found error messages. --
><Error> Invalid record id specified: id </Error>
</PreloadData>
Permissions: View Participants
Exceptions: None
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 147
Confidential and Proprietary Information of Verint Systems Inc.
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"/>).
Parameters:(name, type, description)
projectId (int) - A project IDpreloadDataXml (string) - XML of preload data<PreloadData>
<Preload id="634665465332558180"><f id="Q1">Value</f>
</Preload><!-- Clears all preload fields -->
<Preload id="634665465332558181"/><!-- Clear Q1, set Q2 -->
<Preload id="634665465332558182"><f id="Q1" /><f id="Q2">Value</f>
</Preload></PreloadData>
Return Value & Description:
XmlNodeReturns an XML representation, as follows:
<!-- One Record element for every Record element passed in. Returned order is same as sent. -->
<Result><!-- Preload data added or updated succeeds.
Record Id returned. --><Participant id="634665465332558180" /><!-- Error Cases --><!-- One or more preload errors-->
<Participant id="634665465332558181"><Error>Incorrect data: Exception.Message</Error><Error>Field name: Q11 does not match any questions in this survey.</Error>
</Participant><!-- No record id specified error messages. -
-><Error> No record id specified. </Error>
<!-- Participant not found error messages. --><Error> Invalid record id specified: id </Error>
</Result>
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 148
Confidential and Proprietary Information of Verint Systems Inc.
Permissions: Import Participants
Exceptions: This Web Service Method is not available for data sets.
Method Call: BulkSetPreloadData
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 149
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: BulkSetParticipantInformation
Description: Allows you to change information about one or more participants.
Parameters:(name, type, description)
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
Return Value & Description:
<Result><Participant id="634665465332558181">
<Error>User with the same email and user keys already exist.</Error>
</Participant><!-- No record id specified error messages. --><Error> No record id specified. </Error><!-- Participant not found error messages. --><Error> Invalid participant id: id </Error>
</Result>
Permissions: Edit Participants
Exceptions: This Web Service Method is not available for data sets.
Chapter 4 - Web Services Data Web Service bulk.asmx
EFM Web Services Technical Guide 150
Confidential and Proprietary Information of Verint Systems Inc.
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:
XmlNodeReturns an XML representation, as follows:
<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
EFM Web Services Technical Guide 151
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
int[]Returns:Array of matching case IDs.
Permissions: View Cases or View All Cases
Exceptions: SOAP exceptions for invalid parameters specification.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 152
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: CreateCase
Description: Create new case from specified XML string
Parameters:(name, type, description)
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.
Return Value & Description:
intReturns:The CaseID of a new case.
Permissions: Create Cases
Exceptions: Exceptions are thrown if Title is not specified.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 153
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: CreateCaseEx
Description: Create new case from specified xml string with the notifyUsers option.
Parameters:(name, type, description)
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.
Return Value & Description:
intReturns:The CaseID of a new case.
Permissions: Create Cases
Exceptions: Exceptions are thrown if Title is not specified.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 154
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: EditCase
Description: Edit case.
Parameters:(name, type, description)
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.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 155
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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>
Permissions: Edit Surveys
Exceptions: SOAP exceptions for invalid case ID.
Method Call: EditCase
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 156
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: EditCaseEx
Description: Edit case with the notifyUsers option.
Parameters:(name, type, description)
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.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 157
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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>
Permissions: Edit Surveys
Exceptions: SOAP exceptions for invalid case ID.
Method Call: EditCaseEx
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 158
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetCases
Description: Get cases.
Parameters:(name, type, description)
caseIds (int[]) An array of case IDs.
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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>
Where case status:Open = 0Closed = 1OnHold = 2
NOTE The XML returned by GetCases for a single case can be passed to EditCase with or without modification.
Permissions: View Cases or View All Cases
Exceptions: Exceptions are thrown if there more than 500 casesrequested.
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 159
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCasePriority
Description: Set case priority.
Parameters:(name, type, description)
caseIds (int[]) The array of case IDs for which the priority needs to be set
priority (int) Priority value 1-7 comment (string, optional)
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 160
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCasePriorityEx
Description: Set case priority with the notifyUsers option.
Parameters:(name, type, description)
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].
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 161
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetCaseDetail
Description: Get case details.
Parameters:(name, type, description)
caseId (int) The case ID
Return Value & Description
XMLNodeReturns:XML representation, as follows:
<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>
Where case status:Open = 0Closed = 1OnHold = 2
Permissions: View Cases or View All Cases
Exceptions: Exceptions are thrown for invalid case ID
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 162
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCaseOwner
Description: Assign case owner.
Parameters:(name, type, description)
caseIds (int[]) The array of case IDs for which the owner needs to be set
owner (int) The case UserID comment (string, optional)
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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>
Permissions: Edit Cases
Exceptions: None
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 163
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCaseOwnerEx
Description: Assign case owner with the notifyUsers option.
Parameters:(name, type, description)
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
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].
Return Value & Description:
XMLNodeReturns:XML representation, as follows:
<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>
Permissions: Edit Cases
Exceptions: None
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 164
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: AddCaseComment
Description: Add comment to cases.
Parameters:(name, type, description)
caseIds (int[]) The array of case IDs for which the comment needs to be added
comment (string)
Return Value & Description:
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>
Permissions: Edit Cases
Exceptions: Exceptions are thrown for invalid case IDs
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 165
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: AddCaseCommentEx
Description: Add comment to cases with the notifyUsers option.
Parameters:(name, type, description)
caseIds (int[]) The array of case IDs for which the comment needs to be added.
comment (string) 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].
Return Value & Description:
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>
Permissions: Edit Cases
Exceptions: Exceptions are thrown for invalid case IDs
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 166
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCaseStatus
Description: Set case status.
Parameters:(name, type, description)
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
Return Value & Description:
XML NodeReturns:XML representation, as follows:
<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>
Permissions: Edit Cases
Exceptions: None
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 167
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetCaseStatusEx
Description: Set case status with the notifyUsers option.
Parameters:(name, type, description)
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
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].
Return Value & Description:
XML NodeReturns:XML representation, as follows:
<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>
Permissions: Edit Cases
Exceptions: None
Chapter 4 - Web Services Data Web Service for casedata.asmx
EFM Web Services Technical Guide 168
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: DeleteCases
Description: Delete cases.
Parameters:(name, type, description)
caseIds (int[]) The array of case IDs which need to be deleted.
Return Value & Description:
XML NodeReturns:XML representation, as follows:
<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
Exceptions: SOAP exceptions for invalid case ID.
Chapter 4 - Web Services Data Web Service admin.asmx
EFM Web Services Technical Guide 169
Confidential and Proprietary Information of Verint Systems Inc.
Web Service admin.asmxWeb Service for user and workgroup management.
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.
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.
Parameters:(name, type, description)
username (string) User name; max 255 characters
displayname (string) Display name; max 255 characters
email (string) User's email address; max 255 characters
Return Value & Description:
intReturns: The userid for the added user
Permissions: Create Users
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 170
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
Userid (int) The User's ID
Return Value & Description:
N/A
Permissions: System Administrator Account
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 171
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetUserData
Description: Shows information about all users of the given status.
Parameters:(name, type, description)
status (int)0 = active 1 = suspended2 = deleted
Return Value & Description:
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.
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 172
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
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
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 173
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetUserInformation
Description: Returns information about a user.
Parameters:(name, type, description)
userid (int) The user's ID
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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>
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 174
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<OrganizationAccess name="organization name">
<OrganizationData key="organization key" id="organization id"/>
</OrganizationAccess></User>
Culture definitions: http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx
Permissions: View Users
Exceptions: None
Method Call: GetUserInformation
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 175
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 176
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: ResetUserPassword
Description: Reset the user's password. This sends the new password to the user's email.
Parameters:(name, type, description)
userid (int) The user's ID
Return Value & Description:
N/A
Permissions: Create Users
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 177
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: ChangeUserPassword
Description: Change the user's password.
Parameters:(name, type, description)
userid (int) The user's ID newPassword (string) The new password
(plaintext)
Return Value & Description:
N/A
Permissions: Create Users
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 178
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetUserInfoByEmail
Description: Get a user's information by using an email address
Parameters:(name, type, description)
emailAddress (string) User's email address
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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>
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 179
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<OrganizationAccess name="organization name">
<OrganizationData key="organization key" id="organization id"/>
</OrganizationAccess></User>
Culture definitions: http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx
Permissions: View Users
Exceptions: None
Method Call: GetUserInfoByEmail
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 180
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetUserInfoByExternalId
Description: Return information about a user with specified external data source key/id pair as an XML string.
Parameters:(name, type, description)
userDataSourceKey (string) External data source key (can be blank)
userDataSourceId (string) External data source ID
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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>
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 181
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<OrganizationAccess name="organization name">
<OrganizationData key="organization key" id="organization id"/>
</OrganizationAccess></User>
Culture definitions: http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx
Permissions: View Users
Exceptions: None
Method Call: GetUserInfoByExternalId
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 182
Confidential and Proprietary Information of Verint Systems Inc.
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.
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: SOAP exceptions for the authorized user that does not belong to a workgroup.
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 183
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetUserInfoByUsername
Description: Get a user's information by username
Parameters:(name, type, description)
username (string) The user's username
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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>
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 184
Confidential and Proprietary Information of Verint Systems Inc.
Return Value & Description:
<OrganizationAccess name="organization name">
<OrganizationData key="organization key" id="organization id"/>
</OrganizationAccess></User>
Culture definitions: http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx
Permissions: View Users
Exceptions: None
Method Call: GetUserInfoByUsername
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 185
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetOrganizationHierarchy
Description: Extract current Organization Hierarchy for aspecified Workgroup in XML representation.
Parameters:(name, type, description)
groupId (int) The workgroup ID
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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>
Permissions: View Users
Exceptions: None
Chapter 4 - Web Services Data Add/Change/Remove Users
EFM Web Services Technical Guide 186
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: ImportOrganizationHierarchy
Description: Import Organization Hierarchy in XML representation.
Parameters:(name, type, description)
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
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<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
EFM Web Services Technical Guide 187
Confidential and Proprietary Information of Verint Systems Inc.
Workgroup Access
Method Call: GetWorkgroupList
Description: Get a list of workgroups accessible to the API user.
Parameters:(name, type, description)
None
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<Workgroups><Workgroup id="GROUP ID">
<Name>GROUP NAME</Name><Description>DESCRIPTION</Description>
</Workgroup></Workgroups>
Permissions: View Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 188
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetWorkgroupUsers
Description: Get a list of users in a workgroup.
Parameters:(name, type, description)
groupId (int) The workgroup ID
Return Value & Description:
intReturns: An array of integer userids
Permissions: View Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 189
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetWorkgroupUnsubscribes
Description: Get the list of unsubscribed email addresses in a workgroup.
Parameters:(name, type, description)
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.
Return Value & Description:
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
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 190
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
groupId (int) The Workgroup ID userid (int) The user's ID
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 191
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
groupId (int) The Workgroup ID userid (int) The user's ID
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 192
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetWorkgroupRoleList
Description: Get a list of the Security Roles in this Workgroup
Parameters:(name, type, description)
groupId (int) The Workgroup ID
Return Value & Description:
XmlNodeReturns: An XML representation, as follows:
<Roles> <Role id="ROLE ID">ROLE NAME</Role>
</Roles>
Permissions: View Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 193
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetWorkgroupRole
Description: Get the ID of the Security Role this user has in this group.
Parameters:(name, type, description)
groupId (int) The Workgroup ID userid (int) The user's ID
Return Value & Description:
intReturns: The role ID; call GetWorkgroupRoleList for a list of roles.
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 194
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetWorkgroupRole
Description: Set the role of this user in this Workgroup to the given role.
Parameters:(name, type, description)
groupId (int) The Workgroup ID userid (int) The user's ID roleId (int) The ID of the role to assign
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Workgroup Access
EFM Web Services Technical Guide 195
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
userId (int) The user's ID groupID (int) The Workgroup ID
Return Value & Description:
N/A
Permissions: Edit Users
Exceptions: None
Chapter 4 - Web Services Data Web Service reportdata.asmx
EFM Web Services Technical Guide 196
Confidential and Proprietary Information of Verint Systems Inc.
Web Service reportdata.asmxThis Web Service exposes memorized reports.
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.
Memorized Reports
Method Call: GetMemorizedReports
Description: Get the memorized reports for a given project.
Parameters:(name, type, description)
projectId (int) A project ID
Return Value & Description:
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
EFM Web Services Technical Guide 197
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: DeleteMemorizedReport
Description: Delete the given memorized report.
Parameters:(name, type, description)
projectId (int) A project ID reportId (int) The report ID; see
GetMemorizedReports
Return Value & Description:
N/A
Permissions: Delete Reports
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 198
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: CloneReport
Description: Create a new memorized report for a given project from an existing report.
Parameters:(name, type, description)
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
Return Value & Description:
intReturns: The new report ID
Permissions: Create Reports
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 199
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
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.
WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.
Return Value & Description:
intReturns: The report ID of the new report.
Permissions: Create Reports
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 200
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: GetMemorizedReportSharing
Description: Returns a list of users authorized to view the specified report.
Parameters:(name, type, description)
projectId (int) A project ID reportId (int) The report ID; see
GetMemorizedReports
Return Value & Description:
XMLNodeReturns: An XML representation of the shared users, as follows:
<Report><Userid="ID" />
</Report>
Permissions: View Reports
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 201
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID reportId (int) The report ID; see
GetMemorizedReports usersXml (string) A XML list of users, in the
same format as returned by GetMemorizedReportSharing.
Return Value & Description:
N/A
Permissions: Edit Reports
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 202
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
projectId (int) A project ID reportId (int) The report ID; see
GetMemorizedReports
Return Value & Description:
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"/>
</CriteriaCollection>
Operator is one of = != < > <= >=
Permissions: View Reports and View Project
Exceptions: None
Chapter 4 - Web Services Data Memorized Reports
EFM Web Services Technical Guide 203
Confidential and Proprietary Information of Verint Systems Inc.
Method Call: SetMemorizedReportFilter
Description: Change the filter for a memorized report. The format is the same as returned by GetMemorizedReportFilter.
Parameters:(name, type, description)
projectId (int) A project ID reportId (int) The report ID; see
GetMemorizedReports filterXml (string) XML specifying a set of
Criterion objects used to filter the data.
WARNING If a DATABASE COLUMN of other than a question heading is specified, the attribute: namespace="PDC_RESPONDENTS" is required in the Criterion node.
Return Value & Description:
N/A
Permissions: Edit Reports and View Project
Exceptions: None
Chapter 4 - Web Services Data Report Users
EFM Web Services Technical Guide 204
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameters:(name, type, description)
None
Return Value & Description:
XMLNodeReturns: An XML representation of the authorized users, as follows:
<Users><Userid="ID">
<username>USERNAME</username><displayname>DISPLAY NAME</displayname>
</User></Users>
Permissions: View 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
EFM Web Services Technical Guide 206
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Chapter 5 - Survey Event Handler Use Examples
EFM Web Services Technical Guide 207
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 208
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 209
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 210
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 211
Confidential and Proprietary Information of Verint Systems Inc.
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)
EFM Web Services Technical Guide 212
Confidential and Proprietary Information of Verint Systems Inc.
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)
EFM Web Services Technical Guide 213
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 214
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 215
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 216
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 217
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 218
Confidential and Proprietary Information of Verint Systems Inc.
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.
UserKey2* Gets the value of User Key 2 for the survey respondent.
UserKey3* Gets the value of User Key 3 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
EFM Web Services Technical Guide 219
Confidential and Proprietary Information of Verint Systems Inc.
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).
Parameter Description
Chapter 5 - Survey Event Handler WebServiceRequest
EFM Web Services Technical Guide 220
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameter Description
Chapter 5 - Survey Event Handler JSON Example
EFM Web Services Technical Guide 221
Confidential and Proprietary Information of Verint Systems Inc.
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"
},{"":"Q2_2","Value":"0","Type":"TinyInt"
},{"":"Q2_3","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
EFM Web Services Technical Guide 222
Confidential and Proprietary Information of Verint Systems Inc.
},{"":"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
EFM Web Services Technical Guide 223
Confidential and Proprietary Information of Verint Systems Inc.
WebServiceResponse
Parameter Description
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
EFM Web Services Technical Guide 224
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameter Description
Chapter 5 - Survey Event Handler JSON Example
EFM Web Services Technical Guide 225
Confidential and Proprietary Information of Verint Systems Inc.
JSON Example{
"Culture":"es-ES","RedirectUrl":"http://www.example.com","Command":"ValidationFailed","Fields":[{
"":"Q1","Value":"1","Type":"SmallInt"
},{"":"Q2_1","Value":"1","Type":"TinyInt"
}]}"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
EFM Web Services Technical Guide 226
Confidential and Proprietary Information of Verint Systems Inc.
Field
Parameter Description
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
EFM Web Services Technical Guide 227
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 228
Confidential and Proprietary Information of Verint Systems Inc.
Web Services Event Handler
Chapter 5 - Survey Event Handler Use
EFM Web Services Technical Guide 229
Confidential and Proprietary Information of Verint Systems Inc.
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)
EFM Web Services Technical Guide 230
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 231
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 232
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 233
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 234
Confidential and Proprietary Information of Verint Systems Inc.
{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
EFM Web Services Technical Guide 235
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 236
Confidential and Proprietary Information of Verint Systems Inc.
Notify the email address
Chapter 5 - Survey Event Handler Survey Event Descriptions
EFM Web Services Technical Guide 237
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 238
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 239
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 240
Confidential and Proprietary Information of Verint Systems Inc.
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.
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
EFM Web Services Technical Guide 242
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 243
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 244
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 245
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 246
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 247
Confidential and Proprietary Information of Verint Systems Inc.
[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.
Chapter 6 - Hierarchical Questions Web Service Steps for Using the Sample Code Provided
EFM Web Services Technical Guide 248
Confidential and Proprietary Information of Verint Systems Inc.
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.
Chapter 6 - Hierarchical Questions Web Service Steps for Using the Sample Code Provided
EFM Web Services Technical Guide 249
Confidential and Proprietary Information of Verint Systems Inc.
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.
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
Product Name The Book Title and Name of this Guide 251
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 252
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 253
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 254
Confidential and Proprietary Information of Verint Systems Inc.
"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.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started "Progress" properties
Product Name The Book Title and Name of this Guide 255
Confidential and Proprietary Information of Verint Systems Inc.
"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.
Property Type Description
"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
Product Name The Book Title and Name of this Guide 256
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 257
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 258
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 259
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
"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
Product Name The Book Title and Name of this Guide 260
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 261
Confidential and Proprietary Information of Verint Systems Inc.
Validations
Each validation defined for a question consists of the following properties:
Property Type Description
"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
Product Name The Book Title and Name of this Guide 262
Confidential and Proprietary Information of Verint Systems Inc.
"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.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Choose One question
Product Name The Book Title and Name of this Guide 263
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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
Chapter 7 - Survey Engine API - Getting Started Choose One question
Product Name The Book Title and Name of this Guide 264
Confidential and Proprietary Information of Verint Systems Inc.
"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
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Choose One question
Product Name The Book Title and Name of this Guide 265
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Choose One with Image question
Product Name The Book Title and Name of this Guide 266
Confidential and Proprietary Information of Verint Systems Inc.
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.).
Property Type Description
"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"
"Label" String Label of the choice:"Label": "Choice label"
"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
"Selected" Boolean Appears as true if the choice is selected due to Preselection settings or previously answered:"Selected":true
"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
Product Name The Book Title and Name of this Guide 267
Confidential and Proprietary Information of Verint Systems Inc.
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://.."
"Validations" Array Answer Required: "ReqAns"
Answer Required for "Please Specify" Options: "ReqSpecify"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Essay question
Product Name The Book Title and Name of this Guide 268
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
"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"
"Validations" Array Answer Required: "ReqAns"
Enable Characters Limitation: "CharactersMaxLength"
For more information, see “Validations” on page 261.
Chapter 7 - Survey Engine API - Getting Started Choose Many question
Product Name The Book Title and Name of this Guide 269
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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"
"Label" String Label of the choice group:"Label": "Choice group label"
Choices properties:
"Type" String Property indicating a choice:"Type": "Choice"
"Label" String Label of the choice:"Label": "Choice label"
"Id" String Column name where the choice response is stored:"Id": "Q1_1"
"Selected" 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 Choose Many question
Product Name The Book Title and Name of this Guide 270
Confidential and Proprietary Information of Verint Systems Inc.
For an example of answering the Choose Many question, see “Page data in request” on page 319.
"Specify" Object Appears if the Include "Please Specify" option is selected for the choice. For details, see “Choose One question” on page 263.
"Exclusive"(optional)
Boolean Appears as true if the Exclusive option is selected for the choice:"Exclusive": true
"Validations" Array Answer Required: "ReqAns"
Answer Required for "Please Specify" Options: "ReqSpecify"
Respondent Must Pick:
At Least N Choice(s): "ChkMin"
At Most N Choice(s): "ChkMax"
Exactly N Choice(s): "ChkExc"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Choose Many with Image question
Product Name The Book Title and Name of this Guide 271
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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.
"Type" String Property indicating a choice:"Type": "Choice"
"Label" String Label of the choice:"Label": "Choice label"
"Id" String Column name where the choice response is stored:"Id": "Q1_1"
"Selected" Boolean Appears as true if the choice is selected due to Preselection settings or previously answered:"Selected":true
"Specify" Object Appears if the Include "Please Specify" option is selected for the choice. For details, see “Choose One question” on page 263.
"Exclusive"(optional)
Boolean Appears as true if the Exclusive option is selected for the choice:"Exclusive": true
Chapter 7 - Survey Engine API - Getting Started Choose Many with Image question
Product Name The Book Title and Name of this Guide 272
Confidential and Proprietary Information of Verint Systems Inc.
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://.."
"Validations" Array Answer Required: "ReqAns"
Answer Required for "Please Specify" Options: "ReqSpecify"
Respondent Must Pick:
At Least X Choice(s): "ChkMin"
At Most X Choice(s): "ChkMax"
Exactly X Choice(s): "ChkExc"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Image Upload question
Product Name The Book Title and Name of this Guide 273
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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
Product Name The Book Title and Name of this Guide 274
Confidential and Proprietary Information of Verint Systems Inc.
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.
"Validations" Array Answer Required: "ReqAns"
File type validation: "ImageFileType." The following image formats are supported: .bmp, .exif, .ico, .jpeg, .png, and .tiff.
For more information, see “Validations” on page 261.
NOTE If Q#_1_NAME and Q#_1_TAGS are missing or blank, previous image data is not overwritten.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Rank Order question
Product Name The Book Title and Name of this Guide 275
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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
Product Name The Book Title and Name of this Guide 276
Confidential and Proprietary Information of Verint Systems Inc.
For an example of answering the Rank Order question, see “Page data in request” on page 319.
"Choices" Array Choices of the question. The Choices properties are provided below.
"Type" String Property indicating a choice:"Type": "Choice"
"Label" String Label of the choice:"Label": "Choice label"
"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
"Validations" Array Answer Required: "ReqAns"
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"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Drag and Drop Rank Order question
Product Name The Book Title and Name of this Guide 277
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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"
"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
"Choices" Array Choices of the question. The Choices properties are provided below.
"Type" String Property indicating a choice:"Type": "Choice"
"Label" String Label of the choice:"Label": "Choice label"
Chapter 7 - Survey Engine API - Getting Started Drag and Drop Rank Order question
Product Name The Book Title and Name of this Guide 278
Confidential and Proprietary Information of Verint Systems Inc.
The Drag and Drop Rank Order question is answered the same way as Rank Order question (See “Page data in request” on page 319.)
"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
"Validations" Array Answer Required: "ReqAns"
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"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Scale Slider question
Product Name The Book Title and Name of this Guide 279
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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
"TopicCell"(optional)
String Row heading text if specified when designing the question:"TopicCell":"Row heading"
"Layout" String Layout of the Scale Slider question: "star" and "scale." Note that in JSON, the Slider layout is "scale":"Layout": "star"
"Topics" Array Array of topic objects. The Topics properties are provided below.
"Type" String Property indicating a topic:"Type": "Topic"
Chapter 7 - Survey Engine API - Getting Started Scale Slider question
Product Name The Book Title and Name of this Guide 280
Confidential and Proprietary Information of Verint Systems Inc.
For an example of answering the Scale Slider question, see “Page data in request” on page 319.
"Id" String Column name where the topic response is stored:"Id": "Q1_A_1"
"Label" String Label of the topic:"Label": "Topic label"
"Image"(optional)
String URL to the image provided in the topic if present:"URL": "http//.."
"Value" Integer The selected choice value for the topic. This property is included only if the question is already answered."Value": 1
"Choices" Array Choices of the question. The Choices properties are provided below.
"Type" String Property indicating 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
"Validations" Array Answer Required: "ReqAns"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix question
Product Name The Book Title and Name of this Guide 281
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"TopicCell"(optional)
String Row heading text if specified when designing the question:"TopicCell":"Row heading"
"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"
"Topics" Array Array of topic objects. The Topics properties are provided below.
"Type" String Property indicating a topic:"Type": "Topic"
"Id" String Unique identifier of the topic. Possible values are 1..n:"Id": "1"
"Label" String Label of the topic:"Label": "Topic label"
"Sides" Array Array of side objects. The Sides properties are provided below.
Chapter 7 - Survey Engine API - Getting Started Matrix question
Product Name The Book Title and Name of this Guide 282
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix Choose One side
Product Name The Book Title and Name of this Guide 283
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Type" String Type of the Matrix side:"Type":"ChooseOne"
"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"
"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.
Chapter 7 - Survey Engine API - Getting Started Matrix Choose One side
Product Name The Book Title and Name of this Guide 284
Confidential and Proprietary Information of Verint Systems Inc.
Choice groups properties
"Type" String 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"
"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"
"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"(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.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix Choose One side
Product Name The Book Title and Name of this Guide 285
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 286
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Type" String Type of the Matrix side:"Type":"ChooseMany"
"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"
"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"
"Label" String Label of the choice group:"Label": "Choice group label"
Chapter 7 - Survey Engine API - Getting Started Matrix Choose Many side
Product Name The Book Title and Name of this Guide 287
Confidential and Proprietary Information of Verint Systems Inc.
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
"Type" String Property indicating a choice:"Type": "Choice"
"Label" String Label of the choice:"Label": "Choice label"
"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
"Exclusive"(optional)
Boolean Appears as true if the Exclusive option is selected for the choice:"Exclusive": true
"Validations" Array See “Validations for Matrix question” on page 342 and “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix Short Answer side
Product Name The Book Title and Name of this Guide 288
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Type" String Type of the Matrix side:"Type":"FillIn"
"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"
"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.
Chapter 7 - Survey Engine API - Getting Started Matrix Short Answer side
Product Name The Book Title and Name of this Guide 289
Confidential and Proprietary Information of Verint Systems Inc.
"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"
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix Short Answer side
Product Name The Book Title and Name of this Guide 290
Confidential and Proprietary Information of Verint Systems Inc.
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"
"Validations" Array See “Validations for Matrix question” on page 342 and “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Matrix Essay side
Product Name The Book Title and Name of this Guide 291
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Type" String Type of the Matrix side:"Type":"Essay"
"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"
"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
Product Name The Book Title and Name of this Guide 292
Confidential and Proprietary Information of Verint Systems Inc.
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)
String Preselected or previously answered value:"Value": "Preselected answer"
"Validations" Array See “Validations for Matrix question” on page 342 and “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Scrolling Matrix question
Product Name The Book Title and Name of this Guide 293
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Columns" Integer Number of columns in the question:"Columns": 3
"TopicCell"(optional)
String Row heading text if specified when designing the question:"TopicCell":"Row heading"
"Topics" Array Array of topic objects. The Topics properties are provided below.o
"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"
"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"
"Choices" Array Choices of the question. The Choices properties are provided below.
"Type" String Property indicating a choice:"Type": "Choice"
"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
Product Name The Book Title and Name of this Guide 294
Confidential and Proprietary Information of Verint Systems Inc.
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",
}
"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
"Validations" Array Answer Required: "ReqAns"
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Fill in the Blank question
Product Name The Book Title and Name of this Guide 295
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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"
Chapter 7 - Survey Engine API - Getting Started Fill in the Blank question
Product Name The Book Title and Name of this Guide 296
Confidential and Proprietary Information of Verint Systems Inc.
"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": "%"
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Fill in the Blank question
Product Name The Book Title and Name of this Guide 297
Confidential and Proprietary Information of Verint Systems Inc.
"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)
String Preselected or previously answered value:"Value": "Preselected answer"
"Autodropdown" Array Array of autodropdown objects. It is included only if input type for the response is Autodropdown. Properties for AutoDropdown are provided below.
"Key" String The Autodropdown text:"Key": "Option 1"
"Value" String The Autodropdown value:"Value": "Option 1"
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Fill in the Blank question
Product Name The Book Title and Name of this Guide 298
Confidential and Proprietary Information of Verint Systems Inc.
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",
}
"MaxLength" String Maximum number of characters for the Text input type that is set in the Maximum Length field:"MaxLength": "20"
"Validations" Array Answer Required: "ReqAns"
Allocation: "ReqSum"
Minimum Length: "MinLen"
Numeric Range: "Range"
Valid Characters: "ValidCharacters"
Text Mask: "TextMask"
Validate Topics: “MatchValue”, “NotMatchValue”, “LessThanValue”, “GreaterThanValue”, “LessThanOrEqualValue”, “GreaterThanOrEqualValue”
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Short Answer question
Product Name The Book Title and Name of this Guide 299
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"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"
Chapter 7 - Survey Engine API - Getting Started Short Answer question
Product Name The Book Title and Name of this Guide 300
Confidential and Proprietary Information of Verint Systems Inc.
"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)
String Preselected or previously answered value:"Value": "Preselected answer"
"Autodropdown" Array Array of autodropdown objects. It is included only if input type for the response is Autodropdown. Properties for AutoDropdown are provided below.
"Key" String The Autodropdown text:"Key": "Option 1"
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Short Answer question
Product Name The Book Title and Name of this Guide 301
Confidential and Proprietary Information of Verint Systems Inc.
The Short answer question is answered the same way as Fill in the Blank question described in the preceding table.
"Value" String The Autodropdown value:"Value": "Option 1"
"MaxLength" String Maximum number of characters for the Text input type that is set in the Maximum Length field:"MaxLength": "20"
"Validations" Array Answer Required: "ReqAns"
Allocation: "ReqSum"
Minimum Length: "MinLen"
Numeric Range: "Range"
Valid Characters: "ValidCharacters"
Text Mask: "TextMask"
Validate Topics: “MatchValue”, “NotMatchValue”, “LessThanValue”, “GreaterThanValue”, “LessThanOrEqualValue”, “GreaterThanOrEqualValue”
For more information, see “Validations” on page 261.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Hidden questions
Product Name The Book Title and Name of this Guide 302
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
"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
Product Name The Book Title and Name of this Guide 303
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 304
Confidential and Proprietary Information of Verint Systems Inc.
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.
Property Type Description
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
Product Name The Book Title and Name of this Guide 305
Confidential and Proprietary Information of Verint Systems Inc.
Redirect to an existing Web page 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"
"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"
"TagLine" String Survey tagline that is set during survey design on the Formatting side tab > General drawer.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Language Selection page
Product Name The Book Title and Name of this Guide 306
Confidential and Proprietary Information of Verint Systems Inc.
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.)
Property Type Description
"Type" String Type of the page:"Type": "LanguageSelectionPage"
"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.
"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
Product Name The Book Title and Name of this Guide 307
Confidential and Proprietary Information of Verint Systems Inc.
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.
"TagLine" String Survey tagline that is set during survey design on the Formatting side tab > General drawer.
NOTE The selected language ID should match the ID of one of the languages provided in the Languages array.
Property Type Description
Chapter 7 - Survey Engine API - Getting Started Jump page
Product Name The Book Title and Name of this Guide 308
Confidential and Proprietary Information of Verint Systems Inc.
Jump pageThe returned JSON of the Jump page includes the following properties. (For an example, see Jump page response, page 318.)
Property Type Description
"Type" String Type of the page:"Type": "JumpPage"
"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.
"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.
"Selected"(optional)
Boolean Appears as true for the page, from which respondent jumped.
"Buttons" Object Object for the Back button:"back": "Back"
"TagLine" String Survey tagline that is set during survey design on the Formatting side tab > General drawer.
Chapter 7 - Survey Engine API - Getting Started Jump page
Product Name The Book Title and Name of this Guide 309
Confidential and Proprietary Information of Verint Systems Inc.
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
Product Name The Book Title and Name of this Guide 310
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 312
Confidential and Proprietary Information of Verint Systems Inc.
Campaign Statuses
Parameter Description
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
EFM Web Services Technical Guide 313
Confidential and Proprietary Information of Verint Systems Inc.
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.
Parameter Description
Chapter 8 - Appendix Survey Engine API - JSON examples
EFM Web Services Technical Guide 314
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 315
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 316
Confidential and Proprietary Information of Verint Systems Inc.
}],"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)
EFM Web Services Technical Guide 317
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 318
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 319
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 320
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 321
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 322
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 323
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 324
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 325
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 326
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 327
Confidential and Proprietary Information of Verint Systems Inc.
"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
EFM Web Services Technical Guide 328
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 329
Confidential and Proprietary Information of Verint Systems Inc.
"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)
EFM Web Services Technical Guide 330
Confidential and Proprietary Information of Verint Systems Inc.
{"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)
EFM Web Services Technical Guide 331
Confidential and Proprietary Information of Verint Systems Inc.
"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)
EFM Web Services Technical Guide 332
Confidential and Proprietary Information of Verint Systems Inc.
},{"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)
EFM Web Services Technical Guide 333
Confidential and Proprietary Information of Verint Systems Inc.
"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)
EFM Web Services Technical Guide 334
Confidential and Proprietary Information of Verint Systems Inc.
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)
EFM Web Services Technical Guide 335
Confidential and Proprietary Information of Verint Systems Inc.
"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)
EFM Web Services Technical Guide 336
Confidential and Proprietary Information of Verint Systems Inc.
"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
EFM Web Services Technical Guide 337
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 338
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 339
Confidential and Proprietary Information of Verint Systems Inc.
"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
EFM Web Services Technical Guide 340
Confidential and Proprietary Information of Verint Systems Inc.
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)
EFM Web Services Technical Guide 341
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 342
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 343
Confidential and Proprietary Information of Verint Systems Inc.
"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
EFM Web Services Technical Guide 344
Confidential and Proprietary Information of Verint Systems Inc.
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
EFM Web Services Technical Guide 346
Confidential and Proprietary Information of Verint Systems Inc.
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
www.verint.com