How to: Confirm Responses

Article
08/18/2014

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.

This is the sixth of seven tutorial topics covering tools in Speech Server. This section of the tutorial uses Speech Control Editor, which is the all-purpose tool for assembling a speech-enabled Web application in Microsoft Visual Studio 2005. Speech Control Editor manipulates ASP.NET Speech Controls that produce Speech Application Language Tags (SALT) and JScript on the client. Developers use Speech Control Editor to specify prompts to speak to the user, recognize answers using grammars, and confirm the answers.

For reference information about Speech Prompt Editor, see Develop Prompts with Speech Prompt Tools. For specifics about QA controls, see Speech Controls in SALT Voice Response Application Projects. For more information about the SpeechControlSettings control, see Design Dialog Flow.

This sequence of tutorials demonstrates how to build a simple Web-based voice response application using Speech Server Developer Tools. Specifically, the tutorials demonstrate building a Start page of an imaginary pizza ordering service for use by a telephony SALT client.

The procedures for creating the pizza ordering service application build on each other. Performing the procedures in sequence is therefore important.

Confirming the Responses

The application needs to confirm the responses that it has recognized to ensure that it has not recognized some phrase incorrectly and to give the caller a chance to correct the error if it exists. In this application, if the caller indicates that the information is not correct, the dialog flow returns to the first prompt for a response from the user, SizeQA, and repeats all the prompts again. Sample and Reference Applications demonstrates other confirmation strategies, as well as other dialog designs.

To add the confirmation QA control

In the Toolbox, click the Speech tab, and then drag and drop a QA control onto PizzaPanel.
Right-click the QA control, and then click Property Builder.
In the ID box, change the name of the control to ConfirmQA.
Select Voice Output, and then click PlayOnce.

This specifies that the application plays this prompt only once while the tutorial application is first being tested.

To add semantic values to ConfirmQA

In the tree view pane on the left, select Input.
In the right pane, click Add Existing Grammar.
In Add Existing Grammar, click Browse next to the Grammar Path box.
In the Project folders pane, click Grammars, and then double-click PizzaOrder.grxml in the Contents of folder pane.
In Add Existing Grammar, click Browse in the Active Rule section.
In Rule Browser, select Confirm in the Public and Root Rules list, and then click Select Active Rule.
In Add Existing Grammar, click OK.
In ConfirmQA Properties, click XPathTrigger Sample Sentence Tool.
In the Sample speech input box, type Yes, and then click Go.
On the Answers tab, double-click the first SemanticItem box, and then select siYes.
In the corresponding XPathTrigger box, select SML/Yes.

This step binds the semantic information in SML/Yes to the siYesSemanticItem in SemanticMap.
In the Sample speech input box, type No, and then click Go.
On the Answers tab, double-click the next SemanticItem box, and then select siNo.
Click the corresponding XPathTrigger box, and then select SML/No.

This step binds the semantic information in SML/No to the siNoSemanticItem in SemanticMap.
Click OK.
Right-click the Default.aspx tab, and then select Save Default.aspx.

Playing Back the Caller's Responses as a Prompt

To play back the caller's responses as a prompt, it is necessary to create a prompt function. This prompt function extracts the text from the semantic items that were filled when the caller responded to previous prompts. It takes the size and phone number text from siSize and siPhoneNumberText and then concatenates them with some phrases in the prompt database to produce a prompt that is not in the prompt database. This requires a small function to extract the contents of the semantic items from the SemanticMap control. For more information about prompt functions, see Prompt Projects and Databases.

To create the prompt function file

Right-click the ConfirmQA control, and then click Property Builder.
In the tree view pane on the left, click Voice Output.
In the Prompt options section, clear the BargeIn check box.

In this case, the caller needs to listen to the entire prompt to be able to decide whether the order details and the telephone number are correct.
Click Prompt Function.
Click the Manage this page's prompt function script files link.
In the Manage 'Default.aspx' Prompt Function Script Files dialog box, select New.
In the New Prompt Function Script File dialog box, enter PizzaOrder in the File name box.
Click Save, and then click OK.
In the list under Choose prompt function or <New???> from the dropdown list below, select New.

