Prophecy 9.0 Development Guide Home  |  Frameset Home
  Integration - HTTP  |  TOC  |  Outbound Applications  

Introduction to the Prophecy Designer


Tutorial: Web Services and the Loop Step


This tutorial is based material and exercises we have done in the previous Designer tutorials.  We suggest that if you haven't done those yet you'll want to check them out first.

In our first tutorial we learned how to create a basic Hello World project that greets our caller and hangs up, then we added some interaction and finally we tied it in with some fancy server side scripting.  Well now we are going to integrate into a web service and learn how to handle XML data that a Web Service returns!

Step 1: Create New Project


From here we'll select Create a New Project. This brings us back to our familiar Call Flow diagram.






Step 2: Add Some Steps


First we will want to create a few prompts letting our user know what it is they have dialed into, in this case we will be just using TTS for all of our prompts rather then recording our own custom audio files.  Let's create our first prompt just welcoming the user to the Weather Lookup Tool and we will use the Next Destination box to create a new step where we will gather some user input!





Even though this is an Input step we still need to let our users know to input something.  Here we will ask the user for their zip code using our old friend TTS, you will want to check Prompts may be interrupted by the caller's Voice or keypad input, since during our testing we will likely want to skip past all of the TTS.



Now once we have created our prompt for the user we still need to collect their response or utterance for those in the 'know'.  We will want to stay in the same step, but switch to the Caller Responses tab & select Edit



Now since we will be just collecting a zip code from our callers we will just use the Digits Collection Type, these prebuilt grammars allow us to simply and quickly recognize more complex utterance types such as Dates, Phone Numbers and even currency!  We can specify Maximum and Minimum Length as well which can help improve recognition accuracy.  Here we will set Minimum and Maximum to 5 digits for US Zip codes.



Now we can create another new step.  Lets make this one a Yes/No Step step.  This was we can perform some user utterance validation on our previously collected utterance.



We will want to use the Add Data button and then select zip code input.Collection Result as TEXT STRING so we can read back up collection results to the user to validate it.




--------------------------------------------------------------------

*Note*

You may be asking what is this text string thing and where the heck did this come into play?  Well this is Designers built in TTS or Text To Speech.  These settings allow us to manipulate TTS output and read it back in a specific way.

While we have this step up I wanted to take this chance to clarify a few things regarding the TTS features of Designer.  The following table explains all the options:

Read Data As Description & Options Example
Alphanumeric Mixed return which consists of alphanumeric data ABC123
Currency The return TTS is treated as currency "two dollars and fifty cents
Date The return will be a date, patterns available are Year, Month & Year, Month-Day Month-Year, and lastly Day of Week-Month-Day of Month Thursday, May Seventeenth
Digits Standard digits, containing no decimal places, Groupings can be specified and Intonation (Up, Down & Question) five hundred and fifty five
Cardinal Number Counting numbers, refer to the size of a group one, two, three, four, five...seventy, eighty, ect
Ordinal Number Representing the rank of a number with respect to some order, in particular order or position (i.e. first, second, third, etc.). Its use may refer to size, importance, chronology, etc. thirty first, twentieth, second, ect
Text String Simple text data that you would like to be interpreted via Prophecy TTS engine Defaults to 35 seconds. Maximum value is 120.
Time The Time Dummy, just the time.  You can specify timezone twelve thirty pm eastern daylight savings time


--------------------------------------------------------------------



Now back to your feature program which is already in progress


The end result will look something like this.

One thing you that I wanted to point out is the ability to Barge-In by simply checking the Prompts may be interrupted by the caller's voice or keypad input under Speech Options.  The VoiceXML equivalent to this would be the prompt element with the bargein attribute.




Ok, so now we have built out basic user interaction, We have collected a bit of information from a user, we have validated that COLLECTION RESULT  making use of the Yes/No Step.  Now we need to either proceed on with our program or re-query the user if the result is incorrect.  We will do this under the same step, just under the Caller Choices tab as seen below.




We can also make some custom NOMATCH handlers here on the third tab:



There are pretty self explanatory but we will lightly touch on it just in case there is any confusion!  This is where you can allow for up to 3 retries when a users utterances is not matched before you are required to transition to another step.  You can use TTS and even audio files for these re-prompts, they are fully customizable!


Step 3: WSDL Time!!!


So now we have our basic framework setup for our WSDL Designer program.  Here is how your Designer project should look thus far.



Now lets go back to our Did You Say step and under the Yes Step lets make a new step and call it Weather Lookup and make it an integration step.

So now we have the following


We want to select Web Service and select Save



Then we will select Explore




