Hands-On Lab. Getting Started with the UCMA 3.0 Workflow SDK. Lab version: 1.0 Last updated: 12/17/2010

Transcription

1 Hands-On Lab Getting Started with the UCMA 3.0 Workflow SDK Lab version: 1.0 Last updated: 12/17/2010

2 CONTENTS OVERVIEW... 3 System Requirements 3 EXERCISE 1: UCMA 3.0 WORKFLOW SDK WORKFLOW ACTIVITIES... 4 Task 1 Open the Visual Studio Solution... 4 Task 2 Build the Workflow... 4 Task 3 Test the Workflow EXERCISE 2: BUILDING CUSTOM GRAMMARS Task 1 Building a Custom Grammar with GRXML Task 2 Building a Custom Grammar at Runtime Task 3 Test the Custom Grammars EXERCISE 3: PROMPTS, COMMANDS, AND COMMUNICATION EVENTS Task 1 Prompts Task 2 Commands Task 3 Communication Events Task 4 Test the Prompts, Commands, and Communication Events SUMMARY... 22

3 Overview Lab Time: 45 Minutes Lab Folder: C:\%UC14TrainingKit%\Labs\7\Source\Before The After folder contains the completed lab exercises. Lab Overview: The Unified Communications Managed API 3.0 Workflow SDK allows developers to create Windows workflows that support communications features including speech and instant messaging communication, sophisticated prompts and grammar for supporting machine to human dialog, call control including call transfer and detecting communication events, and presence awareness for using presence to intelligently route calls. In this lab, you will use the UCMA 3.0 Workflow SDK to build a personal virtual assistant that: Uses workflow activities for communicating with and gathering data from the caller, performing conditional logic, executing custom code, getting the presence of a user, and transferring a call. Uses custom DTMF grammars for collecting input from the caller. Provides a good user experience to the caller by providing personalized prompts and help functionality. System Requirements You must have the following items to complete this lab: Microsoft Visual Studio 2010 Unified Communications Managed API 3.0 Workflow SDK Unified Communications Managed API 3.0 SDK A provisioned UCMA 3.0 application Please refer to Lab 6 - Introduction to UCMA 3.0 to learn how to create and provision a UCMA 3.0 application.

4 Exercise 1: UCMA 3.0 Workflow SDK Workflow Activities Task 1 Open the Visual Studio Solution In this task, you will open the project and configure it to run with your parameter values. 1. Navigate to Start >> All Programs >> Microsoft Visual Studio Click on the Microsoft Visual Studio 2010 icon to start Visual Studio Select File >> Open Project. 1. Navigate to the folder C:\%UC14TrainingKit%\Labs\7\Source\Before\UCMA_WorkflowActivities. 2. Open the UCMA_WorkflowActivities solution. 3. In Solution Explorer, open the App.config file. 4. Change the value of ApplicationId to the application id of your provisioned UCMA 3.0 application, e.g. urn:application:labapp Change the value of ApplicationName to the application name of your provisioned UCMA 3.0 application, e.g. LabApp Change the value of TrustedContactUri to SIP URI of the contact associated with your provisioned UCMA 3.0 application, e.g. sip:labcontact10600@fabrikam.com. 7. Change the value of SecondaryLabUserId with the SIP URI of your secondary lab user. Task 2 Build the Workflow In this task, you will learn to use the various workflow activities available in the UCMA 3.0 Workflow SDK. 1. In the Solution Explorer window, open Workflow1.xoml. 2. Open and pin the Toolbox. 3. Expand the Unified Communications Workflow section of the Toolbox. 4. Drag a SpeechStatement activity onto the workflow design surface and place it as the first activity in communicationssequenceactivity1.

