Oracle Digital Assistant – The must know component for a developer

The most versatile component in the ODA dialog flow is without any doubt the System.CommonResponse.

“The System.CommonResponse component enables you to build a specialized user interface that can include text, action buttons, images, and cards without having to write custom code. Instead, you define the component’s properties and metadata.”

I suggest this good tutorial for a comprehensive walkthrough. This post will focus on the different variations of the component.

Multiple Text Messages (no entity resolution)

From 21.06 release the CommonResponse component is suggested as a replacement to the SystemOutput.

It allows to define one/many output messages.

  multipleTextMessages:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "Hello Welcome to Mario's Pizzeria!"
        - type: "text" 
          text: "We have a great selection of Pizzas :)"
    transitions:
      next:

If you have an array variable with many messages, you need to use the property separateBubbles.

Text Messages with entity resolution

The below code resolves the entity, but shows no list of values or options.

 multipleTextBubbles2:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      keepTurn: false
      #pizzaType is a composite bag
      variable: "pizzaType"
      nlpResultVariable: "iResult"
      metadata:
        responseItems:         
        - type: "text"  
          text: "What pizza do you want?"
        - type: "text"  
          text: "We have SUPREME, PEPPERONNI and others"
    transitions: 
      next: "askSize"

The entity resolves once we provide an input that is defined in the LOV of the entity. Not a great implementation for an entity with LOV – it’s easier to show the options.

ANANAS is not in the LOV, hence we are prompted again. The incorrect prompt message and the max prompt attempt are not defined.

• variable–The value defined for this property references the dialog flow variable that is updated with the user input
• nlpResultVariable–References a dialog flow variable that’s of type natural language processing (NLP) result (iResult in this tutorial). The variable reference is used to suppress component rendering if the pizzaType information could be extracted from NLP.

If I write “hi, order SUPREME Pizza” then ODA will skip the above step as the entity is already resolved.

• processUserMessage–If set to true, then the System.CommonResponse component displays as an input component. If set to false, the component behaves like an output component.

Text + Menu options for entity resolution

This approach makes more sense, we will make use of the Entity LOV to displayed them to the user as menu options

${enumValue} refers back to the Entity LOV. iteratorVariable property makes it in a way that iterates over the items from the entity list. The type postback returns a JSON object that contains the state, action, and variables.

 orderPizza:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      keepTurn: false
      variable: "pizzaType" 
      nlpResultVariable: "iResult"
      metadata: 
        responseItems:      
        - type: "text"  
          text: "What kind of pizza do you want?" 
          actions: 
          - label: "${enumValue?capitalize}"
            type: "postback"
            keyword: 
            payload: 
              variables: 
                pizzaType: "${enumValue}"
            iteratorVariable: "pizzaType.type.enumValues"   
    transitions: 
      next: "askSize"       

The above interaction will only move to the next transition when you choose a valid value from the list. With the property maxPrompts we can define a maximum number of attempts for the user to select a valid value, to avoid a endless loop.

Create output with cards

We need* to define a variable with all the information for the cards – pictures and description.

*We don’t really need that, but its a good practice 🙂

LoadPizzaCardInfo:
    component: "System.SetVariable"
    properties:
      variable: "pizzaCardInfo"
      value:
        CHEESE BASIC:
          description: "Classic marinara sauce topped with whole milk mozzarella cheese."
          image: "https://cdn.pixabay.com/photo/2017/09/03/10/35/pizza-2709845__340.jpg"
        PEPPERONI:
          description: "Classic marinara sauce with authentic old-world style pepperoni."
          image: "https://cdn.pixabay.com/photo/2017/01/22/19/12/pizza-2000595_960_720.jpg"
        MEAT LOVER:
          description: "Classic marinara sauce, authentic old-world pepperoni, all-natural\
            \ Italian sausage, slow-roasted ham, hardwood smoked bacon, seasoned pork\
            \ and beef."
          image: "https://cdn.pixabay.com/photo/2017/07/22/22/51/big-2530144__340.jpg"
        
    transitions:
      next: "getUserIntent"

