Here are the steps for creating a skill for use in a DA-as-Agent digital assistant.

1. Click to open the side menu, and then click Development > Skills.
2. Click New Skill .
3. Give it a display name that will make sense to someone who is conversing with the digital assistant through the service. The digital assistant uses this value in some automated messages and prompts. For example: You are at <skill-display-name>. Here are some things you can do.
4. Complete the dialog, and then click Create.
5. In the left navigation bar, click Settings , and then click General.
6. Set the Training Model to Trainer Tm.
7. Switch Enable Insights to On.

   You can use insights to analyze and retrain your skill, as described in Review Conversation Trends Insights.

8. Click the Digital Assistant tab.
9. Enter an invocation that will make sense to a customer. This value is copied to the digital assistant's interaction model for the skill and is used in automated digital-assistant prompts and responses. For example:

   You are at <skill-display-name>. Here are some things you can do:
   <skill-invocation-name-from-DA> <skill-one-sentence-description> 
   1. <skill-example-utterance-set-in-DA>
   2. <skill-example-utterance-set-in-DA>
   ...

Add the necessary intents and entities for your skill.

If your DA-as-agent skill is a basic question-and-answer skill, then you can use answer intents to handle the questions and answers. For Oracle B2C Service, you also can use System.KnowledgeSearch components to address questions and answers. For knowledge search examples, see Use the System.KnowledgeSearch Component. Note that you must create a knowledge search integration to use this component.

After you create your intents click Train. You can't test or publish a skill if it hasn't been trained.

To test your intents, click Test Utterances, and then enter test utterances in the Quick Test section to verify that the model is resolving to the desired intents. You should enter utterances from the intents as well as utterances that are not in any intents. The dialog shows the confidence level for each matched intent. If the resolution isn't what you intended, consider adding the utterance to the desired intent or revising the intent that was incorrectly matched. You also can click Go to Test Cases to create or import batch tests. To learn more see Intent Training and Testing.

When users are signed into the service or have provided their first name, last name, and email address on the chat launch page, then the profile.firstName, profile.lastName, and profile.email variables will contain the user information. For Oracle B2C Service, the profile.locale variable is set to the interface language code. For Oracle Fusion Service the locale is based on language that the user selected on the chat launch site, or, if none was selected, the browser's locale.

In addition, the profile.contactInfo variable contains some chat-request info, such as the customer's question (subject) and the product ID and category ID, if applicable. Also, if the chat launch page contains any custom fields, then the values that the customer enters into those fields are passed to the digital assistant in the profile.contactInfo.customFields array. To learn about customizing the fields that are on the Oracle B2C Service chat launch page, see Overview of Chat on the Customer Portal in Using Oracle B2C Service.

The profile.contactInfo variable is available only for instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).

Here's the structure of the profile.contactInfo for Oracle B2C Service:

{
  "question": <string>,
  "productId": <number>,
  "orgId": <number>,
  "categoryId": <number>,
  "browser": <string>,
  "ipAddress": <string>,
  "userAgent": <string>,
  "sessionId": <string>,
  "operatingSystem": <string>,
  "customFields": [
    {
      "name": <string-name-of-custom-field>,
      "id": <ID-of-custom-field>,
      "value": <field-value> 
    },
    ...
  ]
}

Here's some example data:

{
   "question":"Do you deliver",
   "productId":7,
   "customFields":[
      {
         "name":"ODA Text",
         "id":44,
         "value":"N/A"
      
},
      {
         "name":"ODA YN",
         "id":45,
         "value":"1"
      
},
      {
         "name":"ODA Nbr",
         "id":46,
         "value":"1"
      
},
      {
         "name":"ODA Date",
         "id":47,
         "value":"2020,2,17"
      
},
      {
         "name":"ODA Menu",
         "id":48,
         "value":"12"
      
},
      {
         "name":"ODA DateTime",
         "id":49,
         "value":"2004,11,18,17,18"
      
}
   
],
   "browser":"FireFox 68.0",
   "ipAddress":"123.45.67.89",
   "userAgent":"Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101 Firefox/68.0",
   "sessionId":"HI6unnBo",
   "operatingSystem":"Windows 10",
   "orgId":-1,
   "categoryId":-1
}

Here's an example of extracting and displaying contact info:

context:
  variables:
    contactInfo: "map"
  ...
  setContactInfo:
    component: "System.SetVariable"
    properties:
      variable: "contactInfo"
      value: "${profile.contactInfo.value}"
    transitions:
      next: "echoQuestion"
  echoQuestion:
    component: "System.Output"
    properties:
      text: "Your question was: ${contactInfo.value.question}"
      keepTurn: true
    transitions:
      next: "showText"
  showText:
    component: "System.Output"
    properties:
      text: "You entered: <#list contactInfo.value.customFields as p><#if p.name=='VIP Status'>${p.value}</#if></#list>"
      keepTurn: true
    transitions:
      return: done

Here's the structure of the profile.contactInfo for Oracle Fusion Service:

{
  "question": <string>,
  "productId": <number>,
  "orgId": <number>,
  "categoryId": <number>,
  "browser": <string>,
  "ipAddress": <string>,
  "userAgent": <string>,
  "sessionId": <string>,
  "operatingSystem": <string>,
  "customFields": [
    {
      "name": "<custom-field-name>",
      "type": "<data-type>",
      "value": "<field-value>",
      "menuItemLabel": "<label-string>"
    },
    ...
  ]
}

If you want the skill to transfer the chat session to a human agent, such as when the user wants something that the skill isn't built to handle, add a state that uses the System.AgentTransfer component. Then add some dialog flow to transition to that state as necessary.

Here's an example of a dialog flow that transfers to an agent when the customer asks to speak to an agent. Note that this example just illustrates how to use the System.AgentTransfer component. If you'd like to get the wait time before attempting the transfer, see Get Agent Availability and Wait Time. If you would like the skill to track how many times an agent was needed and why, see Creating Dimensions that Track Skill Usage.

metadata:
  platformVersion: "1.1"
main: true
name: "AutomatedAgentConversation"
context:
  variables:
    iResult: "nlpresult"
    someVariable: "string"
states:
  #
  # Note that even though Answer intents don't have actions, you must have a System.Intent state even if 
  # you have no other types of intents. Answer intents output the answer and restart the conversation.
  #
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        ...
        system.Unsatisfactory Response: "transferToAgent"
        system.Request Agent: "transferToAgent"
        ...
  
  #
  # This state tries to transfer the user to another agent when the user explicitly requests for it.
  #
  transferToAgent:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: "300"
      waitingMessage: "I'm transferring you to a human agent. Hold tight."
      rejectedMessage: "I wasn't able to transfer you to a human agent. Please try again later."
      errorMessage: "We're unable to transfer you to a human agent because there was a system error."
    transitions:
      actions:
        accepted: "reset"
        rejected: "handleRejected"
        error: "offerMoreHelp"
      next: "reset"
  #
  # This state is called when an agent transfer is rejected. 
  # It lets the customer know they can ask for something else.
  # 
  handleRejected:
    component: "System.Output"
    properties:
      text: "Meanwhile, let me know if there's anything else I can help you with."
    transitions:
      return: "handleRejected"
  
  #
  # This state is called when an agent transfer encounters a system error. 
  # It lets the customer know they can ask for something else.
  #
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"
      
  #
  # This state ends the conversation with a return transition for insights purposes, 
  # after the user has been transferred to another agent.
  #
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

See System.AgentTransfer for details about the properties and actions.

When you transfer a conversation from a digital assistant to a live agent, you'll most likely want to pass some information to the service, such as values for an escalation rule. You use the customProperties object to pass this information.

Here's the structure for Oracle B2C Service:

      customProperties:
        - name: 
          value: 
          type:

The type property is required for custom fields, otherwise, it's optional.

For Oracle B2C Service, the name can be FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CATEGORY_ID, CONTACT_ID, INCIDENT_ID, and any custom field of type Incident that has Chat Display enabled in the Visibility settings.

For custom fields, use the field's column name (lower case) preceded by c$. The type can be BOOLEAN, DATE, DATETIME, INTEGER, LONG, STRING, and DECIMAL. The default is STRING. For DATE and DATETIME, use the format yyyy-MM-dd'T'HH:mm:ssXXX. For BOOLEAN, use 1 for true, and 0 for false.

Here's the structure for Oracle Fusion Service:

      customProperties:
        - name: 
          value:

For Oracle Fusion Service, the name can be FIRST_NAME, LAST_NAME, EMAIL, QUESTION, PRODUCT_ID, CATEGORY_ID, CONTACT_ID, INCIDENT_ID, and any field from an Oracle Fusion Cloud Applications (Fusion) object. Note that when you add a custom field to a Oracle Fusion Service object using Application Composer, the _c suffix is added to the name automatically.