Then we will put in our web-service we selected form X-Methods, in this case its a Weather WSDL thats available for free!

http://ws.cdyne.com/WeatherWS/Weather.asmx?wsdl


Copy that URL into our WSDL Location field and select Get Methods.  In this case we are going to be looping through forecasts for a particular zip code.  The zip code is the Method for a particular WSDL.  So in this case we will select GetCityForecastByZIP and select OK.

So now we have selected the method that we will be using for this WDSL step, so now the Parameters box should have some methods that we need to populate from data inputted from our users.



Since this WSDL has several methods we will want to make sure that we select the correct one.  As we mentioned earlier we want to select GetCityForecastByZip

This will then drop us back to the integration step main window.  Once we are here will will want to populate the Runtime Variable with the data we collected from our user in the  zipCodeInput step.  Make sure that you select the Collection Response result, and not the Response Result.  As we mentioned earlier Response Result is a static or constant value that is set in the step and not the collection results.

Here is than image of the step:


Step Four: Test Our WSDL and Verify Results


  You can see there we have placed a Test Value option on the WSDL Parameters box, this allows you to view the return from your WSDL data dip.  Lets put in a ZIP code and watch is work its magic!

Here we can see the elements in order and verify that we are communicating properly with our WSDL.



Now this is important, we want to make sure that we select the correct Destination for our WSDL, once we have successfully retrieved our data we will want to make sure that we transfer then to a loop step to parse the results.



Now we want to use a Loop Step and make sure the loop type is Data Iteration



We will then want to add data and we can do this by scrolling down the list of Data Variables to Weather Lookup (Result)



Then we expand our tree until we get to the Forecast element and select it.



We will then select our loop destinations, in this case we will chose both of them to goto a prompt so we can validate the return data.

Now that we are in a new Prompt step we will use the data from the loop to prompt our user.  We will add our prefix which is simply static TTS followed by two variables that we will render to TTS based on our results!



We will then migrate to a choice step, we could make use of the Yes/No Step but we wanted to make this project as diverse as possible so we will just use the Choice step to illustrate its usage!



Now as we did with our ZipCode step, we will want to verify that we have the correct city before we move forward.  We can do this by simply asking our user if this is the city he wants.



So now we have verified that we have the correct data from our user and so now we have to do something with that data, right.... Correct sir.

So earlier we created our WSDL integration step that returned some nifty complex XML data and we have been using Loops to parse through that data for our users.



So if you notice here the XML that was returned from our test data dip contains different days data.  So lets use another loop here to pick the correct data for our users.  There is no point in knowing yesterdays weather unless you are Doctor Who, so here we go.

Lets create our loop step and point it to our element that we will be looping through.





Now that we have created this loop we will want to ask the user when to stop this crazy train that we call a loop.  Other wise things can get a bit dizzy  =P.



So after each iteration we will prompt the user and ask him if this is the day he wants and then proceed or revert back to the loop based on his answer.



So now we have allowed our user to verify the date they would like the forcast for, we have done this with the help out of wonderful loops and WSDL integration steps!!  How cool is that!  So now lets parrot off our data, make sure our user knows if he can leave that umbrella at home or not and then end this crazy train we call a phone call =].

Step 6: Output returned data to caller and end out call


So lets create a prompt that outputs this the select dates weather via TTS to our caller.



So we don't want to just hang up on our caller do we? Nah, in the interest of proper etiquette we will ask if he wants to get another days weather, or what if we wants to check another cities weather?  Well we can code for that!!!

So we will ask the user how he wants to proceed with a simple choice step.



And our caller choices will route back which ever portion of the project the user would like, such as back to the date loop for another day's weather, or even back to the zip code input to allow the caller to select another city entirely!

Now if the caller is done we just create another prompt that says good bye and select the final destination as hangup and we end the call.



The End, and the WSDL lived happily ever after with all of her loops!


That is it, we have successfully used loops to parse through data returned from our WSDL integration steps returned data.  If you would like you can use the attached backup of this entire project and simply create a new project in Designer and restore from backup

How simple is that,  if there are any questions or if you need any assistance on this please let us know.  Our support staff is always more then happy to offer any assistance our developers may require.


Sample Code!!!


Just in case you want to take this project as it is and throw it out there then by all means please download it and do with it what you will!  It's free code!!!  All you need to do is download the link here and then fire up Designer and create a new project.



Then select the file and name your project



And that its!!!

What we covered:




  ANNOTATIONS: EXISTING POSTS
0 posts - click the button below to add a note to this page

 login
  Integration - HTTP  |  TOC  |  Outbound Applications  
© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site