Tracking tasks in your applications

In the context of Voice Platform, a task can be any unit of work that is considered significant. For example, in the PizzaTalk application you may consider selling a pizza to be a task. Within that larger task, you may have several smaller tasks such as one for determining the size of the pizza that the caller wants, and another obtaining the desired toppings.

It may be important for you to be able to track the outcomes of such tasks for later analysis. Voice Platform lets you do so by defining tasks within your application, so you can generate task completion reports and summaries for them in the Management Station.

Voice Platform provides two Nuance extensions for defining tasks in your application: <nuance:taskbegin> and <nuance:taskend>. These elements let you assign a name to a task in your application, and define its beginning and end within your VoiceXML file. You can specify conditions for the successful completion of the task, and a reason for the outcome of the task (whether it’s successful or not).

When the application runs, Voice Platform tracks the start and end times of the task; whether it completed successfully or unsuccessfully; and if it was unsuccessful, the reason for the failure. Voice Platform records this information in the call log that is generated for every call made to the system.

Task Completion reports

You can generate Task Completion reports in the Management Station. These reports chart the number and percentage of tasks attempted and completed over time, and more.

Generating task alarms

To send an alarm to the Management Station on failure of a given task, use a <log> or <script> element. See Generating alarms in VoiceXML for more information.

Using the taskbegin and taskend elements

The <nuance:taskbegin> and <nuance:taskend> elements are executable content tags, so you can use them anywhere that executable content is allowed: for example, within <block>, <filled>, <if>, or event-catching elements.

<nuance:taskbegin>

The <nuance:taskbegin> element has only one attribute: the name to be assigned to the task. Task names are case-sensitive, and should be unique across your application. For example, if several forms in your application include a “place_order” task, add a prefix that identifies each task in the form. Otherwise, if you import call logs from applications that use the same task name, you won’t know which place_order task the Management Station is using to generate the report. 

<nuance:taskbegin name="form1_place_order"/>

When executing this element, the interpreter does not generate any events.

<nuance:taskend>

The <nuance:taskend> element requires three attributes:

  • name: The name of the task (same as in the <nuance:taskbegin> element).
  • cond, result, or resultexpr: An indication of whether the task was completed successfully. Only one of these attributes can be specified at a time.

    If the condition evaluates to Boolean true, or the result or resultexpr evaluates to “SUCC”, the task is considered successful. If the condition evaluates to Boolean false or the result or resultexpr evaluates to “FAIL”, the task is considered a failure. If the result or resultexpr evaluates to “UNKN”, the outcome of the task is considered to be unknown. If the condition uses a variable that is out of scope or evaluates to something other than a Boolean, the Voice Browser service throws an error.semantic event when executing the element.

  • reason or reasonexpr: An indication of the reason for the outcome of the task. By default this will be “success” if the task was successful, “failure” if the task failed, and “unknown” if the outcome is not known. However, you can supply more specific reasons for the outcome.

For example: 

<nuance:taskend name="form1_place_order" cond="credit_card == 'approved'" 
    reason="Credit Card Rejected"/>

If the Voice Browser service encounters a taskend element without a taskbegin element, no taskbegin element is logged. However, when you generate a Task Completion report, the report will imply a taskbegin element immediately preceding the taskend element. As long as the taskend’s cond attribute evaluates to true, the task will be considered to have completed successfully.

If two or more occurrences of a task are in progress, the taskend element marks the end of the task that started most recently. This might occur when a caller suspends an operation to perform another similar operation.

For example, suppose a caller in the process of transferring funds from Account A to Account B decides to transfer funds from Account C to Account B. The caller completes this second transfer (and the taskend element records the fact) before completing the transfer from Account A to Account B. When the caller successfully completes the first transfer, it will be logged as complete too.

Example

PizzaTalk provides a simple example of using the taskbegin and taskend elements. The Welcome.vxml page includes the line: 

<nuance:taskbegin name="sold_a_pizza" />

This generates an entry like this in the call logs: 

TIME=20091107170004138|CHAN=12.3.45.67,SWMS-117|EVNT=SWItrxb |NAME=sold_a_pizza|UCPU=9046|SCPU=2562

The Wrapup.jsp page includes the line: 

<nuance:taskend name="sold_a_pizza" cond="true" reason="" />

In addition, if a caller does not confirm the pizza size and toppings when prompted, the ConfirmSizeAndToppings.jsp page asks, “Would you like to try again?” If the caller says no, the application marks this task as unsuccessful, using taskend as follows: 

<nuance:taskend name="sold_a_pizza" cond="false" reason="User did not confirm"/>

These taskend elements generate entries in the call logs that look like this: 

TIME=20091107170022513|CHAN=12.3.45.67,SWMS-117|EVNT=SWItrxe|
NAME=sold_a_pizza|RSLT=FAIL|RESN=User did not confirm|UCPU=9046|SCPU=2562

With all these elements in place, you can track task completion for the PizzaTalk application. If you make some calls to the application to generate some data, you can then generate a Task Completion report.