5 5. Open the properties of the new activity and rename it to Welcome. 6. Right-click the Welcome activity and select Generate Handlers. 7. Add the following code snippet to the Welcome_TurnStarting event handler. We would like the workflow to greet the caller by name, so we need to dynamically construct the value of MainPrompt at runtime. The TurnStarting event of the SpeechStatementActivity fires when the activity is about to play the prompt. this.welcome.mainprompt.appendtext( "Welcome {0}. I can help you manage your tasks", GetUserDisplayName(communicationsSequenceActivity1.CallProvider.Call.Remote Endpoint.Participant.Uri)); 8. Switch back to the workflow designer. 9. Highlight the EnterPIN activity and open its properties. 10. Highlight the ExpectedDtmfInputs property of the EnterPIN activity and click the ellipsis to edit the property. 11. Enter (note the spaces between digits) and click OK. In a later exercise in this lab, you will modify this activity to accept more complex input from the user. For now, this activity will only accept as valid input.

6 12. Set the value of IncompleteTimeout property of the EnterPIN activity to 00:00:20. The IncompleteTimeout property specifies the length of time after the user input that the recognition is complete. 13. Set the value of the InitialSilenceTimeout property of the EnterPIN activity to 00:00:10. The InitialSilenceTimeout property specifies the length of time before which the user has to start giving input or the recognition fails. 14. Set the value of the MainPrompt property of the EnterPIN activity to: Please enter your five-digit PIN. The MainPrompt is the prompt that is played when the activity starts. 15. The properties of the EnterPIN activity should now be set as follows: 16. Double-click the CheckPIN activity. The Code activity is native to Windows Workflow v3.0 and executes the code specified in the associated ExecuteCode handler. 17. Add the following code snippet to the CheckPIN_ExecuteCode event handler. In a production application, you can execute code to validate the PIN entered by the caller. _validpin = true; 18. Double-click the GetTasks activity and add the following code snippet to the GetTasks_ExecuteCode event handler to retrieve the caller s tasks from an XML file. XDocument xdoc = XDocument.Load("Tasks.xml"); _tasks = (from t in xdoc.elements("tasks").elements("task")

7 where!t.element("status").equals("completed") select new Task { Id = Convert.ToInt32(t.Element("Id").Value), AssignedTo = Program.SecondaryLabUserId, Description = t.element("description").value, Status = t.element("status").value }).ToList(); 19. Switch back to the workflow designer. 20. Drag a SpeechQuestionAnswer activity onto the workflow design surface and place it directly after the GetTasks activity. 21. Open the properties of the new activity and rename it to ChooseTask. 22. Set the value of IncompleteTimeout property of the ChooseTask activity to 00:00: Set the value of the InitialSilenceTimeout property of the ChooseTask activity to 00:00: Highlight the ExpectedDtmfInputs property of the ChooseTask activity and click the ellipsis to edit the property. 25. Enter the numbers 1 through 9 on separate lines and click OK. In a later exercise in this lab, you will modify this activity to set the expected DTMF inputs at runtime based on the tasks retrieved in the GetTasks activity. 26. The properties of the ChooseTask activity should now be set as follows:

8 27. Right-click the ChooseTask activity and select Generate Handlers. 28. Add the following code snippet to the ChooseTask_TurnStarting event handler. Build the MainPrompt of the ChooseTask activity dynamically after retrieving the caller s tasks. AppendBreak is used to add a break to a prompt to make it sound more natural. The PromptBreak enum is used to represents breaks of different lengths. this.choosetask.mainprompt.clearcontent(); this.choosetask.mainprompt.appendtext("please choose one of the following active tasks:"); this.choosetask.mainprompt.appendbreak(promptbreak.medium); foreach (var task in _tasks) { this.choosetask.mainprompt.appendtext("task {0}: {1}", task.id, task.description); this.choosetask.mainprompt.appendbreak(promptbreak.medium); } 29. Switch back to the workflow designer. 30. Double-click the SetTask activity and add the following code snippet to the SetTask_ExecuteCode to set the selected task. _selectedtaskid = Convert.ToInt32(this.ChooseTask.RecognitionResult.Text.Replace(" ", String.Empty)); 31. Drag a GetPresence activity onto the workflow design surface and place it directly after the SelectedTask activity.

