Oracle by Example brandingOpenWorld 2019 Hands-On Lab: Build a Skill with the Conversation Designer

section 0Before You Begin

This 60-minute hands-on lab introduces you to the Oracle Digital Assistant's Conversation Designer. This lab demonstrates how you can generate a fully functioning skill from example conversations between the user and the skill.

Background

The ability to rapidly develop a functioning skill, one that typifies the interactions between the skill and its users, can be a very useful feature for any company developing a conversational interface for a number of reasons. These include:

  • Getting the buy-in and sign-off from your business on the flow and function of the skill.
  • Road testing the conversation flow with target users to get their feedback.
  • Providing skill developers with a concrete idea of the conversation that they need to implement.

What Do You Need?

To complete this lab, you need an Oracle Digital Assistant (ODA) cloud instance. You can get one using either of the following approaches:

  • Setting up a trial instance.

    By having your own instance, you can continue this lab after the event and even build your own digital assistant.

  • Using a shared instance that has been provisioned for this event.

    If you select this option, you can dig into the lab with less setup time.

    This instance will be used by other participants in the hands-on lab.

Option A: Set Up a Trial Instance

Get an Oracle Cloud Account

Before you can get a trial ODA instance, you need an Oracle Cloud account. If you don't already have one, go to http://oracle.com/oow19freetier to sign up.

  • Please sign up with the email you used to register for Oracle World
  • Please chose Phoenix as the home region.
  • You should get an email within a few minutes to confirm the account.
  • Once you have done so you can sign in Oracle Cloud Sign in

Provision an Oracle Digital Assistant Instance

  1. Click the navigation menu (Navigation menu icon) in the top left corner, scroll down to and expand Platform Services, and then click Digital Assistant.
    Description of oci_console_platform_menu.png follows
  2. Click Instances.
  3. Click Create Instance.
  4. In the Details section of the Instance area, fill in the following details:
    • Instance Name: Enter a name that reflects usage of the environment. For example, for a development environment, you might use something like oda-dev1.

      You can use a name of up to 20 characters. It must start with a letter, and can contain only letters, numbers and hyphens (-). It cannot end with a hyphen (-).

      Use a different name for each environment you create.

    • Description: (Optional) Enter a brief description of what the instance will be used for.
    • Notification Email: Status reports are sent to this email, including notice of when your instance has been created.
    • Region: Select Phoenix
    • Tags: (Optional) Add tags and assign tags to this service.
  5. Use the following placement tag from Oracle: ODAPHX_CODE_2019
    1. In the Special Instructions section of the Instance area, select the I have special instructions from Oracle checkbox.
    2. Input your placement tag.
  6. Click Next.
  7. Review the instance details, then click Create.

    There will be a short wait before you receive an email confirming that your Digital Assistant instance is ready for you to sign into.

    If it takes more than a few minutes to finish, try refreshing the page in the browser.

  8. Once the instance is created, click the menu icon and select Digital Assistant UI Designer.
    screenshot showing a panel for a Digital Assistant instance. On the right side of the panel is an options menu, which is selected, showing options for Digital Assistant UI Designer, Add Tags, and Delete.

    A new browser tab will be opened with the Digital Assistant Designer UI.

    a screenshot showing the home page of Oracle Digital Assistant

Option B: Use the Shared Instance

Log In to the Shared Instance

  1. In your browser, navigate to http://bit.ly/ODAHOLInstance2.
  2. Log in to the instance using the credentials provided by your lab instructor.

After successfully logging in, you will land on the ODA home page.


section 1Review the Conversation Flow

You can conceptualize the user-skill conversation in different ways before you actually begin building it with the Conversation Designer. For example, you can sit down with a business stakeholder or target user and create a overall flow based on how they envision a typical conversation. For the purposes of this lab, we've already assembled the following flow for the conversation that you will realize using the Conversation Designer.

Description of this illustration
Description of the illustration

