web services technical guide 7 - efmhelp.netefmhelp.net/.../web_services_technical_guide_7.0.pdf ·...

Confidential and Proprietary Information of Verint Systems Inc.

EFM

Web Services Technical Guide

Version 7.0

Document Revision 2.00

© 2013 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 2.00

Published September 23, 2013

C o n t e n t s

1 Web Services API-Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4General Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4EFM Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Web Services Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Web Service projectdata.asmx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Web Service reportdata.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Web Service paneldata.asmx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Web Service bulk.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Web Service admin.asmx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

3 Survey Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Use Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Using the Visual Studio Web Site Provided . . . . . . . . . . . . . . . . . . . . . . . . . . 165Creating a New Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Creating a Web Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Using the WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Survey Event Handler Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Survey Event Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Sample Survey Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

4 Hierarchical Questions Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Adding a Hierarchical Question to Your Survey . . . . . . . . . . . . . . . . . . . . . . . . 182Example of Using a Web Service for Hierarchical Questions . . . . . . . . . . . . . . . . . . 183Sample Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

C h a p t e r 1

Web Services API1-Getting Started

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)

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

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

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

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 1 - Web Services API-Getting Started General Introduction

EFM Web Services Technical Guide 5


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 on the project file and select "Add Web Reference…"

Adding a Reference to a Web Service Using Visual StudioType 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 example below.

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




ProjectData Web Reference




Connecting to a Web Service Using Visual StudioTo use a Web Service in Visual Studio, an instance of the object (using the Webreference name that was selected earlier) must be created. Below 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.Please note that the program must login to each Web Service. Logging into a single Web Service will not authenticate the program globally.Any EFM account can be used to login, but the Web Service will be restricted to the permissions allowed for that account's role in EFM. For example, if the Web Service logs into an account that only has survey editing capabilities, you will not be able to 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.




Dynamically Accessing a Web ServiceSometimes the URL of a Web Service may not be fixed. In these cases, you may wish to specify a URL for the Web Service at runtime. Below 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. In some cases it may be more efficient to utilize the System.Uri object to construct the URL instead of building a string.




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.

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 (e.g., asking for a questionnaire before it has been created).

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

The Microsoft .NET Framework will 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. A C# code example is provided below:// Assign a cookie container so the Web Service can preserve the validated// sessionwsProjectData.CookieContainer = new System.Net.CookieContainer();

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



EFM Web Services

Introduction to EFM Web ServicesIn documentation and method names, we use "project" to cover both surveys and panel profiles. The following pages will 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, paneldata.asmx, bulk.asmx, and admin.asmx.

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

Method Call name

Description

Parameters

Return Value and Description

Permissions

Exceptions

Methods will throw SoapExceptions for:

permission errors

parameters out of range

problems reading from or writing to the database