9 32. Open the properties of the new activity and rename it to GetPresence. The warning on the GetPresence activity indicates that the Target property of the activity has not been set. The Targets property represents the list of users for which the activity will query presence. You will later set the Targets property at runtime based on the user that the selected task is assigned to. 33. Right-click the SelectedTask activity and select View Code. 34. Add the following code snippet to the end of SelectedTask_TurnStarting event handler. When the caller selects a task, add the assigned user to the Targets collection of the GetPresence activity. this.getpresence.targets.add(new RealTimeAddress(_taskAssignedToUri)); 35. Highlight the ifelsebranchonline branch of ifelseactivityonline and open its properties. 36. Set the Condition Type to Declarative Rule Condition. 37. Click the ellipsis in the Condition Name property to specify a condition for the If-Else branch. 38. Highlight the Placeholder condition and press Edit. In the Before code for this lab, a placeholder condition is set for the ifelsebranchonline activity in order to allow the lab code to compile without errors.

10 39. Replace the placeholder condition with the following code snippet in the rule condition editor and press OK. The condition checks if the presence of the assigned user is Online. this.getpresence.results[new RealTimeAddress(this._taskAssignedToUri)].PresenceStatus == PresenceAvailability.Online 40. After saving the condition, press Rename and rename it to UserIsOnline. 41. Drag a BlindTransfer activity to the ifelsebranchtransfer branch of ifelseactivitytransfer. 42. Open the properties of the new activity and rename it to BlindTransfer. The warning on the BlindTransfer activity indicates that the CalledParty of the activity has not yet been set. 43. Right-click the UserIsOnline activity and select View Code. 44. Add the following code snippet to the end of UserIsOnline_TurnStarting event handler to set the CalledParty property of the BlindTransfer activity. this.blindtransfer.calledparty = new RealTimeAddress(_taskAssignedToUri);

11 45. Save your changes. Task 3 Test the Workflow In this task, you will run and test the workflow solution that you completed in the previous task. 1. Switch to your secondary lab user s session. 2. Open Microsoft Lync. 3. Set the user s availability to Available. 4. Switch back to your primary lab user s session. 5. Switch to Visual Studio Go to Debug >> Run Without Debugging or use the shortcut key [Ctrl]+[F5] to start the application. 7. Open Microsoft Lync. 8. Locate the contact associated with your provisioned UCMA 3.0 application, e.g. LabContact10600@fabrikam.com. 9. Place an audio call to the contact. The attendant answers the call and welcomes the caller by name. The attendant prompts the user to enter their five-digit PIN. 10. Enter for the PIN. The attendant retrieves a list of the caller s active tasks and presents them as choices. 11. Enter 1 to select task number 1. The attendant confirms the caller s selection. The workflow checks the presence of the user that the task is assigned to. The attendant notifies the caller that the user is online and asks them if they would like to be transferred to the user. 12. Enter 1 for Yes. The workflow places a blind transfer of the call. 13. Switch to your secondary lab user s session. 14. Answer the incoming call. 15. Hang up the call. 16. Switch to your primary lab user s session. 17. Hang up the call. 18. Switch to the console application and press Enter. The application endpoint is terminated and the collaboration platform is shut down.

12 Exercise 2: Building Custom Grammars Grammars are used to recognize complex speech and DTMF input from the user. In this exercise, you will build a custom grammar declaratively using the Grammar-Xml (GRXML) syntax. You will also build a grammar dynamically at runtime using the Microsoft.Speech.Recognition.SrgsGrammar class in the UCMA 3.0 Workflow SDK. Task 1 Building a Custom Grammar with GRXML 1. The EnterPIN activity expects a five-digit sequence of numbers. The ExpectedDtmfInputs property is not sufficient to properly describe this sequence; you would have to add every possible combination of five numbers between 1 and 9 as expected inputs. The solution is to use a DTMF grammar to declaratively describe the expected DTMF input. 2. Add a new XML file to the WorkflowActivities project. 3. Rename the XML file to PINGrammar.grxml. 4. Open the properties of PINGrammar.grxml. 5. Set Build Action to Content. 6. Set Copy to Output Directory to Copy Always. When the WorkflowActivities project is compiled, PINGrammar.grxml is copied to the same location as the project s binaries. 7. Replace the contents of PINGrammar.grxml with the following. XML <grammar xml:lang="en-us" root="validpin" mode="dtmf" tag-format="propertiesms/1.0" version="1.0" xmlns=" <rule id="digit" scope="public"> <one-of> <item>0</item> <item>1</item> <item>2</item> <item>3</item> <item>4</item> <item>5</item> <item>6</item> <item>7</item> <item>8</item> <item>9</item> </one-of>