The New Prompt Function dialog box appears, with PizzaOrder.pf indicated as the prompt function file and ConfirmQA_prompt as the prompt function.
Click Apply.

To create the prompt function

In ConfirmQA Properties, click Edit prompt function file.
In the message box, click OK.
In the table of parameters, select the row under the History parameter, and then double-click the cell under Parameter Name.
Type the following parameter name: sPhoneNumberText.
Double-click the cell under Validation Value.
In the Validation Values dialog box, enter "four two five five five five zero nine zero zero" (with the quotation marks).

In a pass through the solution to validate prompts, this value is used.
Click OK.
Double-click the cell under Runtime Value, and then enter the following function call: GetSIValue(siPhoneNumberText).

In a subsequent step, you will write this function in the HTML on Default.aspx.
Similarly, enter the following items in the table, with the validation values one per line:

Parameter Validation Value Runtime Value

sSize

"large," "medium," "small"

GetSIValue(siSize)
Copy the following function body, paste it into a plain text editor, copy it from the plain text editor, and then paste it into the function ConfirmQA_prompt_inner box, overwriting the default function body.
```
{
    var sConfirmPromptStart = "You ordered a ";
    var sConfirmPromptMid = " pizza, and your telephone number is ";
    var sConfirmPromptEnd = " Is that correct?";
    var sPrompt = "";

    sPrompt = sConfirmPromptStart + sSize + " " + sConfirmPromptMid;
    sPrompt = sPrompt + sPhoneNumberText + sConfirmPromptEnd;
    return(sPrompt);
}
```
Note

The spaces around the strings in the function body are important. If they are not present, the text in the strings is concatenated with the semantic items, and in most cases, the prompt database does not have recorded audio to match. In that case, the text-to-speech (TTS) engine plays the prompts.
Right-click the PizzaOrder.pf tab, and then click SavePizzaOrder.pf.

Parameter	Validation Value	Runtime Value
sSize	"large," "medium," "small"	GetSIValue(siSize)

The prompt function needs to retrieve the semantic items from the SemanticMap and set its parameters equal to those values. The following JScript function in the HTML on Default.aspx retrieves the value of the SemanticItem that it gets as a parameter. This new function is called by the ConfirmQA_prompt function, which was added in the previous section of this topic. It is enclosed in CDATA tags so the SALT interpreter does not try to interpret it.

To retrieve the semantic values

Click the Default.aspx tab.
At the bottom of the design canvas, click Source.

The HTML view of Default.aspx opens in a source editor.
Copy the following script element, paste it into a plain text editor, copy it from the plain text editor, and then paste it into the source editor just above the opening <form> tag of the HTML.
```
<SCRIPT>
    // <![CDATA[
    function GetSIValue(theSI) {
        return(theSI == null ? null : theSI.value);
    }
    // ]]>
</SCRIPT>
```
Right-click the Default.aspx tab, and then click Save Default.aspx.

Dropping ConfirmQA onto the PizzaPanel put it last in the default execution order for added QA controls. ConfirmQA, however, should play before ThanksQA and therefore needs to move up in the execution order.

To set the order of ConfirmQA

Click the Default.aspx tab.
At the bottom of the design canvas, click Design.

The design canvas of Default.aspx opens.
On the View menu, click Speech Controls Outline.

The Speech Controls Outline shows the execution order of the controls in an application, and if expanded, shows additional features of the controls. In this case, some controls have Answer controls.
In Speech Controls Outline, select ConfirmQA.
At the top of the pane, click the UP ARROW once to move the control in the order between PhoneQA and ThanksQA.

To check the prompt playback

On the Build menu, click Build Solution.
On the Debug menu, point to Windows, and then click Voice Response Debugging Window.
In the Voice Response Debugging Window dialog box, accept the default digits in the Called Party and Calling Party boxes, and then click Call.