Here's an example customProperties setting for Oracle Fusion Service:

  doTransfer:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: "300"
      allowTransferIf: "agentSessionsAreAvailable"
      # Example of passing a custom property to Oracle Fusion
                                Service      
      customProperties:
        # This is a checkbox custom field in the Universal Work Object.
        # Checkboxes take the value of Y (selected) or N (unselected).
        - name: "TriagedByODA_c"
          value: "Y"
      acceptedMessage: "The conversation has been transferred to a live agent."
      waitingMessage: "I'm transferring you to a human. Hold tight"
      rejectedMessage: "Looks like no one is available. Please try later"
      errorMessage: "We're unable to transfer you to a live agent because there was a system error."
    transitions:
      actions:
        accepted: "reset"
        rejected: "handleRejected"
        error: "offerMoreHelp"
      next: "reset"

To learn about Oracle B2C Service custom fields, see Overview of Custom Fields in Using Oracle B2C Service. For information about Oracle Fusion Service custom property fields, see "Fields" in Configuring Applications Using Application Composer.

The System.AgentTransfer component has two properties that let you configure when to attempt transferring to an agent – maxEngagementsInQueue and allowTransferIf.

The maxEngagementsInQueue property lets you set the maximum number allowed for engagements waiting in the destination queue. When the chat request is sent, the service responds with the current number of engagements waiting in the queue. If this value exceeds maxEngagementsInQueue, then the rejected action occurs. If you don't include this property, then there's no engagement limit.

You use the allowTransferIf property to specify when to transfer based on available agents. The options are:

• agentsAreRequestingNewEngagements: (default) For Oracle B2C Service agents who must pull chats (request new engagements), this is the most restrictive set of conditions, and the user doesn't have to wait too long before they speak to an agent. The skill attempts to transfer the conversation only if there are agents who have requested new engagements. In all other cases, this option has the same behavior as agentSessionsAreAvailable.
• agentSessionsAreAvailable: The skill attempts to transfer the conversation if any of the available agents have not reached the maximum number of chats that they are allowed to have at one time. The user may have to wait if the agents are involved in long-running conversations or are doing some post-chat follow-up.
• agentsAreAvailable: The skill attempts to transfer the conversation if there are any agents online regardless of whether they have reached their maximum number of chats or are requesting new engagements. With this option, the users may have long waits.

If the specified conditions aren't met, then the rejected action occurs.

If all available agents are busy when a user wants to speak to an agent, then it's possible that the user might have a long wait. Rather than simply transferring the conversation and leaving the user stuck for an unknown amount of time, you can use the System.AgentTransferCondition component to find out the estimated wait time, display that time, and give the user the opportunity to cancel their request for transfer.

You use the component's properties to specify the transfer conditions and the name of the context map variable to put the status information in. The component returns an action that indicates whether the conditions were met. See System.AgentTransferCondition for details about the status information and the actions.

Here's an example of a dialog flow that invokes the component, displays the wait time, and gives the user the opportunity to cancel their transfer request.

The askIfWillWait state uses a resource bundle entry to form the wait time message so that the message makes sense whether the time is more or less than a minute and whether a number is 0, one or more.

