Survey (Managed Code Sample)

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

The Survey sample is an end-to-end outbound-calling application that accepts voice and dual tone multi-frequency (DTMF) input. The application retrieves phone numbers from a database table of numbers to dial and initiates outbound calls. When a called party answers, the application invites the person to participate in a short survey. The user can opt out of taking the survey, schedule the call for a later date, or accept the call. The application then asks the called party up to nine questions and logs the answers to a database table. This application:

• Demonstrates the function of an end-to-end application that initiates outbound calls and recognizes a variety of input from the called party.
• Provides developers with a flexible application that they can configure and use as a model for developing outbound-calling voice and DTMF applications.

Featured Highlights

• Support for the global commands Help, Repeat, Cancel, Next, and Previous
• Response-dependent call flow logic (that is, questions that are asked based only on the value of a user's previous response)
• Use of a MakeCallActivity to initiate an outbound call
• Use of a RecordAudioActivity to record user input
• Playback of audio recorded with a RecordAudioActivity

Initial Setup

The Survey sample uses an XML file for configuration information. This file, Configuration.xml, is located in the Samples\Workflow\Survey\Survey\ directory of the Speech Server installation directory. Configuration.xml contains one configurable parameter, as described in the following table.

Configuration.xml Parameter	Description
connection-string	Specifies the connection string for the SQL??Server database containing the SurveyCallList and SurveyResults tables. The default connection string uses a local SQLExpress database.

The Survey application uses a SQL??Server database for storing call list and survey result data tables. Typically, a local version of SQL??Server is used for the Survey application tables. However, an alternate server can be specified by modifying the connection-string parameter in Configuration.xml.

To create the necessary database and tables, run InitializeDatastore.bat in the Samples\Workflow\Survey\Survey\DatabaseScripts\ directory of the Speech Server installation directory. This creates the SpeechServer database, the SurveyCallList table, and the SurveyResults table.

Running the Application

The Survey reference application can be run in Visual Studio 2005 using F5 debugging.

To initiate a call to the application

1. In the Samples\Workflow\Survey\ directory of the Speech Server installation directory, open the solution file.

2. In Solution Explorer, expand Survey, and then expand Grammars.

3. Double-click AnnualIncome.gbuilder.

4. In the upper-left corner of the AnnualIncome.gbuilder page, click Compile Language.

5. Repeat steps 3 and 4 for HelpCommand.gbuilder, MaritalStatus.gbuilder, MorningAfternoon.gbuilder, NavigationCommands.gbuilder, and RepeatCommand.gbuilder.

6. To start debugging, press F5.

7. In the Voice Response Debugging Window dialog box, click the SIP Phone tab, and then click Outbound Trigger.

8. On the Survey Application Trigger Page, click Send Trigger.

   The page queries the SurveyCallList table for the next number to call and sends a trigger to the application. Observe the updated Trigger Result and URI request information about the Survey Application Trigger Page and notice that the URI shows the outbound number that the application calls.

9. In the Incoming Call Control dialog box, click Answer.

10. When prompted to enter input, click Start Recording in the User Input pane in the Voice Response Debugging Window dialog box, and then say your response.

11. When the recognized phrase appears in one of the text boxes on this pane, click Submit.

    Alternatively, you can use the Text Input area to enter input using the keyboard.

Note

Because the survey has two prompts that record user input, a microphone is required to take the entire survey.

The logic of the Survey reference application is complex enough that a single, step-by-step explanation of all the decision points and responses is impractical. Instead, the following sections outline three scenarios using the Survey application. These scenarios illustrate the majority of the application's features.

User Scenario 1: Accepting the Call and Taking the Survey

To accept the call and take the survey

1. Initiate an outbound call, and then accept the call as described in the Running the Application procedure.

   The application executes the welcomeStatementActivity and says "This is a call from Trey Research. We'd like you to participate in a brief survey. It'll take three to five minutes to complete." It then starts the askParticipationQuestionAnswerActivity and asks "Are you willing to participate?"

2. Click Start Recording, and then say "Yes."

3. When your response appears in the debugger, click Submit.

   The application executes the surveyInstructionsStatementActivity and says "Great! You can speak your response after I ask each question. You can also skip through the survey by saying next, previous, or repeat. And if you get stuck, you can always say help. Alright? Let's get started." It then starts the askBirthYearQuestionAnswerActivity and asks "What year were you born in?"

4. Click Start Recording, and then say "Nineteen sixty eight."

5. When your response appears in the debugger, click Submit.

   The application plays the birth year as "Nineteen sixty eight. Thanks." It then executes the askMaritalStatusQuestionAnswerActivity and asks "Are you married, single, or divorced?"

6. Click Start Recording, and then say "Single."

7. When your response appears in the debugger, click Submit.

   The application plays the response as "Got it. Single." It then executes the askHouseholdSizeQuestionAnswerActivity and asks "How many people live in your household?"

8. Click Start Recording, say "Next," and then click Submit to skip this question.

   The application executes the askAnnualIncomeQuestionAnswerActivity. It asks "What is your annual household income?" followed by a list of options one through six that are tied to annual income ranges.

9. Click Start Recording, and then say "Four."

10. When your response appears in the debugger, click Submit.

    The application responds with "Got it" and executes the askMoviesAttendanceQuestionAnswerActivity. It asks "On average, how many movies do you see in a theater each year?"

11. In the Voice Response Debugging Window dialog box, click the SIP Phone tab, and then enter 20 using the keypad.

    The application responds with "Alright. Twenty" and executes the recordLastMovieRecordAudioActivity. It says "Now I want to record your answer. After the tone, please say the name of the last movie you saw in a movie theater."

12. Click Start Recording, and then say your response.

    The application plays the recorded audio to you, followed by "Got it." It then executes the updateCallRecordAsCompletedCodeActivity to mark the call list record status as complete and executes the goodbyeStatementActivity. It says "Thank you for your time. Goodbye." and ends the call.

When the call completes, review the contents of the SurveyCallList table. The record for the number called now has a status of COMPLETED. Review the content of the SurveyResults table and see the stored results of the completed call. The table does not contain an answer for question three because this question was skipped. Open the audio file directory to see the audio files that are saved from the call.

User Scenario 2: Declining the Survey and Rescheduling

To decline the survey and reschedule

1. Initiate an outbound call, and then accept the call as described in the Running the Application procedure.

   The application executes the welcomeStatementActivity and says "This is a call from Trey Research. We'd like you to participate in a brief survey. It'll take three to five minutes to complete." It then starts the askParticipationQuestionAnswerActivity and asks "Are you willing to participate?"

2. Click Start Recording, and then say "No."

   The application responds with "Okay." It then executes the askTakeLaterQuestionAnswerActivity and asks "Would you be willing to take the survey in the future at a time more convenient for you?"

3. Click Start Recording, and then say "Yes."

   The application responds with "Great, let's schedule the call." It then executes the askDayQuestionAnswerActivity, which asks "Which day in the coming week would you like us to call you back?"

4. Click Start Recording, and then say "Friday."

   The application repeats the recognized day. It then executes the askMorningOrAfternoonQuestionAnswerActivity and asks "And, is morning or afternoon better?"

5. Click Start Recording, and then say "Morning."

   The application executes the callbackScheduleStatementActivity and says "Got it. Morning." It then says "Thank you for your time. Goodbye." and ends the call.

When the call completes, review the contents of the SurveyCallList table. The record for the number called has an updated NextCallTime value. The call time reflects the day and time-of-day information entered during the call. The record has a status of READY, but calls are not initiated to the number again until after the NextCallTime value.

User Scenario 3: Declining the Survey Without Rescheduling

To decline the survey without rescheduling

1. Initiate an outbound call, and then accept the call as described in the Running the Application procedure.

   The application executes the welcomeStatementActivity and says "This is a call from Trey Research. We'd like you to participate in a brief survey. It'll take three to five minutes to complete." It then starts the askParticipationQuestionAnswerActivity and asks "Are you willing to participate?"

2. Click Start Recording, and then say "No."

   The application responds with "Okay." It then executes the askTakeLaterQuestionAnswerActivity and asks "Would you be willing to take the survey in the future at a time more convenient for you?"

3. Click Start Recording, and then say "No."

   The application responds with "Thank you for your time. Goodbye." and ends the call.

When the call completes, review the contents of the SurveyCallList table. The record for the number called has a status of DECLINED. The application does not make any further calls to this number.

Remarks

This code sample is intended to demonstrate specific Speech Server features. It does not necessarily reflect best practices with respect to security and privacy. You should carefully review any code that you deploy in production for potential security risks and privacy issues.