Through your headset or speakers, the application plays back the prompts in all the QA controls, one after the other, from the prompt database. To respond to prompts, click Start Recording in the Voice Response Debugging Window dialog box, and then respond to the prompt. This time, the application asks for confirmation of the information provided. It does not yet, however, take action on the semantic value of the confirmation.
Close the Voice Response Debugging Window dialog box.

Note

If the microphone is configured improperly, the results of this check can be unexpected, such as incomplete prompts or missing information in the confirmation prompt. If this happens, it might be necessary to configure the microphone.

At this point, the prompt played back by the prompt function uses the voice produced by the TTS engine. The previous section recorded all the prompts, so something new has appeared in the prompts. The next section of the tutorial, Debugging the Tutorial Application, demonstrates another method for debugging prompts and determines what happened.

Handling Confirmations

If the response to the question, "Is that correct?" is "Yes" in response to the prompt from ConfirmQA, the dialog flow simply continues to ThanksQA and the application ends.

However, if the response is "No," the application needs to take different action. In this case, the dialog flow begins again at the SizeQA prompt and continues through the prompts until the ConfirmQA prompt again. The onNotConfirmed function referred to in the OnClientChanged property of the siNo semantic item clears the values of the semantic items to which the QA controls refer. That starts the dialog flow again from the first control in the speech index order with empty semantic items. To have the prompts play again if the caller does not confirm the information, you must first clear the PlayOnce item in QA control properties.

For more information about the activation order of controls, see Dialog Controls - Activation and Confirmation.

To clear the PlayOnce properties

Right-click SizeQA, and then click Property Builder.
In the tree view pane on the left, select Voice Output.
Clear the PlayOnce check box, and then click OK.
Repeat steps 1 through 3 for PhoneQA and ConfirmQA.

To handle a negative confirmation

Right-click SemanticMap, and then click Property Builder.
In the tree view pane on the left, select siNo.
In the OnClientChanged box, type onNotConfirmed.

The script for this handler goes into the HTML on Default.aspx.
Click OK.
At the bottom of the design canvas, click Source.

The HTML view of Default.aspx opens in a source editor.
Copy the following function body, paste it into a plain text editor, copy it from the plain text editor, and then paste it into the source editor inside the SCRIPT Tag element previously inserted, just above the closing tag of the CDATA element.
```
//Restarts the dialog if user doesn't confirm the information.
function onNotConfirmed()
{
    if(siNo.value == "No")
    {
        siSize.Clear();
        siPhoneNumberText.Clear();
        siPhoneNumberAreaCodeDigits.Clear();
        siPhoneNumberLocalDigits.Clear();
        siYes.Clear();
        siNo.Clear();
        siCancel.Clear();
    }
    return;
}
```
The function checks to ensure that the semantic value of siNo is No, and if so, it clears the values of all the semantic items in the semantic map.
Right-click the Default.aspx tab, and then click Save Default.aspx.

Terminating the Application Properly

The application uses an AnswerCall control to make the proper connections to the telephony source. When the application terminates, it needs a DisconnectCall control to break those connections properly.

To use the DisconnectCall control

Click the Default.aspx tab.
At the bottom of the pane, select Design.
In the Toolbox, select Speech, and then drag and drop a DisconnectCall control onto the design canvas.
Right-click the Default.aspx tab, and then click Save Default.aspx.

Canceling the Order

Applications can use Command controls to listen to all speech input for a given scope of the application and take action if a response is a recognized phrase in the control's grammar. Cancellation, Help, and Navigation commands are common uses for these controls. For more information, see GlobalCommands (Managed Code Sample). The tutorial application uses a simple control to cancel the order entirely and stop the application.

To set up the Command control for order cancellation

In the Toolbox, select Speech, and then drag and drop a Command control onto the design canvas.
In the Toolbox, select Speech, and then drag and drop a SpeechControlSettings control onto the design canvas.

