article by Frank Nimphius, May 2021
Below are 3 examples for use cases that benefit from structured data entry in a chatbot conversation.
- Sensitive information such as credit card numbers that should not be displayed in the messenger's conversation history.
- For users to enter or edit a large amount of information that otherwise would result in very long chatbot conversations
- When the messenger does not provide convenient user interface to guide users (e.g. a calendar picker or dependent list-of-values)
Oracle Digital Assistant supports locally and remotely deployed web forms. For the Oracle Web SDK (Oracle web messenger), the web view can be displayed in a separate browser tab or integrated into the messenger so that users are not taken out of context. In this article I explain how you display web forms in the web messenger and also provide a sample that displays a Oracle JET10 based login form.
The Sample at Runtime
After importing the provided Oracle Digital Assistant skill and configuring Oracle Web Messenger, you can test the sample by starting the index.html file in a browser. Then open the messenger window by clicking the bot icon. A welcome message is displayed with the instructions shown in the image below.
Click the Login form button to launch the web form containing a username and a secret field. The sample does not perform any authorization and instead sends the information you enter to the bot. The key point to make is that the conversation history of the web messenger does not contain the provided username and secret and that the secret field does not even show clear text.
After pressing the Submit button, you will be prompted to click the Close link on the upper right corner fo the messenger. When you do this, the web form will close for the bot to continue the conversation.
Upon return from the login form, you see the information you entered in the form printed in a bot message to prove that the information was received. In a production bot, you would not echo sensitive information like this but use the information internally. If the use case was to display a web form for users to correct entries provided in a bot conversation, then of course you would acknowledge changes in a message response. So, use case matters.
Oracle Web messenger tutorial: https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorial-web-sdk/index.html
Dialog Flow and Skill Settings
The configuration in the skill is simple and uses a single dialog flow state that hosts a System.Webview component. The web form (in case of a local deployment) is referenced by its configuration name (see the service property in the image below). All other settings are for the prompt and labels, as well as for how to transition when one of the buttons got pressed.
Note: My sample uses resource bundles for the messages and labels. Some resource bundles receive information about the message channel that is used so the message can contain channel specific formatting (HTML markup in the case of the web messenger channel) without limiting the skill to be usable with a single messenger only.
The web form, any single page application (SPA) you build using Oracle JET or equivalent technologies, is registered in the custom component panel under the Webview tab. The name you give to the SPA deployment is the service name you reference from the System.Webview component.
Note: To upload the web form, you create a deployable ".tgz" file and drag & drop it to a new service configuration you create using the + Add Service button.
Configure the Demo on Your Oracle Digital Assistant Instance
Beside of importing the sample skill to your Oracle Digital Assistant instance, you need to configure the Oracle Web SDK (Web messenger) with your web channel Id and the Oracle Digital Assistant host URL (tenant URL)
Importing the Skill and creating a web channel
- Open your Oracle Digital Assistant instance in a browser and navigate to the skills panel
- Use the import button and import the displayingwebviews_21_05_01_.zip file you can download from here.
- Give the import a couple of minutes to complete.
- Create a web channel (see the product documentation)
- Associate the web channel with the imported skill
- Configure the channel as shown below. Note that setting "Allowed Domains" to "*" should only be done during testing, For production instances you should use a more restrictive whitelisting of domains or enable client authentication (JWT web tokens)
- Take a note of your Oracle Digital Assistant tenant URL (see your browser URL window and copy the host name without "https://" and any following slashes
Oracle Web SDK Configuration
After downloading the sample Oracle Digital Assistant Web SDK from here , you need to unzip it. In the unzipped sample client, navigate to the samples > web folder. The index.html file is what you need to open in a browser after completing the configuration steps I am explaining next
Navigate into the scripts folder and open the settings.js file in a JavaScript editor or a text editor.
- Go to line 164 and replace the current URL with the host URL of your tenant (The URL that is in the settings file as a placeholder does not work).
- replace the channel ID in line 169 with your web channel ID (The channel ID that is in the settings file as a placeholder does not exist).
- Next, launch the index.html file in a browser and open the web messenger. If your configuration works, then you should see the welcome message with the instructions.
What You Should Know
The Oracle Digital Assistant Web messenger has a declarative functionality that allows you to open any URL in a conversation within a custom inlineFrame you add to your page. For displaying the webview, we don't use this option so it remains available for other URLs. Instead, as shown below, the sample uses a delegate object to open the webview in place.
Oracle Digital Assistant webviews that are deployed to the embedded container always use /connectors/v2/webviews/ in their URL path.
The delegate object, which is called before any bot message renders on the client, uses this information to distinguish webviews from other URLs. If a webview link is identified, the JavaScript code change the action type of the message from "url" to "webview".
This then leads to the webview URL to be opened in the hidden iFrame contained in the messenger.
Also in the settings.js file, there is a configuration property webViewConfig that contains useful settings like the title of the web view window and how much of the underlying chat window should be hidden by the webview. In the sample the webview is configured to fully hide the conversation box. In addition, I set the close link to only display the label "close".
Understanding the Oracle JET app and deployment
I provided the Oracle JET source code for the webview for you to explore. You can download the JET source code from here.
After unzipping the ZIP file, you see the following folder structure (see image)
The index.html file contains the Oracle JET UI components (an inout field, a secret field, a read-only message field and a button). The binding logic that makes the form work is contained in the main.js file located in the js folder.
Oracle JET code explained
- line 67 – 69 – binding definition that allows to read and write information to the inout fields
- line 75 – reads the request parameters sent from the Oracle Digital Assistant chatbot. the parameters contain input parameters and a call back url parameter. The latter is used in this sample (the sample does not require any parameter sent from the bot).
- 79 – 87 – A useful helper function that allows you to read request parameters by their name.
- line 94 – A call to obtain the callback URL to pass user input entered in the web form to the bot. It uses the function shown in lines 79-87
- line 96 – 119 – When the submit button is pressed, the user input is read from the username and the password (secret field). The information is then returned to the bot using the callback URL retrieved earlier. After 500 ms, a message is displayed to the user that it is now good to close the webview window to continue with the conversation in the chatbot.
The values returned from the webview are stored in the dialog flow variable referenced from the System.Webview variable property (see image below). To access e.g. the returned "username" result, you use ${webviewResponsePayload.value.username}.
Oracle JET code deployment
If you changed the Oracle JET code and what to deploy it into the skill, you need to create a .tgz package for it. For this, you
- run npm install in the root folder to ensure all dependencies are loaded
- use the Oracle JET command-line interface to create a release version
- ojet build –release
- ojet server –release
- Navigate to Oracle JET project's 'web' folder and issue the following command to create a deployable package: tar -zcvf <name of package file>.tgz *
You can then replace deployed webview with your tgz file
Related Tutorials
Building Webviews for Local Deployment to Oracle Digital Assistant using Oracle JET
Access a Skill from Your Website (Oracle Web messenger tutorial)
Oracle JET Getting Started and Cookbook reference