13 </rule> <rule id="validpin" scope="public"> <one-of> <item repeat="5"> <ruleref uri="#digit"/> </item> </one-of> </rule> </grammar> 8. You can specify if the grammar is restricted to DTMF by setting the mode attribute of the top-level grammar element to dtmf. Otherwise, the default behavior is that the grammar is used to validate both speech and DTMF input. 9. A grammar is simply a set of rules. The first rule in this grammar dictates the input must be one-of the listed items in order to be valid. The items in the list are the numbers 0 through The top-level grammar element specifies that the root rule for this grammar is the rule with the id of ValidPIN. The root rule is the main rule that the grammar will process. The ValidPIN rule references the digit rule and specifies that the sequence should be repeated five times. 11. Switch to the workflow designer. 12. Highlight the EnterPIN activity and open its properties. 13. Set the value of the Grammars property to PINGrammar.grxml. 14. Set the value of NoRecognitionPrompt to Sorry, that is not a valid PIN. Task 2 Building a Custom Grammar at Runtime 1. You saw how the workflow presented the user with a list of tasks to choose from. In this simple example, the list came from an XML file included in the project. 2. However, in a real life workflow, the task list would be retrieved from an external system such as a SQL Server database, or Microsoft Outlook. The workflow does not know in advance how many choices there are, so a static grammar does not work well in this case.

14 3. Double-click the GetTasks activity and add the following code snippet to the end of the GetTasks_ExecuteCode event handler to create a grammar that validates the caller s choice. Setting the ExpectedDtmfInputs property of the ChooseTask activity to null clears out the hardcoded settings in the activity. A grammar is constructed dynamically by creating an instance of SrgsDocument and adding rules to the grammar. A rule called Items that specifies that the caller must choose one of the valid task ids is created and added to the grammar s Rules collection and specified as the root rule. The new grammar is added to the DtmfGrammars collection of the ChooseTask activity. // Clear out hardcoded expected Dtmf inputs this.choosetask.expecteddtmfinputs = null; // Create a dynamic grammar based on the number of tasks in the list var choices = new string[_tasks.count]; choices = (from t in _tasks select t.id.tostring()).toarray(); var grammar = new SrgsDocument(); grammar.mode = SrgsGrammarMode.Dtmf; var rule = new SrgsRule("Items"); var oneof = new SrgsOneOf(choices); rule.elements.add(oneof); grammar.rules.add(rule); grammar.root = rule; // Clear out the grammars before adding a new one this.choosetask.grammars.clear(); this.choosetask.dtmfgrammars.add(new Grammar(grammar)); 4. Switch to the workflow designer. 5. Highlight the ChooseTasks activity and open its properties. 6. Set the value of NoRecognitionPrompt to Sorry, you did not select a valid task. Task 3 Test the Custom Grammars 1. Go to Debug >> Run Without Debugging or use the shortcut key [Ctrl]+[F5] to start the application. 2. Open Microsoft Lync. 3. Locate the contact associated with your provisioned UCMA 3.0 application, e.g. LabContact10600@fabrikam.com. 4. Place an audio call to the contact. The attendant answers the call and welcomes the caller then prompts them to enter a five-digit PIN. 5. Enter an invalid PIN, e.g. 1234*. The grammar specified in PINGrammar.grxml validates the PIN entered by the user and prompts the user that the input was not recognized. The activity s NoRecognitionPrompt is played when the caller enters invalid input.

15 a. Note: The Microsoft Lync numeric keypad allows the caller to enter numbers using the letters on the number keys. In order to enter some invalid input, enter * at the end of the PIN. 6. Enter a valid PIN, e.g The attendant retrieves a list of the caller s active tasks and presents them as choices. 7. Enter an invalid task number, e.g. 5. The dynamic grammar created at runtime will validate the user s input and prompt the user to enter a valid choice. 8. Hang up and close the call. 9. Switch to the console application and press Enter. The application endpoint is terminated and the collaboration platform is shut down.