The Command control requires this control.
Right-click Command1, and then click Property Builder.
In the tree view pane, select Command.
In the Speech Settings Item list, select <New>, accept SpeechControlSettingsItem1 in the Add New Speech Control Settings Item, and then click Add.
In the Scope list, select PizzaPanel.
In the Type box, enter Cancel.
In the tree view pane on the left, select Input.
On the Grammar tab, set the grammar as an existing grammar, choosing PizzaOrder.grxml as the grammar file and Cancel as the active rule.
Click the XPathTrigger Sample Sentence Tool button, enter Cancel in the Sample speech input box, and then click Go.

The tool now shows the SML that the SR engine returned.
In the XPathTrigger box, select SML/Cancel.
In the OnClientCommand box, enter CancelFunction.

The body of this function is added later in the tutorial.

The script in this function sets the activation state of the QA controls to false, so they are not activated again.
In the tree view pane on the left, select Voice Output.
Click Inline Prompt, and then enter the following inline prompt in the box:

Your order has been canceled. Goodbye.
Click OK.

By default, if a client activation is not specified for a control, its activation state is true. This means that it is activated any time it comes up in the dialog flow and its semantic items are not complete. To use the Command control to cancel the pizza order and end the application, it is necessary to set the state of all the QA controls to false. This requires a ClientActivation function for each control. It is the same for all the controls in this application and initially sets the activation state of the control to true. CancelFunction sets the variable that the ClientActivation function returns to false. Then, when the control becomes active in the dialog flow, the ClientActivation function returns false and the control does not activate, even though its semantic items might not be complete.

To set the state of the QA controls

Right-click SizeQA, and then click Property Builder.
In the ClientActivationFunction box, type ActivateQA.

Note

The AllowCommands box is already selected by default. This allows Command controls to listen for responses and take action at the same time the QA control is active.
Click OK.
Repeat steps 1 through 3 for PhoneQA, ConfirmQA, and ThanksQA.

To insert the script

At the bottom of the design canvas, click Source.

The HTML view of Default.aspx opens in a source editor.
Copy the following function body, paste it into a plain text editor, copy it from the plain text editor, and then paste it into the source editor inside the SCRIPT Tag element previously inserted, just above the closing tag of the CDATA element.
```
// ActivateQA is the ClientActivationFunction for the QA controls
// Until the CancelFunction sets the value of activeQA to false,
// it is always true.
var activeQA=true;
function ActivateQA()
{
    return activeQA;
}
function CancelFunction() 
{
    activeQA = false;
}
```
The ActivateQA function returns the value of the variable activeQA. When the application starts, this variable is set to true. The CancelFunction sets that variable to false. After that, when the ActivateQA function is called, it returns true.
Right-click the Default.aspx tab, and then click Save Default.aspx.

Confirming the Dialog Flow

The dialog flow for the application is now complete. The application plays the prompts, waits for responses, replays the relevant responses, and confirms the responses. If the caller confirms the responses, the application plays a concluding prompt and ends. If the caller does not confirm the responses, the application clears all the semantic items and restarts playing prompts with the SizeQA control. It is now possible to confirm the flow of the dialog by running it in the debuggers and answering "Yes" or "No" to the confirmation prompt.

Note

Because the PlayOnce property of QA controls is now cleared to be able to reactivate the controls on non-confirmation, the controls now replay if the silence time-out is exceeded or if the speech recognition engine does not recognize a response. A production application would have counters for each prompt and a way to determine the confidence of the recognition. It could give a different prompt after an unrecognized response or change the dialog flow after a certain number of failed attempts to get a recognizable response.

To confirm the dialog flow

On the Debug menu, click Windows, and then click SIP Phone.
In the Called Party and Calling Party boxes, enter any digit.
In the Voice Response Debugging Window dialog box, click Call.
Respond to the prompts as they play.
When asked if the responses are correct, say "No".

The application begins again with the prompt asking for the size.
Again, respond to the prompts as they play.
When asked if the responses are correct, say "Yes".

The application plays its thanks prompt, and then end.
Close the Voice Response Debugging Window dialog box.

To	See
Go to the next step	Debugging the Tutorial Application
Start from the beginning	Creating a Speech Project
Get more information about prompts and prompt functions	Prompt Projects and Databases
Get more information about commands	GlobalCommands (Managed Code Sample)

Share via