logical errors (e.g., 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 (e.g. 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.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();




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, then there is a validation problem. See "Login" call below.

Parameters:(name, type, description)

None

Return Value & Description:

string Returns: The string ACK

Permissions: None

Exceptions: None




Method Call: Login

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

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

Best practice is to use an account which is used only for accessing Web Services that belongs to a security role that has the minimum set of required permissions needed to perform whatever actions the calling process needs to perform (i.e., the principle of least privilege). The client must enable cookies, so that the login information is preserved across calls.


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


string Returns:Empty string for successSOAP exception on failure

Permissions: None

Exceptions:




Method Call: Logout

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


None


None

Permissions: None

Exceptions: None

C h a p t e r 2

Web Services Data

Web Service projectdata.asmxThis Web Service exposes SurveyProject data. In documentation and method names, we use "project" to cover both surveys and panel profiles.

Lists of Projects

Method Call: GetSurveyList

Description: Returns a list of surveys in an XML representation


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


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

<Projects><Project id="ID">

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

</Projects>

Permissions: View Surveys

Exceptions: None

Chapter 2 - Web Services Data Web Service projectdata.asmx



Method Call: GetCommonSurveyListF

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


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


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


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

</Projects>


Exceptions: None




Method Call: GetProfileList

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


None


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


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

</Projects>

Permissions: View Panel Profiles

Exceptions: None




Project Creation

Method Call: CreateSurveyProject

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


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

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

respondent Source (int)

0 = open participation1 = EFM panel2 = external email list3 = external access list


intReturns: The new project id

Permissions: Create Surveys

Exceptions: None




Method Call: CreatePanelProfile

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


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

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


intReturns: The new project id

Permissions: Create Panel Profiles

Exceptions: None




Questionnaire Access

Method Call: GetQuestionnaire

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

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

Parameters: (name, type, description)

projectId (int) A project ID


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


Exceptions: None




Method Call: GetPublishedQuestionnaire

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

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




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


Exceptions: None




Method Call: SetQuestionnaire

Description: Set the questionnaire via its XML representation.

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


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

questionnaire, as returned by GetQuestionnaire


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

Permissions: Edit Surveys

Exceptions: None




Method Call: GetQuestionnaireVersions

Description: Get the current list of versions of this survey



Return Value & Description

XMLNodeReturns: XML specifying the versions, as follows:

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

</Versions>


Exceptions: None

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




Notes: SectionAddedCommentAddedPageBreakAddedTextBlockAddedPublishRollBackUpgradeQuotaPageRotationCodeBlockUpdatedCodeBlockAddedSurveyGlossary EmailTriggerActivatePageBreakDeleted

Method Call: GetQuestionnaireVersions




Method Call: RevertQuestionnaire

Description: Revert to an earlier version of the questionnaire


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

GetQuestionnaireVersions


N/A


Exceptions: None




Custom Properties

Method Call: GetSurveyCustomProperties

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


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

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


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

<Properties><Property>

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

</Property></Properties>


Exceptions: None




Method Call: GetCustomPropertiesForSurveys

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


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

return projects with a custom property with this name


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

<Projects><Project id="PROJECTID">

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

</Property></Project>

</Projects>


Exceptions: None




Method Call: SetSurveyCustomProperties

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


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

column; or null to set the survey custom properties.

NOTE "columnName" is limited to 255 characters.

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


N/A


Exceptions: None




Column Information

Method Call: GetDataMap

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




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

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

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

</FieldMap></DataMap>


Exceptions: None




Method Call: GetExportDataMap

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




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


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



Exceptions: None




Method Call: GetReportDataMap

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




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


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



Exceptions: None




Method Call: GetColumnList

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




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

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

</Columns>


Exceptions: None




Method Call: GetSurveyInformation

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




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

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

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

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

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

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

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

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

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

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

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

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

</Topic>





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

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

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

</Question></Survey>


Exceptions: None

Method Call: GetSurveyInformation




Method Call: GetSurveyFieldInformation

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


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

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


XMLNodeReturns: An XML structure, as follows:

<SurveyFields xmlns=""><SurveyField>

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

</Heading><Body>

<Text>Choose One Question text</Text>

</Body><Choices>

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

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

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

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

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

</Choice></Choices>

</SurveyField><--! The following XML represents the text in "Other (please specify)" above-->

<SurveyField><Heading>

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

</Heading><Body>

<Text></Text></Body>

</SurveyField>





<SurveyField><Heading>

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

</Heading><Body>

<Text>Choose Many Question text</Text>

</Body><Choice>

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

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

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

</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><Topic>

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

<Choices><Choice dbvalue="1">

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

<Text>Choice B</Text></Choice>






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

</Choice></Choices></SurveyField><SurveyField>

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

</Heading><Body>

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

</Body><Topic>

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

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

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

</SurveyField></SurveyFields>


Exceptions: None





Survey Life Cycle

Method Call: RepublishProject

Description: Open, republish, or close the project.


projectId (int) A project ID publishMode (int)

0 = testing1 = open2 = closed


N/A


Exceptions: None




Survey Information

Method Call: SetEndPageURL

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


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

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

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


N/A


Exceptions: None




Method Call: GetProjectInformation

Description: Get basic information about a project.

NOTE The URL is provided for Open Participation surveys only.




XMLNodeReturns: An XML representation, as follows:

<Project id="PROJECTID" type="Survey|Profile" owner="USERID" publish="Created|Testing|Open|Closed" status="Deleted|Active" source="Panel|Access List|Email List|Open Participation"modifier="MODIFIER"modified_date="MODIFIED"close_date="CLOSE_DATE"publish_date="PUBLISHED"open_date="OPEN_DATE"create_date="CREATE_DATE"> <Name>PROJECT NAME</Name> <Description>PROJECT DESCRIPTION</Description> <URL>URL</URL> </Project>


Exceptions: None




Method Call: SetProjectInformation

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


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

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


N/A


Exceptions: None




Survey Management

Method Call: DeleteProject

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




N/A

Permissions: Delete Surveys

Exceptions: None




Method Call: GetResponseCount

Description: Tell how many responses this survey has received.

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


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

responses only; otherwise, return all started responses.


intReturns: The number of responses of the specified type.

Permissions: View Results

Exceptions: None




Method Call: GetSurveyData

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




DataSetReturns: A DataSet:http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconXMLDataSet.asp


Exceptions: None




Method Call: GetSurveyDataEx

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


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

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

filterXml (string) 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 To use "recordid" as a heading, namespace="PDC_RESPONDENTS" is required in the <Criterion> node.


DataSetReturns: A DataSet

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconXMLDataSet.asp

NOTE The DataSet returned is sorted by modified time.


Exceptions: None




Method Call: GetSurveyDataPaged

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


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

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

filterXml (string) 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.

NOTE To use "recordid" as a heading, namespace="PDC_RESPONDENTS" is required in the <Criterion> node.


DataSetReturns: A DataSet

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconXMLDataSet.asp

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


Exceptions: None




Method Call: GetResponse

Description: Get the answers for one response.


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

found with GetSurveyData(Ex).


XMLNodeReturns: An XML representation of the response as follows:

<Rows><Row id="RECORDID">

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

</Row></Rows>


Exceptions: None




Method Call: ChangeResponse

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


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

be found with GetSurveyData(Ex). columnName (string) The database name for the

column to be changed. newValue (string) A string representation of the new

value.


stringReturns: Blank if successful; else an error message

Permissions: Edit Results

Exceptions: Exceptions will be thrown for invalid record ids or other errors updating the response.




Method Call: ChangeMultipleResponses

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


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

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

<Row id="RECORDID"invite_status="STATUS" user_key1="KEY" user_key2="KEY" user_key3="KEY" last_page="LAST PAGE USER VISITED" started="START TIME" modified="MODIFICATION TIME" completed="COMPLETED TIME">

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

</Rows>


stringReturns: Blank if successful; otherwise an exception message.


Exceptions: None




Method Call: AddResponse

Description: Add a new response to the survey.


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

be added to the new row, this is in the same format as returned by GetResponse and SetParticipantInformation. 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">

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

</Rows>


longReturns: New Record ID of the added response


Exceptions: None




Method Call: GetPreloadData

Description: Get the preload data for a participant.


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

found with GetParticipantData(Ex).


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

Permissions: View Participants

Exceptions: None




Method Call: SetPreloadData

Description: Change the preload data for a participant.

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

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



row(s) to be changed in the same format used by ChangeMultipleResponses.


N/A


Exceptions: None

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




Method Call: DeleteParticipant

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


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

be found with GetParticipantData(Ex).


N/A

Permissions: Delete Participants

Exceptions: None




Method Call: ClearResponse

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


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

found with GetSurveyData(Ex).


N/A

Permissions: Delete Results

Exceptions: None




Aggregate Data

Method Call: GetFrequencyInformation

Description: Get frequency data for a question.

NOTE Currently not supported for matrix questions.


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

can be fetched with GetColumnList.


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

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

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

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

</Frequency></Question>


Exceptions: None




Method Call: GetStatistics

Description: Get statistics data for a question.


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

question can be fetched with GetColumnList.


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

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

</Question>


Exceptions: None




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 doesn't support user keys, which in turn means that a given panelist can be invited to a survey just once.


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


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

Permissions: Import Members

Exceptions: None




Method Call: AuthorizePanelistForSurvey

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


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

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


invited multiple times; pass null if not used.


longReturns: The new recordId


Exceptions: None




Method Call: AuthorizeParticipantForSurvey

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


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

for Access List surveys; max 255 characters. userkey1 (string) A key to allow the same person to be



invited multiple times; pass null if not used. culture (string) The culture to be set for this

participant, e.g. en-US. See http://msdn2.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx


longReturns: The new recordId


Exceptions: None




View Participant Information

Method Call: GetAuthorizedParticipantCount

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

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




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


Exceptions: None




Method Call: GetParticipantData

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

NOTE Maximum of 10,000 records returned per call.




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

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





last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/></Participants>

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


Exceptions: None

Method Call: GetParticipantData




Method Call: GetParticipantDataEx

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

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


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

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

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

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

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


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

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





reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/></Participants>


Exceptions: None

Method Call: GetParticipantDataEx




Method Call: GetParticipantDataPaged

Description: Returns information about participants for this survey. Maximum of 10,000 records returned per call.See also: projectdata.GetParticipantInformation


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 will automatically create this enum when generating a proxy class for the ProjectData web service.0 = Any status (all participants returned)1 = NotStarted2 = Started (excludes completed , branched out or over quota)3 = Completed (excludes branched out or over quota)4 = branched out (excludes completed or over quota)5 = over quota (excludes completed or branched out)

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

recordCount (int) Return no more records than this.


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

<Participants><Participant recordid="RECORDID"invite_status="STATUS"email="EMAIL"culture="ISO-CODE"last_page="LAST PAGE USER VISITED"user_key1="KEY1"user_key2="KEY2"user_key3="KEY3"started="START TIME"modified="MODIFICATION TIME"completed="COMPLETED TIME" branched_out="BRANCHED OUT TIME"over_quota="OVER QUOTA TIME"url="URL TO START THE SURVEY"campaign_status="CAMPAIGN STATUS"http_referer="REFERRING URL"





http_user_agent="WEB BROWSER'S USER AGENT"remote_addr="RESPONDENT'S IP ADDRESS"remote_host="RESPONDENT'S HOST NAME"initial_date="INITAL INVITATION SENT DATE"initial_status="INITIAL INVITATION STATUS"reminder1_date="FIRST REMINDER SENT DATE"reminder1_status="FIRST REMINDER STATUS"reminder2_date="SECOND REMINDER SENT DATE"reminder2_status="SECOND REMINDER STATUS"reminder3_date="THIRD REMINDER SENT DATE"reminder3_status="THIRD REMINDER STATUS"reminder4_date="FOURTH REMINDER SENT DATE"reminder4_status="FOURTH REMINDER STATUS"thankyou_date="THANK YOU SENT DATE"thankyou_status="THANK YOU STATUS"close_date="CLOSE DATE FOR THIS RESPONSE"last_page_number="LAST PAGE NUMBER VIEWED"modifier="EFM USERID THAT LAST MODIFIED THIS USER RECORD"fi_loaded="LOADED INTO FEEDBACK INTELLIGENCE"/></Participants>

Where Invite status:1 = initial invite2 = 1st reminder etc.50 = invalid address


Exceptions: None

Method Call: GetParticipantDataPaged




Method Call: GetParticipantInformation

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


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


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

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





Exceptions: None

Method Call: GetParticipantInformation




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.



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" />

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

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


N/A

Permissions: Edit Participants

Exceptions: None




Method Call: FindPanelistRecord

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


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

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

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

invited multiple times; pass null if not used


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


Exceptions: None

Method Call: FindPanelistsRecord

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

NOTE Maximum of 1,000 records returned per call.


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

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

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

</Panelist></ Panelists>


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

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


Exceptions: None




Method Call: FindParticipantRecord

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


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

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

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

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

invited multiple times; pass null if not used


longReturns: The recordId.


Exceptions: None

Method Call: FindParticipantsRecord

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


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

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

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

</Participant></Participants>


Returns an XML representation of found panelists, as follows:

<Result><Panelist id="123456" /><Error>Missing field: EmailAddress</Error></Result>

Permissions: View Panelists

Exceptions: None




Invitations

Method Call: GetInvitationText

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


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

0 = initial invite1 = 1st reminder etc.


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

Permissions: View Invitations

Exceptions: None




Method Call: GetInvitationTemplate

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


projectId (int) A project ID invitationType (int)



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

<Message type="INVITATIONTYPE"><Subject>

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

</Subject><TextBody>

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

</TextBody><HtmlBody>

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

</HtmlBody></Message>


Exceptions: None




Method Call: SetInvitationTemplate

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


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

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

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

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

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


N/A


Exceptions: None




Method Call: SetMultipleInvitationStatus

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


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

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

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


N/A


Exceptions: None




Method Call: SetInvitationStatus

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


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

0 = Not Invited1 = Initial Invitation Sent2 = First Reminder Sent3 = Second Reminder Sent4 = Third Reminder Sent5 = Fourth Reminder Sent50 = Invalid Address


N/A


Exceptions: None




Method Call: SendInvitationsEx

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


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

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

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


N/A

Permissions: Send Invitations

Exceptions: None




Method Call: SendInvitations

Description: Send out invitations of the given type.


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



N/A

Permissions: Send Invitations

Exceptions: None




Method Call: GetCampaignHistory

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


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

participantId (long) The internal ID of this participant


XmlNode in the following format:<CampaignHistory>

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

</CampaignHistory>Where MAILING TIME is a human readable date/time of the last action associated with that mail (UTC).MAILING STATUS is one of the following values:0 = No Action/Not Sent1 = Passed to mail server - sent to Hurricane Server10 = 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 = Deferred20 = Delivered by Hurricane or Sent to SMTP Server30 = Error received in response from recipients mail server.31 = Error connecting to recipients mail server32 = There was an error with the DNS server.33 = Failure34 = Invalid Email Address40 = 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. (i.e. A word in the message triggered content filtering to fail the message.)





42 = Your message contained a virus and was blocked.43 = Your message has been identified as spam and was blocked.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 blocked70 = User viewed message in mail client (Requested hidden image)80 = User clicked survey link (i.e. started the survey)90 = User unsubscribed from the survey100 = User completed the survey

NOTE

Mailing Status Definition

10-19 DeferredEmail will be retried as configured in Hurricane

30-39 Failure

40-49 Bounce


Exceptions: None

Method Call: GetCampaignHistory




Respondent Reports

Method Call: EmailLiveResultsReport

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

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

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


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


N/A

Permissions: View Results and Edit Panel Profiles

Exceptions:




Method Call: EmailResultsReport

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

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

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


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

0 = Respondent Report,1 = Live Results Report

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

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

Report


N/A


Exceptions: None




Method Call: EmailResultsReportToRespondent

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

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

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


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

0 = Respondent Report, 1 = Live Results Report

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

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

Report


N/A


Exceptions: None




Unsubscribed Emails

Method Call: GetUnsubscribedStatus

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


emailAddress (string) Email address to query the unsubscribe list


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

Permissions: View Unsubscribes

Exceptions: None




Method Call: UnsubscribeListAdd

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


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


N/A

Permissions: Edit Unsubscribes

Exceptions: None




Method Call: UnsubscribeListRemove

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


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


N/A

Permissions: Edit Unsubscribes

Exceptions: None




Update Borrowed Questions

Method Call: UpdateBorrowedQuestions

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




N/A


Exceptions: None




Method Call: UpdateBorrowedQuestionsForRespondent

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


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

survey


N/A


Exceptions: None




Validate a Single Response

Method Call: ValidateSingleResponse

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


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

survey


List of cleared fields:<Result>

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


Exceptions: SOAP Exceptions for invalid access and invalid




Method Call: GetSurveyEventHandler

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


projectid (int) A project ID


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

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

</Events></WebServiceHandlerProperties>


Exceptions: None




Method Call: SetSurveyEventHandler

Description: Set survey event handler properties for given project id


projectid (int) A project ID eventHandlerProperties (string) String of XML, in the

same format returned by GetSurveyEventHandler


N/A


Exceptions: None




Translations

Method Call: GetSurveyTranslations

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

placeholders for translation Returns string in XLIFF format with translatable strings

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


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

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


<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">

<file original="18d1fdae.que" source-language="en-US" target-language="fr-CA" datatype="plaintext">

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

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

</trans-unit></body>

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


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


</file></xliff>

Permissions: Translate Survey

Exceptions: None




Method Call: SetSurveyTranslations

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


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

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

Structure of XLIFF string <xliff> - root tag with XLIFF xml namespace attribute <file> - child tag of xliff document

- "original" attribute - questionnaire file extension- "source-language" attribute - base culture, by

default it is "en-US"- "target-language" attribute - translation language

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

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

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

<source>value</source><target>value</target>

</trans-unit>

Example of translatedXml parameter:<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">

<file original="18d1fdae.que" source-language="en-US" target-language="fr-CA" datatype="plaintext">


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


</file>





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


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


</file></xliff>


N/A

Permissions: Translate Survey

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

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

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

Method Call: SetSurveyTranslations




Method Call: EvaluateTriggers

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


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


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

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

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

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

</Result>

Permissions: Email Triggers

Exceptions: None

Chapter 2 - Web Services Data Web Service reportdata.asmx



Web Service reportdata.asmxThis Web Service exposes memorized reports.

Memorized Reports

Method Call: GetMemorizedReports

Description: Get the memorized reports for a given project.




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

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

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

</Report></Reports>

Permissions: View Reports

Exceptions: None




Method Call: DeleteMemorizedReport

Description: Delete the given memorized report.


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


N/A

Permissions: Delete Reports

Exceptions: None




Method Call: CloneReport

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


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

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

report reportDescription (string) An optional description of

the report


intReturns: The new report ID

Permissions: Create Reports

Exceptions: None




Method Call: CreateSharedReport

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


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

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

report reportDescription (string) An optional description of

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

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

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


intReturns: The report ID of the new report.

Permissions: Create Reports

Exceptions: None




Method Call: GetMemorizedReportSharing

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




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

<Report><User id="ID" />

</Report>


Exceptions: None




Method Call: SetMemorizedReportSharing

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


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.


N/A

Permissions: Edit Reports

Exceptions: None




Method Call: GetMemorizedReportFilter

Description: Returns an XML representation of the filter for a memorized report. The format (shown below) is the same as used for GetSurveyDataEx. The same filter will appear as part of the report XML returned by GetMemorizedReports. If there is no filter, it will return a blank CriteriaCollection.




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 = != < > <= >=


Exceptions: None




Method Call: SetMemorizedReportFilter

Description: Change the filter for a memorized report. The format is the same as returned by GetMemorizedReportFilter.


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.


N/A

Permissions: Edit Reports

Exceptions: None




Report Users

Method Call: GetReportingUsers

Description: Get a list of users authorized to view reports. The users passed to SetMemorizedReportSharing must come from the list.


None


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

<Users><User id="ID">

<username>USERNAME</username><displayname>DISPLAY NAME</displayname>

</User></Users>

Permissions: View Users

Exceptions: None

Chapter 2 - Web Services Data Web Service paneldata.asmx



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

Add/Modify/Delete Panelists

Method Call: AddPanelist

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


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

characters lastname (string) Last name; maximum 255

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

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

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

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


intReturns: The new panelistid (or the existing one, in case of an update)

Permissions: Create Members

Exceptions: None




Method Call: RemovePanelist

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


panelistID (int) The panelist ID


N/A

Permissions: Delete Members

Exceptions: None




Method Call: SetExternalId

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


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


N/A

Permissions: Edit Members

Exceptions: None




Find Panelists

Method Call: GetPanelistCount

Description: Return the number of defined panelists.


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


intReturns: The count

Permissions: View Members

Exceptions: None




Method Call: FindPanelist

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


key (string) The external ID to search for


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


Exceptions: None




Method Call: FindPanelistsLike

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


name (string) The target name


int[]Returns: An array of integer panelist IDs


Exceptions: None




Method Call: GetPanelistList

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


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


int[]Returns: An array of integer panelist IDs


Exceptions: None




Method Call: GetPanelistData

Description: Get basic information about a set of panelists.


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

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

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


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

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

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

</Panelist></Panelists>


Exceptions: None




Master Panel Data

Method Call: GetPanelistInformation

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


panelistID (int) The panelist ID


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


Exceptions: None




Audit Panelists Actions

Method Call: GetPanelistActions

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


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


DataSetReturns: A DataSet: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconXMLDataSet.asp 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




Saved Panel Filters Query

Method Call: AddPanelFilter

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


filterName (string) The name of the saved panel filter. filterXml (string) The filter in the same format returned

by GetPanelFilter.


filterId(int)

Permissions: Edit Panel Filters

Exceptions: None




Method Call: GetPanelFilterCount

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


status (int)0 = shared filters1 = private filters


intReturns: The number of saved panel filters

Permissions: View Panel Filters

Exceptions: None




Method Call: GetPanelFilterList

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


status (int)0 = shared filters1 = private filters


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

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

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

<Filters>


Exceptions: None




Method Call: GetPanelFilter

Description: Returns a representation of a particular panel filter.


filterid (int) The ID of the saved panel filter


XmlNodeReturns: An XML representation, as follows:

<CommunityFilternumbercompleted="NUMBER" numbercompletedcompare="COMPARE" lastcompleteddays="# DAYS" lastcompletedcompare="COMPARE" lastinviteddays="# DAYS" lastinvitedcompare="COMPARE" createddays="# DAYS" createdcompare="COMPARE" portalstatus="Undefined|NotInvitedNotJoined|InvitedNotJoined|Joined"sourcetype="SOURCE" status="STATUS" soundex="true|false">

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

</CommunityFilter>Status is one of:

0 = active 1 = suspended 2 = deleted

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

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





Exceptions: None

Method Call: GetPanelFilter




Method Call: SetPanelFilter

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

CAUTION Be very careful, as no validation is done.


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

returned by GetPanelFilter.


N/A


Exceptions: None




Method Call: SharePanelFilter

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


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

others in the workgroup


N/A


Exceptions: None




Add/Remove Panel Filters

Method Call: RemovePanelFilter

Description: Removes a panel filter.

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




N/A

Permissions: Delete Panel Filters

Exceptions: None




Evaluate Filters (Saved or Ad Hoc)

Method Call: EvaluateSavedPanelFilter

Description: Evaluates the given saved panel filter.




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

Permissions: View Member Filters and View Members

Exceptions: None




Method Call: EvaluateSimplePanelFilter

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


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

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

value (string) The value to test against


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


Exceptions: None




Method Call: EvaluateXmlPanelFilter

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


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


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


Exceptions: None




Profile Data

Method Call: GetProfileInformation

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

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


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


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

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

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

</Row></Rows

Permissions: View Panel Profiles

Exceptions: None




Method Call: SetProfileInformation

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


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

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


N/A

Permissions: Edit Member Profiles

Exceptions: None




Authorized Surveys

Method Call: GetSurveysForPanelist

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


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

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

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

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

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


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

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

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

</Survey></Surveys>

Permissions: View Members and View Surveys

Exceptions: None




Method Call: GetSurveyStatusForPanelist

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


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


intReturns:

0 = not started1 = started but not completed9999 = completed

Permissions: View Members and View Surveys

Exceptions: None




Portal Emails

Method Call: SendPortalEmails

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


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

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


N/A

Permissions: View Members and Send Invitations

Exceptions: None

Chapter 2 - Web Services Data Web Service bulk.asmx



Web Service bulk.asmx

Method Call: BulkImportPanelists

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


panelistsXml (string)<Panelists>

<Panelist><Email>Email address (max 255)</Email><FirstName>First name (max 255)</FirstName><LastName>Last name (max 255)</LastName><Culture>Optional: Culture </Culture>(see http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx)<ExternalId>Optional: (max 255)</ExternalId>(Must be unique per panelist. Can be the key for a foreign data system; or if not specified the email address will be used.)<Status>Optional value: 'Active|Deleted'</Status><Unsubscribe>Optional value: true|false. </Unsubscribe>(Use 'true' to mark the panelist unsubscribed)<DisplayName>Display name used in the portal</DisplayName>

<Password>Password for panelist to login into VCBM</Password><Approved>DateTime</Approved><Invited>DateTime</Invited><Registered>DateTime</Registered><Reminded>DateTime</Reminded><Profile id="12345678">

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

</Panelist></Panelists>


XmlNodeReturns an XML representation, as follows:

<!-One Panelist element for every Panelist element passed in. Returned order is same as sent. Unless explicit errors are returned all data is successfully committed. If there are errors only the items that are noted should be addressed (i.e., no rollback of other data). --><Result><Panelist id="123456" />

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

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

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



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

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

</Profile></Panelist>

</Result>




Permissions: Import Panelists

Exceptions: SoapExceptions 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

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, 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 each participant the email address or panelist id plus up to three user keys will be checked, if it matches an existing participant that record will be updated otherwise a new participant will be added. For each participant node passed in one will be returned in the same order indicating success or failure of the insert or update. For success the new participant id will be returned otherwise it will be information about the error that occurred.If this is a new participant being added and there are errors with the preload data, the participant will not be authorized to take the survey. However, if this is an update to an existing record and there are preload errors, the participant will not be unauthorized.The key field for identifying a panelist is the external id. This can be the same as the email or different. If you do not specify an explicit external id, the email field is used to look in the external id field (for those customers that use email as the external id). If your external id is different from the email address that is the value you have to pass to the method.


projectId (int) A Project ID participantsXml (string)

<Participants><Participant>



<Email>Email</Email><PanelistId>Panelist Id</PanelistId><ExternalId>Panelist external Id</ExternalId>

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

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

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

</Preload></Participant>

</Participants>



<Result>

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



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

</Participant>

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

</Participant></Result>




Permissions: Import Participants



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.


projectid (int) A Project ID responseXml (string)

<Records><Record>

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

<started> DateTime </started><completed> DateTime </completed><modified> DateTime </modified>

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

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

<http_referer> Referrer </http_referer>(e.g. http://www.example.com)

<http_user_agent> Browser string </http_user_agent>

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

<remote_addr> e.g. 127.0.0.1</remote_addr><remote_host> e.g. 127.0.0.1</remote_host><last_page> Last page viewed </last_page>

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

<panelistid> Panelist Id (Panel surveys only) </panelistid><email> Email address </email><user_key1> User key 1 </user_key1><user_key2> User key 2 </user_key2><user_key3> User key 3 </user_key3>

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

(transactional surveys only)</Record>

</Records>



<Result>

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

</Result>

Method Call: BulkChangeResponses

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


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

<Records><Record id="634635537507737461">

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

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

(eg 2011-06-29T10:29:52.5711135)<culture> culture </culture>

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

(eg Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0))

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

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

<panelistid> Panelist Id </panelistid><email> Email address </email><user_key1> User key 1 </user_key1><user_key2> User key 2 </user_key2><user_key3> User key 3 </user_key3>

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

(transactional surveys only)</Record>

</Records>



<Result>

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

</Result>


Exceptions: None

Method Call: BulkChangeResponses

Method Call: BulkGetPreloadData

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


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



<PreloadData><Preload id="634665465332558180">

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

<Preload id="634665465332558181"/>



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

</PreloadData>


Exceptions: None

Method Call: BulkSetPreloadData

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


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

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

</Preload>

<Preload id="634665465332558181"/>

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

</Preload></PreloadData>



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

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

</Participant>

<Error> No record id specified. </Error>

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

</Result>

Permissions: Import Participants

Exceptions: None

Chapter 2 - Web Services Data Web Service admin.asmx



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

Add/Change/Remove Users

Method Call: AddUser

Description: Add a new user.

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


username (string) User name; max 255 characters displayname (string) Display name; max 255

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

characters


intReturns: The user ID for the added user

Permissions: Create Users

Exceptions: None




Method Call: DeleteUser

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


Userid (int) The User's ID


N/A

Permissions: System Administrator Account

Exceptions: None




Method Call: GetUserData

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


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


DataSetReturns: A DataSet (serialized data table in a System.Data.DataSet): http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconXMLDataSet.asp. See an example of the data table below.

Column Data Type

Description/Comments

USERID Int32 internal unique identifier

USERNAME String Username used to authenticate into EFM

PASSWORD String Hashed - Password

EMAIL String Email address

DISPLAYNAME String First and last name

CURR_GROUP Int32 Current EFM workgroup ID

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

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

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





LICENSE String Reserved*

STATUS Int32 User status - Reserved

DEPTID Int32 Reserved*

SETTINGS String Reserved*

LAST_SELECTION Int32 Reserved*

USER_INFO String Reserved*

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

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

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

PASS_REQ_ID Int64 Reserved*

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


Exceptions: None

Method Call: GetUserData




Method Call: GetUserInformation

Description: Returns information about a user.


userid (int) The user's ID



<User id="USER ID" group="CURRENT GROUP ID" culture="CULTURE" status="Deleted|Suspended|Active" Reviewer Status = "Standard|Reviewer|Supervised">

<Name>USER NAME</Name><Display>DISPLAY NAME</Display><Email>EMAIL</Email>

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


Exceptions: None




Method Call: SetUserInformation

Description: Change basic information about a user: name, display, email, culture, group, status.

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


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

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


N/A

Permissions: Edit Users

Exceptions: None




Method Call: ResetUserPassword

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


userid (int) The user's ID


N/A


Exceptions: None




Method Call: ChangeUserPassword

Description: Change the user's password.


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


N/A


Exceptions: None




Method Call: GetUserInfoByEmail

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


emailAddress (string) User's email address



<User id="USER ID" group="CURRENT GROUP ID" culture="CULTURE" status="Deleted|Suspended|Active" reviewerStatus="Standard|Reviewer|Supervised">




Exceptions: None




Method Call: GetUserInfoByUsername

Description: Get a user's information by username


username (string) The user's username



<User id="USER ID" group="CURRENT GROUP ID" culture="CULTURE" status="Deleted|Suspended|Active" reviewerStatus="Standard|Reviewer|Supervised">




Exceptions: None




Workgroup Access

Method Call: GetWorkgroupList

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


None



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

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

</Workgroup></Workgroups>


Exceptions: None




Method Call: GetWorkgroupUsers

Description: Get a list of users in a Workgroup.


groupId (int) The Workgroup ID


intReturns: An array of integer user IDs


Exceptions: None




Method Call: AddUserToWorkgroup

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


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


N/A


Exceptions: None




Method Call: DeleteUserFromWorkgroup

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




N/A


Exceptions: None




Method Call: GetWorkgroupRoleList

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


groupId (int) The Workgroup ID



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

</Roles>


Exceptions: None




Method Call: GetWorkgroupRole

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




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


Exceptions: None




Method Call: SetWorkgroupRole

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


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


N/A


Exceptions: None




Method Call: SetUserWorkgroup

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


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


N/A


Exceptions: None

C h a p t e r 3

Survey Event Handler

The Survey Event Handler1 provides the ability for the survey engine to call a Web Service2 based upon 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.

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)

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 name and callingparameters. It contains 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 Web site: http://en.wikipedia.org/wiki/Web_service

Chapter 3 - Survey Event Handler Requirements



You have the ability to configure what "event" triggers the survey engine will call out to the Web Service (like survey start or end) as well as the amount of response data sent in the call. In addition, you also have the ability to specify a custom token which ensures that the Web service is called only from your survey.

Requirements1 EFM API License.

2 You must 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 which supports XML Web Services may be used.We have provided an ASP.NET Web site application written in C# that defines the Web method and the structures passed back and forth from the survey engine. In addition, a Web Services Description Language (WSDL) file is supplied that defines those structures.

Chapter 3 - Survey Event Handler Using the Visual Studio Web Site Provided



Using the Visual Studio Web Site ProvidedYou can use the Visual Studio Web site that is provided as a basis for developing your own Web site or you can use it as an example for creating a new website.

Steps1 Open the contents of the .zip file in Visual Studio as a C# file based Web site.

Visual Studio Interface - Survey Engine Services

Chapter 3 - Survey Event Handler Using the Visual Studio Web Site Provided



2 The class SurveyEventService.asmx contains the definition of the Web method called from the survey engine. See below:/// <summary>/// This file defines the Web method that is called by the survey engine./// </summary>[WebService(Namespace = "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 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 named /// WebSurveyEventHandler./// </summary>/// <param name="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]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 (e.g., eventarguments).

Chapter 3 - Survey Event Handler Creating a New Web Service



Creating a New Web ServiceYou can create a new Web Service that can be called by the survey engine at runtime. To create a new Web service file:

1 Navigate to "Add New Item" dialog.

2 Select Web Service.

3 Enter a name in the "Name:" text field.

4 Select the Language (for this example it is Visual C# - see image below).

5 Select Add.

Add New Item dialog

NOTE Select File>New>File to get to Add New Item.

Chapter 3 - Survey Event Handler Creating a Web Method



Creating a Web Method1 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;

}

2 At this point the Solution Explorer will look like this:

Solution Explorer window

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 3 - Survey Event Handler Using the WSDL file



Using the WSDL fileYou can also use the WSDL3 file that is provided to generate class structures for the values passed back and forth in the Web method call. The Web method must have the following signature:

/// <summary>/// This is the Web method that is called from the survey engine at runtime./// It must exactly match this signature./// </summary>[WebMethod]public WebServiceResponse WebSurveyEventHandler(SurveyEventArgs eventArgs)

3 WSDL is an XML format for describing network services as a set of endpoints operating on messagescontaining either document-oriented or procedure-oriented information. The operations and messages aredescribed abstractly, and then bound to a concrete network protocol and message format to define an end-point. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible toallow description of endpoints and their messages regardless of what message formats or network protocolsare used to communicate. Reference: http://www.w3.org/TR/wsdl

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 (e.g., eventarguments).

Chapter 3 - Survey Event Handler Survey Event Handler Configuration



Survey Event Handler ConfigurationThe Web Service Survey Event Handler enables you to use your own Web service to handle survey events.

NavigationSelect your survey from the Surveys/My Surveys page (see image below). The Design page displays. Click "Advanced" from the side panel and select "Web Services Event Handler" from the options.

Surveys/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.




Web Services Event Handler




Web Service dialog example

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 (V7)1 Open the EFM V7 Application.

2 Select the Surveys tab and a survey from your "My Surveys" list and the Design page will display.

3 Select Advanced from the side panel and click "Web Services Event Handler" from the Options pane. The Survey Event Handler dialog displays.




Survey Event Handler dialogThis 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.




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




Authentication OptionalThe 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 image below for the location of the Authentication Token.

Authentication Token field

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 3 - Survey Event Handler Survey Event Descriptions



Survey Event Descriptions

Survey StartSelect this option to call the Web service when participants click the link to begin the survey. Only preloaded data is sent from the survey engine to the Web service during this event.

Page SubmitUse Page Submit to send survey data while the survey participant is going from page to page in the survey. Options in the Page Submit drop-down menu include:

None (fast)

Only the Responses Submitted for the Page (average)

All non-empty Responses for the Survey (slow)

Survey EndSelect this option to call the Web service when participants complete the survey. All data is sent from the survey engine to the Web service during this event. This is typically either from clicking the Submit button or a branch to End option.

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 3 - Survey Event Handler Survey Event Descriptions



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 3 - Survey Event Handler Sample Survey Event Handler



Sample Survey Event HandlerIncluded along with the starter project is a sample Web Service Survey Event Handler. It is a simple code validation survey meant to showcase basic usage of the survey event process.The first page of the survey has a single entry field. If you enter the secret code of "1234" you pass normally into the survey. If you click "Next" without entering anything the HTML replacement feature is used to display an error message. If you enter a wrong code you are redirected to a custom URL.

Steps for Using the Sample Code Provided1 Compile and run the Vovici.SEWS.Demo solution. Note where the Web site 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 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 3 - Survey Event Handler Sample Survey Event Handler



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 4

Hierarchical Questions Web Service1

Setup1 Navigate 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 New Hierarchical Question dialog opens.

3 Enter your Question Heading text and add your question to the Question Text area.

4 Create a List Caption (optional).

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 4 - Hierarchical Questions Web Service Setup



5 Select the Web Service tab. See image below.

Web Service tab6 Type in the URL of your Web Service into the Web Service URL text box field.

7 Type in the Step Labels (one per line, for example, Make, Model, and Year).

8 Click OK to confirm or Cancel to terminate the action.

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 4 - Hierarchical Questions Web Service Adding a Hierarchical Question to Your Survey



Adding a Hierarchical Question to Your Survey

Hierarchical Questions are added to your survey through the Add drop-down menu within the Design page. Select "Add from Library" from the Add drop-down menu and navigate to the Hierarchical Questions tab. Select the hierarchical question you want to add and click OK. See images below.

Design/ Add from Library

Chapter 4 - Hierarchical Questions Web Service Example of Using a Web Service for Hierarchical Questions



Hierarchical Questions tab

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 then goes to the external database and 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's list. Again 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 will continue 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 4 - Hierarchical Questions Web Service Sample Web Service



Sample Web ServiceIncluded along with the starter project is a sample Web Service Hierarchical Question. It is a simple code sample meant to illustrate the basic structure of the hierarchical question web service. In the .zip file provided there are two sample files - HierarchicalListService.asmx and TestHierarchicalListService.asmx. See image below.

Zip file contentsThe sample code below 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 Vovici.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">/// <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>




[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 as shown in the image below.

Hierarchical Questions/Question tab




3 Fill in the Web Service tab as shown in the image below.

Web Service tab

4 Create a new survey.

NOTE Change the Web Service URL field to point to the Web Service on your server.




5 From within the Design page, select Library Question.

Library Question6 Select the Hierarchical Questions tab.

7 Select Country & State/Province.

8 Click OK.

9 Click Test to publish the survey.




10 The survey will display and will look similar to the image below.

Testing Your Survey

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.

AAddPanelFilter . . . . . . . . . . . . . . . . . . 116AddPanelist . . . . . . . . . . . . . . . . . . . . 106AddResponse . . . . . . . . . . . . . . . . . . . 49AddUser . . . . . . . . . . . . . . . . . . . . . 145AddUserToWorkgroup. . . . . . . . . . . . . . . 157AuthorizeMultiplePanelistsForSurvey . . . . . . . 56AuthorizePanelistForSurvey . . . . . . . . . . . . 57AuthorizeParticipantForSurvey . . . . . . . . . . 58

BBulkAuthorizeParticipants . . . . . . . . . . . . . 135BulkChangeResponses . . . . . . . . . . . . . . 141BulkGetPreloadData . . . . . . . . . . . . . . . 143BulkImportPanelists . . . . . . . . . . . . . . . 132BulkImportResponses. . . . . . . . . . . . . . . 138BulkSetPreloadData. . . . . . . . . . . . . . . . 144

CChangeMultipleResponses . . . . . . . . . . . . 48ChangeResponse . . . . . . . . . . . . . . . . . 47ChangeUserPassword . . . . . . . . . . . . . . . 152ClearResponse . . . . . . . . . . . . . . . . . . 53CloneReport . . . . . . . . . . . . . . . . . . . 99CreatePanelProfile . . . . . . . . . . . . . . . . 18CreateSharedReport . . . . . . . . . . . . . . . 100CreateSurveyProject . . . . . . . . . . . . . . . 17

DDeleteMemorizedReport . . . . . . . . . . . . . 98DeleteParticipant . . . . . . . . . . . . . . . . . 52DeleteProject . . . . . . . . . . . . . . . . . . . 41DeleteUser . . . . . . . . . . . . . . . . . . . . 146DeleteUserFromWorkgroup . . . . . . . . . . . . 158

EEmailLiveResultsReport . . . . . . . . . . . . . . 82EmailResultsReport . . . . . . . . . . . . . . . . 83EmailResultsReportToRespondent . . . . . . . . 84EvaluateSavedPanelFilter . . . . . . . . . . . . . 124EvaluateSimplePanelFilter . . . . . . . . . . . . 125EvaluateTriggers . . . . . . . . . . . . . . . . . 96EvaluateXmlPanelFilter . . . . . . . . . . . . . . 126

FFindPanelist. . . . . . . . . . . . . . . . . . . . 110FindPanelistRecord . . . . . . . . . . . . . . . . 69FindPanelistsLike . . . . . . . . . . . . . . . . . 111FindPanelistsRecord. . . . . . . . . . . . . . . . 70FindParticipantRecord. . . . . . . . . . . . . . . 71FindParticipantsRecord . . . . . . . . . . . . . . 72

GGetAuthorizedParticipantCount . . . . . . . . . . 59GetCampaignHistory . . . . . . . . . . . . . . . 80GetColumnList. . . . . . . . . . . . . . . . . . . 31GetCommonSurveyList . . . . . . . . . . . . . . 15GetCustomPropertiesForSurveys . . . . . . . . . 26GetDataMap . . . . . . . . . . . . . . . . . . . . 28GetExportDataMap . . . . . . . . . . . . . . . . 29GetFrequencyInformation . . . . . . . . . . . . . 54GetInvitationTemplate. . . . . . . . . . . . . . . 74GetInvitationText . . . . . . . . . . . . . . . . . 73GetMemorizedReportFilter . . . . . . . . . . . . 103GetMemorizedReports . . . . . . . . . . . . . . . 97GetMemorizedReportSharing . . . . . . . . . . 101GetPanelFilter . . . . . . . . . . . . . . . . . . 119GetPanelFilterCount . . . . . . . . . . . . . . . 117GetPanelFilterList . . . . . . . . . . . . . . . . 118GetPanelistActions. . . . . . . . . . . . . . . . 115GetPanelistCount . . . . . . . . . . . . . . . . 109GetPanelistData . . . . . . . . . . . . . . . . . 113GetPanelistInformation . . . . . . . . . . . . . 114GetPanelistList . . . . . . . . . . . . . . . . . 112GetParticipantData . . . . . . . . . . . . . . . . 60GetParticipantDataEx . . . . . . . . . . . . . . . 62GetParticipantDataPaged . . . . . . . . . . . . . 64GetParticipantInformation . . . . . . . . . . . . . 66GetPreloadData . . . . . . . . . . . . . . . . . . 50GetProfileInformation . . . . . . . . . . . . . . 127GetProfileList . . . . . . . . . . . . . . . . . . . 16GetProjectInformation . . . . . . . . . . . . . . . 39GetPublishedQuestionnaire . . . . . . . . . . . . 20GetQuestionnaire . . . . . . . . . . . . . . . . . 19GetQuestionnaireVersions . . . . . . . . . . . . . 22GetReportDataMap . . . . . . . . . . . . . . . . 30GetReportingUsers . . . . . . . . . . . . . . . 105GetResponse . . . . . . . . . . . . . . . . . . . 46GetResponseCount . . . . . . . . . . . . . . . . 42GetStatistics. . . . . . . . . . . . . . . . . . . . 55GetSurveyCustomProperties. . . . . . . . . . . . 25GetSurveyData . . . . . . . . . . . . . . . . . . 43GetSurveyDataEx . . . . . . . . . . . . . . . . . 44GetSurveyDataPaged . . . . . . . . . . . . . . . 45GetSurveyEventHandler . . . . . . . . . . . . . . 91GetSurveyFieldInformation . . . . . . . . . . . . 34GetSurveyInformation. . . . . . . . . . . . . . . 32GetSurveyList . . . . . . . . . . . . . . . . . . . 14GetSurveysForPanelist . . . . . . . . . . . . . 129GetSurveyStatusForPanelist . . . . . . . . . . . 130GetSurveyTranslations . . . . . . . . . . . . . . 93GetUnsubscribedStatus . . . . . . . . . . . . . . 85GetUserData . . . . . . . . . . . . . . . . . . 147GetUserInfoByEmail . . . . . . . . . . . . . . . 153GetUserInfoByUsername . . . . . . . . . . . . 154GetUserInformation . . . . . . . . . . . . . . . 149GetWorkgroupList . . . . . . . . . . . . . . . . 155GetWorkgroupRole . . . . . . . . . . . . . . . 160GetWorkgroupRoleList. . . . . . . . . . . . . . 159GetWorkgroupUsers . . . . . . . . . . . . . . . 156

I n d e x

Index

Index



LLogin . . . . . . . . . . . . . . . . . . . . . . . 12Logout . . . . . . . . . . . . . . . . . . . . . . 13

PPing. . . . . . . . . . . . . . . . . . . . . . . . 11

RRemovePanelFilter . . . . . . . . . . . . . . . . 123RemovePanelist. . . . . . . . . . . . . . . . . . 107RepublishProject . . . . . . . . . . . . . . . . . 37ResetUserPassword . . . . . . . . . . . . . . . . 151RevertQuestionnaire . . . . . . . . . . . . . . . 24

SSendInvitations . . . . . . . . . . . . . . . . . . 79SendInvitationsEx . . . . . . . . . . . . . . . . 78SendPortalEmails . . . . . . . . . . . . . . . . . 131SetEndPageURL. . . . . . . . . . . . . . . . . . 38SetExternalId . . . . . . . . . . . . . . . . . . . 108SetInvitationStatus . . . . . . . . . . . . . . . . 77SetInvitationTemplate . . . . . . . . . . . . . . 75SetMemorizedReportFilter . . . . . . . . . . . . 104

SetMemorizedReportSharing . . . . . . . . . . 102SetMultipleInvitationStatus . . . . . . . . . . . . 76SetPanelFilter . . . . . . . . . . . . . . . . . . 121SetParticipantInformation . . . . . . . . . . . . . 68SetPreloadData . . . . . . . . . . . . . . . . . . 51SetProfileInformation . . . . . . . . . . . . . . 128SetProjectInformation . . . . . . . . . . . . . . . 40SetQuestionnaire . . . . . . . . . . . . . . . . . 21SetSurveyCustomProperties . . . . . . . . . . . . 27SetSurveyEventHandler . . . . . . . . . . . . . . 92SetSurveyTranslations . . . . . . . . . . . . . . 94SetUserInformation . . . . . . . . . . . . . . . 150SetUserWorkgroup . . . . . . . . . . . . . . . 162SetWorkgroupRole . . . . . . . . . . . . . . . 161SharePanelFilter . . . . . . . . . . . . . . . . . 122

UUnsubscribeListAdd . . . . . . . . . . . . . . . . 86UnsubscribeListRemove . . . . . . . . . . . . . . 87UpdateBorrowedQuestions . . . . . . . . . . . . 88UpdateBorrowedQuestionsForRespondent . . . . . 89

VValidateSingleResponse . . . . . . . . . . . . . . 90

© 2013 Verint Systems Inc. All Rights Reserved Worldwide. Confidential and Proprietary Information of Verint Systems Inc.

The contents of this material are confidential and proprietary to Verint Systems Inc. and may not be reproduced, published, or disclosed to others without express authorization of Verint Systems Inc.

Verint Global Headquarters330 South Service RoadMelville, NY 11747 USA

[email protected]

www.verint.com

web services technical guide 7 - efmhelp.netefmhelp.net/.../web_services_technical_guide_7.0.pdf ·...

Documents