Smart Advice. Agile. Personalized. Transparent.

Oracle Digital Assistant fuelled by OPA Interview via the OPA Chat API

Philip Whitwell

Update! Oracle Digital Assistant 20.12 includes an out-of-the-box connector and system component for Intelligent Advisor simplifying the integration of interviews into Digital Assistant flows. For more information, see Integrate with Oracle Digital Assistant in the Intelligent Advisor Documentation Library.


This blog will walk you through setting up an Oracle Digital Assistant (ODA) skill that will be driven by an OPA Interview deployed to the OPA Chat API channel.  ODA supports various chat clients allowing the skill to power chatbots for Facebook, Slack, Skype and many more.

The backward chaining of OPA engine has meant that it has been long suited to driving web interviews.  Tell OPA what you want to investigate and it will work out what questions to ask to, in what order, to reach a conclusion.  When dealing a large number of screens and questions the fact that the engine is able to calculate which screen should be displayed and which questions are relevant to show saves a web developer writing lots of complex code - OPA simply decides the optimal screen to display until the conclusion is reached.  The same goal driven flow is also well suited to chatbots allowing the bot to ask only relevant questions to answer the user's 'Intent' (what the user is interested in knowing more about).  The combination of OPA to drive complex conversational flows with the user and ODA to provide the natural language processing is a powerful combination.  

A demonstration of the OPA and ODA can be seen here, you can also interact with the chatbot demo on Facebook Messenger here.


The credit for the component goes to Andrew Higginbottom, who originally developed the component against the Interview Service and moved the code over to the OPA Chat API once released, his feedback has been invaluable in making sure the OPA Chat API has all the required features.


Creating the ODA custom component

Either, build the code yourself allowing you to play with the custom component or download from here

If you planning on adding features to the component, see Developer Challenge section below, then it is worth starting with understanding the OPA Chat API which is described here.

Build Instructions

First download the code from https://github.com/oracle/opa-oda-chat.git

If you are using Visual Studio Code then you can clone the Git repository with the Git: Clone command in the Command Palette (⇧⌘P). You will be asked for the URL of the remote repository (as above) and the parent directory under which to put the local repository.

Install the ODA SDK - type 'npm install @oracle/bots-node-sdk@2.1.3'   in a terminal window ( at the time of publishing there was an issue with version 2.2.0).

Or use 'npm install --save-dev express'

Then build the component - type 'npm pack'  in the terminal window, in the root directory the build custom component opa-oda-chat-0.0.1.tgz will be created.

Creating a skill in ODA to test the custom component

We will not cover modification of the custom component in this blog but there is some excellent materials here that cover how to debug locally and develop features of the custom component.

Login to your ODA environment and then add a skill as below...

first create a Service and upload the *.tgz file created/downloaded in step 1

If the component has been successfully deployed as a Service then you should see the following 

Next, lets add an Intent to our skill so we can test the interaction.

Name the Intent and provide at least 5 sample utterances to test that they will match.  When you have setup click the Try It Out! link to test

Repeat this exercise a second time as ODA requires two intents to train the NLP engine.  Once you have two Intents set up then click the Train button in the top right hand corner.

Adding the YAML to call OPA via custom component

The next stage is to add the YAML to translate the utterances typed in the chat into the Intent into an action that calls OPA via the custom component. The example below should work with the encrypted credentials - if you want to point at your own OPA Hub then you will need to change the chatURL and authURL parameters and create an API client, help is here.  The details for the encryption of the parameters are covered in the Readme in the custom component.

There is also an unresolvedIntent to catch the utterances that don't match to the OPA intent.


YAML below...(if you struggle the exported skill is available here)

#metadata: information about the flow
#  platformVersion: the version of the bots platform that this flow was written to work with 
  platformVersion: "1.0"
main: true
name: OPABlogHelp

### OPA Variables ###
    chatClientId: "string"
    chatClientSecret: "string"
  setChatClientId: #OPA
    component: "System.SetVariable"
      variable: "chatClientId"
      value: "ou3Ey2UBUmEe0HzgQxlfwA=="
  setChatClientSecret: #OPA
    component: "System.SetVariable"
      variable: "chatClientSecret"
      value: "S8XoXQMmjtJa5u/JnDLyBw=="
#### Start State / Intent Matching
    component: "System.Intent"
      variable: "iResult"
        SimpleOPAInteraction: "goToOPA"
        unresolvedIntent: "unresolved"

#### OPA Intent
    component: "OpaInterview"
      botName: "simpleBot"
      chatURL: "https://gseopa00097.rightnowdemo.com/web-determinations/JSONChatStart/latest/KnowYourCustomer"
      authURL: "https://gseopa00097.rightnowdemo.com/opa-hub/api/auth"
      chatClientId: "${chatClientId.value}"
      chatClientSecret: "${chatClientSecret.value}"
      greeting: "Hi{user}. I can help you find out what banking products are suitable."
      offerRestart: "Would you like to check again?"
      farewell: "OK. You can ask me about something else if you like."
      maxPrompts: 1
      return: "done"

#### Unresolved Intent
    component: "System.Output"
      text: "Hello, I can help you with investigate OPA, type 'Show me OPA' to begin?"
      return: "done"

Now the fun part: - testing the default deployment

Once you have the YAML updated or the skill imported you are ready to use the ODA Test Chat Client.

Launch the Chat using the Play icon and then type Hi or Show me OPA to get started...

If you open the KnowYourCustomer deployment in Oracle Policy Modeling you can see that the labels correspond to the defined screens.

When the component is passed a list type control from OPA Chat client it renders the values as cards,  you can click on the card or type the value into the chat.

Special commands the component understands 

stop - this will exit from the OPA controlled dialog, if the component does not understand an answer this will also be fired.  
if you want to add additional stop words e.g. quit,  this can be configured in the YAML by adding      
      stopWord: "quit"
back - this will tell the OPA Chat API to 'undo' and go back a screen control.
if you want to add additional back words e.g. undo this can be configured in the YAML by adding      
      backWord: "undo"

For dates you can use natural commands such as Last Wednesday, First of this month


Developer Challenges

You should now be able to point to your own OPA deployments and test the existing component but as the component is a public GitHub repository you could add some features of your own.

A few ideas of features to look at

  1. Support the rendering of Forms returned by the OPA Chat API, there is an example at the end of the KnowYourCustomer example.  
  2. Render Read-Only values as chat messages, at the moment read-only answers are ignored by the component 
  3. Handle screen controls with default values, e.g. describe the default value in the message and have a blank message accept the default answer
  4. Provide an example of how to use Chat capabilities to capture GPS location and pass that to OPA, this may need some changes to the Chat API
  5. Improve the matching of chat responses to the answers expected by OPA

Let me know of any ideas you have or stuff that you are working on.



Join the discussion

Comments ( 1 )
  • Kritika Jain Thursday, March 19, 2020

    I want to have date input for Date of birth from intervew form to OPA in calender form in ODA side.How is it possible.And also I am not able to display table from interview form to ODA in tabular form.Please help.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.