16 Exercise 3: Prompts, Commands, and Communication Events In this exercise, you will use prompts, commands, and communication events to improve the experience of a user calling into the workflow application. Task 1 Prompts In this task, you will explore the various prompts that can be used with the SpeechStatement and SpeechQuestionAnswer workflow activities. You will also learn to create more sophisticated and natural sounding prompts. 1. Switch to the code behind in Workflow1.xoml.cs. 2. Navigate to the EnterPIN_TurnStarting event handler. 3. Add the following code snippet to EnterPIN_TurnStarting event handler to set the SilencePrompt of the EnterPIN activity. this.enterpin.prompts.silenceprompt.clearcontent(); this.enterpin.prompts.silenceprompt.appendtext(prompt_silence); this.enterpin.prompts.silenceprompt.appendtext("please enter your fivedigit, numeric PIN"); Note: The SpeechActivity and SpeechQuestionAnswerActivity activities support a collection of prompts that can be used to improve the user experience for the caller. For example, the SilencePrompt is the prompt that is used if the user stays silent. You can construct the SilencePrompt of the EnterPIN activity in the TurnStarting handler. The SilencePrompt can be also be set in the properties of the activity in the workflow designer, however setting it in the TurnStarting handler gives you more flexibility to construct a more useful prompt. Note that we are clearing the value of SilentPrompt first since the TurnStarting handler could potentially get executed several times. 4. Add the following code snippet at the end of the EnterPIN_TurnStarting event handler to set the NoRecognitionPrompt of the EnterPIN activity. The NoRecognitionPrompt is played if the user input is not recognized. this.enterpin.prompts.norecognitionprompt.clearcontent(); var norecprompt = new PromptBuilder(); norecprompt.appendtext(prompt_norecognition); norecprompt.appendbreak(promptbreak.medium);

17 norecprompt.appendtext("please enter your five-digit, numeric PIN"); this.enterpin.prompts.norecognitionprompt.appendpromptbuilder(norecprompt); Note: Another way to dynamically construct a prompt is to use a PromptBuilder object. Append text, audio, and breaks dynamically to the PromptBuilder to construct the prompt. Call AppendPromptBuilder on the NoRecognitionPrompt to append the instance of the PromptBuilder to the prompt. 5. Navigate to the ChooseTask_TurnStarting event handler. 6. Add the following code snippet at the end of the ChooseTask_TurnStarting event handler to set the SilencePrompt and NoRecognitionPrompt of the ChooseTask activity. this.choosetask.prompts.silenceprompt.clearcontent(); this.choosetask.prompts.silenceprompt.appendtext(prompt_silence); this.choosetask.prompts.norecognitionprompt.clearcontent(); var norecprompt = new PromptBuilder(); norecprompt.appendtext(prompt_norecognition); norecprompt.appendbreak(promptbreak.medium); norecprompt.appendtext("choose one of the tasks by entering its number."); this.choosetask.prompts.norecognitionprompt.appendpromptbuilder(norecprompt ); Task 2 Commands In this task, you will add a Help command to the workflow to allow the caller to press 0 to get help. 1. Switch to the workflow designer. 2. Highlight the drop down under the communicationssequenceactivity1 activity and select View Commands. A CommandsActivity stores all the commands available to the communications sequence. 3. Drag a SpeechHelpCommand from the toolbox into the CommandsActivity activity.

18 4. Highlight the SpeechHelpCommand and open its properties. Select the SpeechHelpCommand property and click the ellipsis to edit its value. 5. Enter 0 and click OK. Define the expected inputs that will trigger the Help Command of the SpeechQuestionAnswer activity that the caller is currently on. The HelpPrompt for that activity will be played. 6. Highlight the drop down under the communicationssequenceactivity1 activity and select View CommunicationsSequenceActivity. 7. Highlight the EnterPIN activity and open its properties. 8. Expand the Prompts collection of the EnterPIN activity. 9. Enter the following prompt for the HelpPrompt: Please enter your five-digit PIN so that the system can validate your identity. When the workflow prompts the caller to enter their PIN, the caller can press 0. The caller will hear the HelpPrompt of the EnterPIN activity when they press Repeat the previous steps to add the following HelpPrompt to the ChooseTask activity: "Please choose a task, the system will look up the availability of the person that the task is assigned to". Task 3 Communication Events