You'll notice that there are four top-level flows that can be triggered through natural language processing (NLP):

  • Live Chat -- Executed when the skill understands that user wants to speak to an agent. It then hands the user off to a call center. (For this lab, you won't actually be configuring the agent hand off in Oracle Service Cloud. The goal here is to just demonstrate the flow.)
  • Buy Goods -- Presents a carousel of cards, each with a different product. Each card directs the user to the company's website.
  •  Product Question -- Recognizes that the user wants to ask a question about a product. It presents a list of help topics, such as registering a warranty, checking a warranty, or product support.
  • Download User Manual -- Prompts the user for product information and then presents the appropriate PDF that the user can download.


section 2Create Tasks

You need to create a new skill when you use the Conversation Designer (you can't use it with an existing skill), so start off by creating a new skill in your ODA instance. From your new skill, you'll access the Conversation Designer and then begin building the tasks.

  1. In your ODA instance, click the left menu (The Menu Icon), expand Development, and then click Skills.
  2. Click the New Skill tile.
  3. The New Skill tile
  4. Complete the Create Skill dialog by giving your skill a name. If you're sharing an instance with other developers, start the name with your initials. For example: GR_ConversationDesignerSkill.
  5. Click Create.
  6. In the left navigation bar, click Conversation Designer ( The Conversation Designer icon).
  7. In the Welcome screen, add the following and then click Create.
    • Human Live Chat
    • Buy Goods
    • Product Question
    • Download Manual
  8. Description of the illustration follows
    Description of the illustration.

Build the Human Live Chat Task

In this step, you're going to create a sample agent escalation conversation, where the chat is transferred from the skill to a live agent upon the user request. As mentioned previously, you're not going to actually configure the agent hand-off to Oracle Service Cloud. Instead, your going to add the user request and a series of skill responses that would be typical for an escalation scenario.

  1. Click Human Live Chat in the Tasks menu.
    Description of this illustration follows
    Description of the illustration.
  2. Click the Person Speaks icon ( The Person Speaks icon).
  3. In the Add Message dialog, first select Text (if it's not already selected) and then enter I want to speak to a human. Note that Conversation Designer classifies this input as INTENT UTTERANCE.
  4. Description of sample-arch-image.png follows
    Description of the illustration.
  5. Click Done. Note that the message appears in the preview.
  6. Description of this image follows
    Description of the illustration.
  7. Click the Bot Speaks icon (The Bot Speaks icon).
  8. In the Add Message dialog, select Text (if it isn't already selected).
  9. Enter Happy to connect you to our call center. Then click Done.
  10. Note: Unless you're told otherwise, select Text (the default) for both the skill and user messages for the remainder of this tutorial.

    Description of sample-arch-image.png follows
    Description of the illustration.
  11. Click The Bot Speaks icon again. Enter OK -- passing you to an agent now.
  12. Click Done.

You've just completed the first task. It should look like this in the preview:

Description of this image follows
Description of the illustration.

Build the Buy Goods Task

For this task, you're going to build a conversation where the user searches for, and buys, a television. After you enter the initial user request message, you're going to create a series of skill messages that prompt the user through the transaction. These messages include lists of options, a confirmation message, and a carousel of cards with images and clickable actions.

  1. Click Buy Goods in the Tasks menu.
  2. Click The Person Speaks icon. Enter I'd like to buy a television please. Notice that the Conversation Designer again classifies this type of statement as an INTENT UTTERANCE.
  3.  Click Done.
  4. Click The Bot Speaks icon. Enter OK -- We have a great selection at low, low prices! Conversation Designer classifies this message as OUTPUT.
  5. Click Done.
  6. Click The Bot Speaks icon again. In the Add Message dialog, select Actions.
  7. The Select Button.
  8. In the Bot's Message field, enter What size of TV are you interested in?
  9. Add the following three actions:
    • Up to 32 inch
    • Up to 48 inch
    • Up to 80 inch
  10. Description of this image follows
    Description of the illustration.
  11. Click Done to close the dialog.
  12. Click The Person Speaks icon. Enter Up to 32 inch. Because this user message references an action whose value was defined already, the Conversation Designer classifies it as CHOICE since the user is choosing a known value.
  13. Click Done.
  14. Click The Bot Speaks icon and then enter the confirmation message, Here are our TVs Up to 32 inch.

    Because this message contains one of the values set for the action, it will enable the skill to populate the user's choice in the message at runtime. Be sure to enter the same letters and characters that you used in the action (Up to 32 inch, for example, not Up to 32-inch). If you don't, the skill will output this message as static text.

  15. Click Done.
  16. Click The Bot Speaks icon again, but this time, select Cards.
  17. The Action button
  18. In the General tab, enter Here are our TVs that are currently in stock in the Bot's Message field. 
  19. Description of this image follows
    Description of the illustration.
  20. Click the Cards tab.
  21. The cards tab
  22. In the Title field, enter Panasonic 75 HD.
  23. In the Description field, enter Premium picture quality on a large scale.
  24. Enter https://cdn.pixabay.com/photo/2018/12/22/03/27/smart-tv-3889141_1280.png in the Image URL field.
  25. In the Actions field, enter Buy.
  26. Click the menu (The menu icon) next to the Actions field and then select Go to URL from the Action Type menu.
  27. Description of this image follows
    Description of the illustration.
  28. Enter https://www.panasonic.com.
  29. Description of this image follows
    Description of the illustration.
  30. Click Done.
  31. Description of this image follows
    Description of the illustration.
  32. Click Add Card The add icon.
  33. The Add Card icon
  34. Repeat the previous steps, but enter the following values:
    • Title: Samsung Q95OR
    • Description: Experience immersive viewing for less
    • Image URL: https://cdn.pixabay.com/photo/2012/04/11/18/33/lcd-29306_1280.png
    • Action: Buy
    • Go to URL: https://samsung.com
  35. Description of this image follows
    Description of the illustration.
  36. Click The add icon again and then add the following:
    • Title: Sony SG9
    • Description: Double award winner
    • Image URL: https://cdn.pixabay.com/photo/2017/02/20/00/03/tv-2081277_1280.png
    • Action: Buy
    • Go to URL: https://www.sony.com
  37. Description of this image follows
    Description of the illustration.
  38. Click Done.

Build the Product Question Task

For this conversation, the skill handles various product support requests with a list of actions that route to other tasks. To enable this routing, you will add actions that branch to subtasks. As the name implies, subtasks perform supporting functions. Unlike tasks, they contain conversations that have been started by the skill, not by a user's intent utterance.

  1. Click Product Question in the Tasks menu.
  2. Click The Person Speaks icon. Enter I have a product question.
  3. Click Done.
  4. Click The Bot Speaks icon.
  5. In the Add Message dialog, click Actions.
  6. In the Bot's Message field, enter Ok, -- for product questions, I can help you with the following.
  7. Enter Warranty Registration in the Action 1 field.
  8. Click the menu (The menu icon) that's next to the field and then choose Branch Conversation from the Action Type menu.
  9. Description of this image follows
    Description of the illustration.
  10. Enter Warranty Reg (the name of a subtask that you'll create later on) and then click Done.
  11. Description of this image follows
    Description of the illustration.
  12. Repeat these steps to create two more actions, Warranty Check and Support. These two actions will also branch to subtasks that you will create later on.
    • For the Warranty Check action, enter Warranty Check as the branched conversation.
    • For Support, enter Support as the branched conversation.
    • Description of this image follows
      Description of the illustration.
  13. Click Done to close the dialog.

The Warranty Registration, Warranty Check, and Support subtasks have been added to the Tasks list.

Description of this image follows
Description of the illustration.

Build the Download User Manual Task

For this final task, you'll create a conversation where the skill replies to the user's request for a product manual. To enable this download, you will add an attachment message that points to the URL for the manual, which is a PDF document.

  1. Click Download Manual from the Tasks menu.
  2. Click The Person Speaks icon. Enter I want to download a manual for my TV.
  3. Click Done.
  4. Click The Bot Speaks icon. Enter Can you please confirm the product ID?
  5. Click Done.
  6.  Click The Person Speaks icon. Enter ABC-12345. Notice that the Conversation Designer classifies this input as NUMBER.
  7. Click Done.
  8. Description of this image follows
    Description of the illustration.
  9. Click The Bot Speaks icon.
  10. Click the Next option (next to Cards) to navigate to Attachment.
  11. Description of this image follows
    Description of the illustration.
  12. Enter Here is your TV manual in the Bot's Message field.
  13. In the URL field, enter http://downloadcenter.samsung.com/content/EM/201902/20190208124554853/BN68-09451A-00_QSG_Q90R_ZA_190118.0.pdf
  14. Choose File from the Type menu. Then click Done.
  15. Description of this image follows
    Description of the illustration.

section 3Create the Sub Tasks

You added Warranty Registration, Warranty Check, and Support subtasks when you configured action routing for the Product Question task. In this section, you're going to build them out with their own messages.

Build the Warranty Registration Subtask

  1. Click Warranty Reg in the Tasks list.
  2. Description of this image follows
    Description of the illustration.
  3. Click The Bot Speaks icon. Enter OK -- I can register your warranty. Can you confirm the email address?
  4. Click Done.
  5. Click The Person Speaks icon. Enter name@example.com. Note that the Conversation Designer classifies this as EMAIL.
  6. Click Done.
  7. Click The Bot Speaks icon. Enter OK--we will email our warranty registration form to you.
  8. Click Done.

Build the Warranty Check Subtask

  1. Click Warranty Check in the Tasks list.
  2. Click The Bot Speaks icon. Enter OK--let's check your warranty. Please enter the product serial number.
  3. Click Done.
  4. Click The Person Speaks icon. Enter 12345678. Note that the Conversation Designer classifies this as NUMBER.
  5. Click Done.
  6. Click The Bot Speaks icon. Enter OK--I can confirm 12345678 is currently in warranty until the 12th of October 2019. Be sure that the serial number matches your input in the previous user message.
  7. Click Done.

Build the Support Subtask

  1. Click Support in the Tasks list.
  2. Click The Bot Speaks icon.
  3. Click Actions.
  4. Enter Would you like to speak to an agent or raise a ticket? in the Bot's Message field.
  5. In the first action field, enter Speak to a live agent.
  6. Click the menu (The menu icon) next to the field and then choose Branch Conversation from the Action Type menu.
  7. Enter Live Chat. Then click Done.
  8. Description of this image follows
    Description of the illustration.
  9. Enter Log a service ticket in the second action field.
  10. Click the context menu then choose Branch Conversation.
  11. Enter Log Ticket. Then click Done.
  12. Description of this image follows
    Description of the illustration.
  13. Click Done to close the dialog.
  14. Description of this image follows
    Description of the illustration.

Build the Live Chat Subtask

  1. Click Live Chat in the Tasks list.
  2. Click The Bot Speaks icon. Enter Connecting you to one of our agents...
  3. Click Done.

Build the Log Ticket Subtask

  1. Click Log Ticket in the Tasks list.
  2. Click The Bot Speaks icon. Enter Ok--logging a ticket. Can you please confirm the product serial number?
  3. Click Done.
  4. Click The Person Speaks icon. Enter 12345678. Note the the Conversation Designer has classified this input as NUMBER.
  5. Click Done.
  6. Description of this image follows
    Description of the illustration.
  7. Click The Bot Speaks icon. Enter OK--I've opened a support ticket on product 12345678. Someone will contact you shortly.
  8. Click Done.

section 4Preview the Mockup

Now that you've completed the mockup, you can preview its various tasks and see how the conversation flows. In fact, you can preview a task while you're building it to check your work.

While building the flows, you probably noticed the check mark that appears next to actions and cards. This denotes a default action or choice.

Description of this image follows
Description of the illustration.

The preview replays the conversation according to the default actions, so by resetting the defaults, you can preview different outcomes. In this section, we're going to change the default settings for the Buy Goods and Product Question tasks because they have multiple actions.

Preview the Buy Goods Task

  1. Click Buy Goods in the Tasks list.
  2. Click Preview Your Task! (located at the upper right).
  3. The Preview your task! link
  4. Click Send Message (The Send Message icon) to enter the initial user message (I'd like to buy a television please) after it's populated in the chat.
    The Send icon
  5. When the preview outputs Up to 32 inch, click The Send Message icon.
  6. When you click The Send Message icon to enter Buy at the end of the flow, a separate tab opens for the target URL associated with the Panasonic 75 HD, the Panasonic website.
  7. Description of this image follows
    Description of the illustration.
  8. Return to the browser tab that's running Oracle Digital Assistant.
  9. Click Back to Mockup.
  10. The Back to Mockup link

Change the Default Card for the Buy Goods Task

The browser opens the Panasonic website because the Panasonic 75 HD is the default choice (It bears the check mark in the preview). Let's try something else.

  1. In the preview, click the skill's Here are our TVs currently in stock message.
  2. Click Edit Interaction (The Edit Interaction icon) in the context menu.
  3. Description of this image follows
    Description of the illustration.
  4. Click the Cards tab in the Edit Message dialog.
  5. Click the menu (The menu icon) in the second card tile located near the top of the dialog.
  6. Description of this image follows
    Description of the illustration.
  7. Click Set Default.
  8. Description of this image follows
    Description of the illustration.
  9. Click Done to close the dialog.
  10. Click Preview Your Task! again. This time, the carousel scrolls to the Samsung Q95OR card. When you click The Send Message icon to enter Buy, the Samsung website opens.
  11. Description of this image follows
    Description of the illustration.
  12. Return the browser tab that's running Oracle Digital Assistant, then click Back to Mockup.

Change the Default Action

The default TV size in the preview mode is Up to 32 inch. Let's see what happens in the preview when you change the default setting for the size options.

  1. Select the skill's What size of TV are you interested in? message in the preview. (You may need to scroll up.)
  2. Click The Edit Interaction icon in the context menu.
  3. In the Edit Message dialog, select the Actions tab if it isn't already open and then click the menu (The menu icon) next to the Up to 48 inch action.
  4. Description of this image follows
    Description of the illustration.
  5. Click Default, then click Done. Click Done to close the Edit Message dialog.
  6. Description of this image follows
    Description of the illustration.
  7. Click Preview Your Task! and then start the conversation again by clicking The Send Message icon after each user message. So far, the user's responses have been the same as the default values, but in this case, the preview ignores the new default of Up to 48 inch and proceeds with Up to 32 inch. Why? Because the user's Up to 32 inch message overrides the default setting in the preview mode. If you hadn't added this user message, then the conversation would play according to the default value. When you actually chat with the skill later on, you can enter any of these values.
  8. Description of this image follows
    Description of the illustration.
  9. Click Back to Mockup.

Preview the Product Question Task

By default, the Product Question task routes per the Warranty Registration action, which branches to the Warranty Reg subtask.

Description of this image follows
Description of the illustration.

To preview this task:

  1. Click Product Question in the Tasks list
  2. Click Preview Your Task!
  3. Prompt the conversation by clicking The Send Message icon after each user message.
  4. When the replay reaches the end of the Warranty Reg task (Ok -- we will email our warranty registration form to you.), click Back to Mockup.

Change the Default Routing for the Product Question Task

  1. Click Product Question in the Tasks list.
  2. Click the skill's reply (Ok-- for product questions, I can help you with the following in the preview. Then click The Edit Interaction icon in the context menu.
  3. Description of this image follows
    Description of the illustration.
  4. In the Edit Message dialog, click the menu (The menu icon) next to the Support action.
  5. Description of this image follows
    Description of the illustration.
  6. Choose Default and then click Done. Then click Done again to close the Edit Message dialog.
  7. Click Support in the Tasks list.
  8. In the preview, click the message and then click The Edit Interaction icon in the context menu.
  9. Click the menu next to the Log a service ticket action.
  10. Description of this image follows
    Description of the illustration.
  11. Choose Default and then click Done. Click Done again to close the Edit Message dialog.
  12. Click Product Question in the Tasks lists again and then click Preview Your Task! and then click The Send Message icon to replay the conversation. Note that conversation now ends with Log Ticket subtask.
  13. Description of this image follows
    Description of the illustration.
  14. Click Back to Mockup.

section 5Generate the Skill and Take a Look at the Artifacts

With your tasks complete, you're now ready to generate an actual skill.

  1. Click Generate Skill (The Generate Skill icon).
  2. The Generate Skill icon
  3. Click Generate in the Generate Skill dialog.
  4. Click Train (The Train Button).
  5. The Train icon.
  6. Click Submit in the Train dialog.

The Conversation Designer creates a complete dialog flow definition along with intents and entities that it interpreted from the tasks and their messages. Let's take a quick look at some examples.

View the Generated Intents

  1. Click Intents (Intent icon) in the left navigation bar. Notice that the Conversation Designer has generated a Greeting intent along with intents that match each task. It has also added training data that it interpolated from the task name and the user messages that it classified as INTENT UTTERANCE.
    Description of this image follows
    Description of the illustration.
    For example, click BuyGoods. Notice that both the name of the task and the user message (I would like to buy a television set please) are incorporated into the training data along with variants of these phrases.
    Description of this image follows
    Description of the illustration.

View the Generated Entities

  1. Click Entities (Entities Menu Icon) in left navigation bar. The Conversation Designer used the bot and user messages (and their various relationships to one another) to create a series of entities and composite bag entities. There are are a lot of them, so we're just going to look at one of them.
    Description of this image follows
    Description of the illustration.
  2. Click TelevisionTv in the Entities list.
  3. Description of this image follows
    Description of the illustration.
  4. Notice that Conversation Designer has created a Value List entity from the skill's action message that asks for TV sizes.
  5. Description of this image follows
    Description of the illustration.

section 5Test the Skill

In this step, you're finally going to chat with the skill itself and discover how the generated artifacts support its understanding of natural language, its ability to route the conversation, slot entity values, and validate user input.

Test the Buy Goods Task

  1. Click the Skill Tester (The Skill Tester icon) in the left navigation bar.
  2. Enter I want to buy a television in the chat window.
  3. Choose a size. Note that the skill confirms that size.
  4. Description of this image follows
    Description of the illustration.
  5. Click Reset (The Reset Button), located at the upper right hand side.
  6. The Reset button
  7. Begin the conversation again by entering I want to buy a television.
  8. When prompted to choose a size, enter something that's not one the values, like 100 or Huge. Notice that the skill only accepts input that matches the action names.
  9. Description of this image follows
    Description of the illustration.
  10. Enter one of the action names, like 80 inch.
  11. Scroll through the carousel to select a TV, then click Buy. The company website opens a separate tab.
  12. Click The Reset Button and then repeat these steps, varying the intent message (buy TV, I wanna television, etc.) and choosing different combinations of TV sizes and models each time. Be sure to click The Reset Button after each conversation. When you're done with this flow. click The Reset Button.

Test the Product Question Flow

  1. Enter I've got a question about my warranty.
  2. Click Warranty Registration.
  3. When prompted to enter an email address, enter what? (or something else that's not formatted as an email address). Notice that skill is asking for a specific entity type, EMAIL.
  4. Enter a valid email address.
  5. Description of this image follows
    Description of the illustration.
  6. Click The Reset Button.
  7. Enter I have a warranty question.
  8. Click Support, then Log a service ticket.
  9. Enter any numeric string (like 9898989898989). Note that the confirmation message references that value. If you entered a string of letters (wESdlfjlakdkl, for example), the skill would prompt you for a NUMBER entity value.
  10. Description of this image follows
    Description of the illustration.
  11. Click The Reset Button.

Test the Download Manual Flow

  1. Enter i need a manual.
  2. Enter a string of numbers.
  3. Click the link. You may need to open this document in another tab. For example, if you're using Windows, right-click your mouse and then choose Open Link in New Tab.
  4. Description of this image follows
    Description of the illustration.

Congratulations! You've created a working skill using the concept of design by example.


more informationWant to Learn More?