orderPizza:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      variable: "pizzaType"
      nlpResultVariable: "iResult"
      autoNumberPostbackActions:
      translate:
      metadata: 
        responseItems:         
        - type: "cards" 
          cardLayout: "horizontal"
          cards:
          - title: "${enumValue}"
            description: "${pizzaCardInfo.value[enumValue].description}"
            imageUrl: "${pizzaCardInfo.value[enumValue].image}"
            iteratorVariable: "pizzaType.type.enumValues"
            rangeStart:
            rangeSize:
            actions:
            - label: "Order ${enumValue?capitalize}"
              type: "postback"
              keyword:  
              payload: 
                action: "selectPizza"  
                variables: 
                  pizzaType: "${enumValue}" 
    transitions:
      next: "askSize"
      actions:
        selectPizza: "askSize"

Cards with Buttons

The globalActions property allows to add buttons to the entire component. Usually used for Cancel, Go Back and that type of actions.

  orderPizza:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      variable: "pizzaType"
      nlpResultVariable: "iResult"
      autoNumberPostbackActions:
      translate:
      metadata: 
        responseItems:         
        - type: "cards" 
          cardLayout: "horizontal"
          cards:
          - title: "${enumValue}"
            description: "${pizzaCardInfo.value[enumValue].description}"
            imageUrl: "${pizzaCardInfo.value[enumValue].image}"
            iteratorVariable: "pizzaType.type.enumValues"
            actions:
            - label: "Order (${enumValue[0]?upper_case}${enumValue[1]?upper_case})${enumValue?keep_after(enumValue[1])}"
              type: "postback"
              keyword: "${enumValue[0]?upper_case}${enumValue[1]?upper_case}" 
              payload: 
                action: "selectPizza"  
                variables: 
                  pizzaType: "${enumValue}"
                  
        globalActions:
        - label: "Cancel"
          type: "postback"
          keyword: "Cancel" 
          payload: 
            action: "exit" 

Another Example of Cards

This is a sample code that shows 3 cards with company news, with a label of type URL that is clickable.

news:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true      
      metadata: 
        responseItems:         
        - type: "cards" 
          cardLayout: "horizontal"          
          cards:
          - title: "New Menu at the company Cafeteria"
            #description: "www.oracle.com"
            imageUrl: "https://i.pinimg.com/originals/7a/fe/07/7afe07ff9379a6690d2f5aba2a51855c.jpg"           
            actions:
            - label: "New menu at company cafeteria"
              type: "url"
              payload:
                url: "www.oracle.com"
          - title: "New Coffee Machine"
            description: "Turbo Expresso Available"
            imageUrl: "https://media-cdn.tripadvisor.com/media/photo-s/10/78/59/e6/barista-coffee.jpg"           
            actions:
            - label: "See the new machine in action"
              type: "url"
              payload:
                url: "www.oracle.com"
          - title: "Oracle"
            description: "Digital Assistant"
            imageUrl: "https://miro.medium.com/max/700/1*VZoj9U7cmUzZYA5e5kfLJg.png"           
            actions:
            - label: "ODA"
              type: "url"
              payload:
                url: "www.oracle.com"   
        globalActions:         
        - label: "Back to Start"
          type: "postback" 
          payload:
            action: "action1" 
    transitions:
      actions:
        action1: "Greeting2"
      next: "Greeting2"

Display image, video, audio, or file

Below an example of displaying an Image.

 media:
    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
        - text: "Say Hello to ODA!"
          type: "text"
          name: "conf"
          separateBubbles: true
        - type: "attachment"
          attachmentType: "image"
          name: "image"
          attachmentUrl: "https://www.oracle.com/a/ocom/img/dc/oda-sticker.png"
      processUserMessage: false

This is an example of a pdf file as attachment.

 Policies:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      keepTurn: false
      metadata:
        responseItems:
        - text: "In this attached document you can find the absence policies."
          type: "text"          
          name: "txt"
        - type: "text" 
          text: "<a href='https://filelocation.pdf' target='_blank'>Absency Policies</a>"
       
        globalActions:         
        - label: "Back to Start"
          type: "postback" 
          payload:
            action: "action1" 
    transitions:
      actions:
        action1: "Greeting2"
      next: "completeCreateAbsenceIntent"

The above link is better displayed in a Web channel (otherwise the html markups are not displayed)

Training

Below is a great video from the Design Camp Series covering all of the CommonResponse versatility.