19 In this task, you will add a communication event to recognize when the caller enters invalid input successive times. 1. Highlight the drop down under the communicationssequenceactivity1 activity and select View CommunicationsEvents. Note: The CommunicationEvents activity contains a list of events defined for the communications sequence. Each event is mapped to an individual activity sequence that is run when the event is raised. By default, a CallDisconnected event communication event is created for every communication sequence. When the call is disconnected at any point during the communication sequence, this event is raised and the sequence is executed. The CallDisconnected event contains one Code activity that is blank by default and serves as a placeholder for application specific logic. 2. Drag a ConsecutiveNoRecognitionSpeechEvent activity into the CommunicationEvents activity. The ConsecutiveNoRecognitionsSpeechEvent fires when the caller responds successive times in a way that does not match to an expected grammar element. 3. Open the properties of the ConsecutiveNoRecognitionSpeechEvent activity. The MaximumNoRecognitions property is set to 3 by default. 4. Set the value of MaximumNoRecognitions to Drag a SpeechStatement activity into the ConsecutiveNoRecognitionSpeechEvent activity. 6. Set the MainPrompt property of the activity to: Sorry, I did not understand your response or you did not enter one. Please try again later. If the callers enters invalid input in response to a SpeechQuestionAnswer activity two successive times, the workflow will playback this prompt.

20 7. Drag a GoTo activity into the ConsecutiveNoRecognitionSpeechEvent activity and place it under the SpeechStatement activity. 8. Open the properties of the GoTo activity. 9. Highlight the TargetActivityName and click the ellipsis to edit the property and connect it to the disconnectcallactivity1 activity. The caller will be disconnected if they trigger the ConsecutiveNoRecognitionSpeechEvent. Note: There are three communication events for consecutive errors when waiting for input during a question to the user. The ConsecutiveSilencesSpeechEvent triggers when the no response limit is hit. The ConsecutiveNoRecognitionsSpeechEvent triggers when the caller responds in a way that does not match to an expected grammar element (up to the

21 configurable consecutive occurrences). Lastly, the ConsecutiveNoInputsSpeechEvent triggers from both the silences and no recognition events based on a configurable maximum. Task 4 Test the Prompts, Commands, and Communication Events 1. Go to Debug >> Run Without Debugging or use the shortcut key [Ctrl]+[F5] to start the application. 2. Open Microsoft Lync. 3. Locate the contact associated with your provisioned UCMA 3.0 application, e.g. LabContact10600@fabrikam.com. 4. Place an audio call to the contact. The attendant answers the call and welcomes the caller by name. The attendant prompts the user to enter their five-digit PIN. 5. Do not enter the PIN when prompted. The SilencePrompt for the EnterPIN activity will be played. 6. Enter a valid PIN, e.g The attendant retrieves a list of the caller s active tasks and presents them as choices. 7. Enter 0. Entering 0 triggers the SpeechHelpCommand of the workflow. 8. The caller hears the HelpPrompt of the EnterPIN activity. 9. Enter an invalid task number, e.g. 4. The caller hears the NoRecognitionPrompt of the ChooseTask activity. 10. Enter an invalid task number, e.g. 5. The activity sequence in the ConsecutiveNoRecognitionSpeechEvent is triggered. 11. The caller is disconnected. 12. Switch to the console application and press Enter. The application endpoint is terminated and the collaboration platform is shut down.

22 Summary In this lab, you built a personal virtual assistant built using the UCMA 3.0 Workflow SDK. You saw how the workflow was able to collect information from the user, interact with external services, and communicate dynamically with the user to present various options. You also saw how to use custom grammars to collect complex DTMF input from the user. Finally, you learned how to improve the user experience for the caller by providing Help Commands and support for incomplete or unrecognized input.