There are some experts online. But it might take {minutes, plural,
     =-1 {}
     =0 {}
     =1 {1 minute and }
     other {# minutes and }
}{seconds, plural,
     =-1 {a while}
     =0 {{minutes, plural,
          =0 {a very short wait time}
          other {0 seconds}
        }}
     =1 {1 second}
     other {# seconds}
} for one to join. Are you willing to wait?

Note that this example uses System.SetCustomMetrics to track if agents were available, and, if so, how many users chose to wait and how many canceled the transfer request.

  ############################
  # Agent Transfer
  ############################  

  # See if there are any agents available 
  
  evaluateAgentTransferCondition:
    component: "System.AgentTransferCondition"
    properties:
      maxWaitSeconds: 300
      maxEngagementsInQueue: 20
      allowTransferIf: "agentsAreAvailable"
      agentStatusVariable: "agentStatus"
    transitions:
      actions:
        conditionsMet: "askIfWillWait"
        conditionsNotMet: "setInsightsCustomMetricsConditionsNotMet"
        error: "handleTransferError"
      next: "done"
      
  # Measure when agents aren't available

  setInsightsCustomMetricsConditionsNotMet:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "No agents available for new chats"
    transitions:
      next: "handleRejected"      
                  
  askIfWillWait:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text:  "${rb('promptTextForTransferDecision','minutes,seconds',agentStatus.value.expectedWaitMinutes,agentStatus.value.expectedWaitSeconds)}"
            separateBubbles: true
            actions:
              - label: "Yes, I'll wait"
                type: "postback"
                keyword: "yes"
                payload:
                  action: "yes"
                name: "Yes"
              - label: "No, nevermind"
                keyword: "no"
                type: "postback"
                payload:
                  action: "no"
                name: "No"
    transitions:
      actions:
        yes: "setInsightsCustomMetricsAgentTransferInitiated"
        no: "setInsightsCustomMetricsAgentTransferCancelled"
        textReceived: "intent"
      next: "handleCancelled"
      
  # Measure when user chooses to wait for transfer

  setInsightsCustomMetricsAgentTransferInitiated:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "User chose to wait"
    transitions:
      next: "transferToAgent"        
      
  # Measure when user chooses to not wait for transfer

  setInsightsCustomMetricsAgentTransferCancelled:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer Choice"
        value: "User didn't want to wait"
    transitions:
      next: "handleCancelled"
      
  # Perform the actual transfer
  #
  # The maxWaitSeconds, maxEngagementsInQueue, allowTransferIf,
  # and customProperties, if any, should match those used for 
  # System.AgentTransferCondition 
  
  transferToAgent:
    component: "System.AgentTransfer"
    properties:
      maxWaitSeconds: 300
      maxEngagementsInQueue: 20
      allowTransferIf: "agentsAreAvailable"
    transitions:
      actions:
        accepted: "done"
        rejected: "handleRejected"
        error: "handleTransferError"
      next: "handleTransferError"
     
  ############################
  # All done
  ############################
                  
  done:
    component: "System.Output"
    properties:
      text: "Let me know if you need help on anything else."
    transitions:
      return: "done"  
      
  handleRejected:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text"
          text: > 
            Unfortunately, none of my colleagues are currently available to assist with this.
            Still, we’d love to see this through for you. 
            Please feel free to reach us through email@example.com.
    transitions:
      next: "done"
      
  handleCancelled:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "OK. Maybe some other time. Please feel free to reach us through email@example.com."
    transitions:
      next: "done"
      
  handleTransferError:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "Unfortunately, we can't transfer you at this time. Please try again later."
    transitions:
      next: "done"
      
  ############################
  # Global error handler
  ############################
  
  globalErrorHandler:
    component: "System.Output"
    properties:
     text: "Sorry, we were unable to do the action that you requested." 
    transitions:
      next: "done"

You can create an incident report (or service request) for Oracle B2C Service or Oracle Fusion Service from any skill.

To create an incident report from your skill:

1. Go to Settings > Additional Services > Customer Service Integration and create an integration with the needed service.

   You only need to do this once per instance.

2. Add the incident creation component to your flow. For the Visual Flow Designer, see Incident Creation. For YAML, see System.IncidentCreation.

   If you have created a Oracle Fusion Service integration and have selected Allow only signed-in users to create service request as the authentication type, you also need to do the following:

   1. Set the Incident Creation component's Requires Authentication setting to True.
   2. Add an OAuth Account Link component to the dialog flow to handle user authentication. For the Visual Flow Designer, see OAuth Account Link. For YAML, see System.OAuthAccountLink.

The default chat that's accessed through the service's customer portal is limited to text and images. For example, instead of cards and buttons, it just displays text, and the user has to type the choice or button label instead of just clicking on it.

To display more than just text for the UI components that are in the dialog flow, you can use one of the following options:

• Web Chat for Service (WCFS). This feature enables you to customize the chat widget by using features present in the SDK for Oracle Web user channels. To configure WCFS, see the Web Chat for Service (WCFS) section of Administering Oracle Engagement Engine.
• Oracle Inlay Toolkit Inlays. To learn about Inlays, see the Oracle Inlay Toolkit documentation.

If your chat client is the default chat that's accessed through the service's customer portal, then ensure that you set the Enable Auto Numbering on Postback Actions to true on the Settings > Configuration page for the digital assistant so that the user can respond to the UI component by typing in a number instead of the exact text. If you don't set it to true, then use keywords for response items to minimize what the user has to enter. In this example, autonumbering is set to true whenever the client is Twilio or Oracle B2C Service chat.

${(system.channelType=='twilio'||system.channelType=='osvc' )?then('true','false')}

Here's a comparison of how the UI components are displayed for the different clients.

This table illustrates how different component configurations display in the default chat and Inlays.

Example Component Configuration	Inlay	Default Chat
actionList: component: "System.List" properties: prompt: "System.List Choose an option for setting the transition action" options: - label: "Action 1" value: "action1" - label: "Action 2" value: "action2" - label: "Action 3" value: "action3" autoNumberPostbackActions: false footerText: "Footer" transitions: actions: action1: "output1" action2: "output2" action3: "output3"
cardResponseHorizontal: component: "System.CommonResponse" properties: processUserMessage: true keepTurn: true metadata: responseItems: - type: "cards" cardLayout: "horizontal" footerText: "Footer Text: Cards with Values: Horizontal" cards: - title: "${myvalues.name}" description: "${myvalues.description}" imageUrl: "${myvalues.image}" cardUrl: "http://www.oracle.com" name: "ValuesCard" iteratorVariable: "myvalues" actions: - label: "I Want This One" type: "postback" payload: action: "itemPicked" variables: user.horizontalVariable: "${myvalues.name}" globalActions: - label: "Cancel" type: "postback" payload: action: "cancel" - label: "Send Location" type: "location"
cardActionResponse: component: "System.CommonResponse" properties: processUserMessage: true keepTurn: true metadata: responseItems: - type: "cards" cardLayout: "vertical" footerText: "Footer text for cards." cards: - title: "Card with Actions" description: "This is a card with actions" cardUrl: "http://www.oracle.com" name: "ActionsCard" actions: - label: "share" type: "share" payload: action: "share" - label: "location" type: "location" payload: action: "location" - label: "url" type: "url" payload: action: "url" url: "http://www.oracle.com" - label: "call" type: "call" payload: action: "call" phoneNumber: "808 888 1212" - label: "ok" type: "postback" payload: action: "ok" variables: user.someVariable: "ok" - label: "not ok" type: "postback" payload: action: "notok" variables: user.someVariable: "not ok" transitions: {}		Note that you can wrap the payload URLs in HTML tags. For example <a href="http://www.oracle.com">Click Here</a>.

After you build the skill, you must train it so that you can use it in the DA-as-agent digital assistant.

1. Go to Settings > General and ensure that the training model is Trainer Tm.

   When you use answer intents, you should always use Trainer Tm, even in development environments.

2. Click Train.
3. (Optional) If you don't intend to make anymore changes to this version of the skill, in the title bar, click the down arrow and select Publish.

You'll need a chat rule in the Service Console to define when to assign a chat session to the digital assistant. You'll also need a state to handle transfers from the digital assistant to a live agent.

1. Expand Site Configuration and double-click Rules.
2. In the Home tab, click Chat, and then click Edit.
3. Create a state for the hand off to a live agent.
   1. Right-click States and click New State.
   2. Name the state. For example: 03. Hand Off to Live Agent.
   3. Click Save.
4. Add a rule to the state to assign the chat session to a queue.

   These substeps show a very simple configuration. For your instance, you must carefully consider both the if conditions, and the then actions.

   1. Right-click the state that you just added and click New Rule.
   2. Name the rule. For example: Hand Off to Live Agent.
   3. In this example, there are no if conditions. You might need to add conditions as appropriate for your business needs.
   4. Click Add Action - Then and then click Chat Queue ID.
   5. From the Assign Chat Queue drop-down list, select the queue that the conversation should be sent to (in this example, the default queue).

      
      
      
      

   6. Click Save.
5. Add a rule to the initial state to route chat sessions to the digital-assistant-agent queue.
   1. Right-click the initial state (the one that is shown in bold text), and click New Rule.
   2. Name the rule. For example: Digital Assistant Agent.
   3. If applicable, click Add IF Condition Based On to add the desired conditions for routing to the digital assistant queue.
   4. Click Add Action - Then and add an action to assign the chat session to the digital assistant queue (Digital Assistant Agent in our example).
   5. Click Add Action - Then and add an action to transition to the state that you created for the hand off (03. Hand Off to Live Agent in our example) and then stop.

      
      
      
      

   6. (Optional) Add an Else action.
   7. Drag the rule to a position in the initial state such it's evaluated before any rules that might route the qualifying chat sessions to some other queue. For example, ensure that it is evaluated before a state that unconditionally routes chat sessions to the default queue.
6. Compile and activate your changes.

To prevent the customer from having to state their need twice, add a Subject field to the chat launch page. If a customer enters a value in that field, then, when the conversation is transferred to the digital assistant, the digital assistant tries to resolve the intent from the subject field value.

The Subject field is included in Inlays by default. To learn about customizing fields on the chat launch page, see Overview of Chat on the Customer Portal in Using Oracle B2C Service.