Oracle by Example brandingCreate a Webview from an Oracle Visual Builder Application

section 0Before You Begin

This 45-minute tutorial shows you how to integrate a single-page app (SPA) authored in Oracle Visual Builder with Oracle Digital Assistant.

Background

Adding webviews to your skill allows it support structured data input through UI elements like forms, date pickers, fields, and LOVs. In Oracle Digital Assistant, the web apps that are delivered within the chat as webviews are single-page apps (SPAs). By completing this 45-minute tutorial, you will learn how to use Oracle Visual Builder to declaratively build a SPA and then integrate it with a skill.

The use case for this tutorial is a credit card dispute service. Digital Bank, a fictitious bank, wants to reduce the waiting time and effort spent by their customers to settle credit card disputes. To this end, Digital Bank prefaces its approach on the following:

  • Users dispute their credit card transactions through a skill.
  • Users log a dispute by completing a web form that's delivered as a webview.
  • The skill that supports the webview runs on a web channel, meaning that the web form will open in a separate browser tab.
  • The skill collects an initial set of information from the user before it displays a link to a webform for entering details about the dispute.
  • The information captured by the skill is passed to (and populated in) the dispute form.
  • Once a user completes the form, the skill conversation continues.

What Do You Need?

  • Access to an Oracle Digital Assistant instance, Version 19.1.5 or higher.
  • Access to Oracle Visual Builder, Version 19.1.3 or higher.
  • An installation of Node.js.

    In the tutorial, you'll use node package manager (npm), which is distributed with Node.js, to run the web messenger client app from your local machine.

    To ensure you have Node.js installed, run the following command in from a command line in a terminal (Mac) window or a command (MS Windows) window:

    node -v

    To ensure that npm has been installed, run:

    npm -v

  • The resources.zip file, which includes the starter skill and a finished version of the skill for your reference, along with starter and final versions of the SPA. Click here to download this file and then unzip it to your local system.



section 1Prepare the Skill

Import the Starter Skill

  1. Log into Oracle Digital Assistant.
  2. Click menu icon in the top left corner to open the side menu.
  3. Expand Development and then click Skills.
  4. Hide the menu by clicking menu icon again.
  5. Locate the FinancialDisputeBot starter skill. Then click Clone.

    If you can't locate the skill, click Import Skill (located at the upper right).

    An image of Skills dialog box with the Import Skill button highlighted.
    Description of the illustration.
    Browse to, and then select, FinancialDisputeBot_starter.zip. Then click Open.

Explore and Test the Skill

Take a look at the intents and entities.

  1. Click the Skill Tester in the left navbar.
    Skill Tester icon
  2. Enter hi.
  3. Enter your name and and an amount.

    The skill returns a URL.

    Description of sample-arch-image.png follows
    Description of the illustration.

  4. Instead of opening the URL, click Reset and then click then Close (The Close icon)  to dismiss the tester.

What you just did: You just setup and tested the FinancialDisputeBot starter skill. The skill asks users to enter basic dispute information and provides a URL for users to fill the webform.

Right now, the skill has the following drawbacks:

  • The information captured in the skill could not be sent to the URL.
  • The results from dispute web application could not be sent back to the skill.

In short, the skill and web application are two separate entities that do not share any contextual information.

Configure the Skill to Call the Web App

In this section, you will configure your skill to call a web app that is hosted within Oracle Digital Assistant. In this step, you'll configure the dialog flow.

  1. Click Flows (The dialog flow editor icon) in the left navbar.
  2. In the variables node, add a variable called outputfromweb that stores data received from the web app (a string). When you're done, the variables node should look like this:
    context:
      variables:
        fullname: "string"
        amount: "string"
        outputfromweb: "string"    
  3. Next, add the state that calls the web app. First, click + Components, then choose User interface, then Webview.
  4. Choose askAmount in the Insert After menu.
  5. Switch on the Remove Comments toggle and then click Apply.
  6. Change the name of the added dialog flow state from textResponse to webview.
  7. Define the following properties:
    Property Value
    sourceVariableList "fullname,amount"
    variable "outputfromweb"
    prompt "Please tap on the link to proceed."
    service "DisputeFormService"
  8. For the transitions property, replace
          actions: 
            someAction:
            
    with
          next: "output"
          actions:
            textReceived: "onCancel"
            cancel: "onCancel"
  9. Delete the unneeded properties, so that the webview state looks like this:
    webview:
        component: "System.Webview"
        properties:
          sourceVariableList: "fullname, amount"
          variable: "outputfromweb"
          prompt: "Please tap on the link to proceed"
          service: "DisputeFormService"
        transitions:
          next: "output"
          actions:
            textReceived: "onCancel"
            cancel: "onCancel"
  10. In the output state, update the text property as follows:
    text: "Thank-you ${fullname.value}, we have noted your response - ${outputfromweb.value.disputeReason}"
  11. Add the onCancel state that handles cancel and textReceived actions, by clicking + Components, then User interface, then Output.
  12. Choose output from the Insert After menu, switch on Remove Comments, then click Apply.
  13. Rename the state onCancel.
  14. Define the text property as "I'm sorry that you have canceled your dispute request."
  15. Add the following transition to end the dialog:
        transitions:
          return: "done" 
  16. When you're done, the onCancel state should look like this:

      onCancel:
        component: "System.Output"
        properties:
          text: "I'm sorry that you have canceled your dispute request."
        transitions:
          return: "done" 
  17. Click Validate. Oracle Digital Assistant returns an error because you haven't yet configured the DisputeFormService Webview Service that connects the skill to the web app. 
    Description of the image follows
    Description of the illustration.
    You'll do this in the next section. If you're encountering errors besides this one, replace your dialog flow with this one.

What you just did: In this section, you updated FinancialDisputeBot skill to call a Webview Service named DisputeFormService using the System.Webview component. The full name and the amount are passed to the web app. The web application response will be saved in variable named outputfromweb. Once the web app is done, the skill confirms that the response from web application has been noted.


section 1Prepare the Oracle Visual Builder Web App

In this section, you're going to create Oracle Visual Builder web app, export it, and then host it in Oracle Digital Assistant.

To create this app, you'll use the starter application called FinancialDisputeSPA_starter.zip.

Import the Starter Oracle Visual Builder Application

  1. Log into your Oracle Visual Builder instance.
  2. In the Home page, click Import.
    Description of this image follows
    Description of the illustration.
  3. Choose Application from file.
    Description of this image follows
    Description of the illustration.
  4. Click Upload a file or drag it here, then select, the FinancialDisputeSPA_starter.zip file.
  5. After you upload the file, rename it to <your_initials>_FinancialDispute. Then click Import.
    Description of this image follows
    Description of the illustration.
  6. In the Home page, click your application.
    Description of this image follows
    Description of the illustration.
    The Navigator's Welcome page displays.
    Description of this image follows
    Description of the illustration.

Explore and Test the Oracle Visual Builder Application

Now let's explore the starter application and run it.

  1. If the Navigator's Web Application's tab is not already open, click Web Applications (The Web Applications icon). Otherwise, click financialdispute, and then HTML (The HTML icon).
    Description of this image follows
    Description of the illustration.

    This HTML file, which is called index.html, is the main entry point of this web application. In the following section, you are going to fetch parameters sent by the System.Webview component that you configured in the FinancialDispute skill.

  2. In the left pane, expand main and then click main-start. This is the Financial Dispute page design layout that will appear once the application is launched.

    Note: The Design option should be selected by default, but if it isn't, select it. 

  3. Next, click main-thanks to view the design layout. This page appears after a user submits or cancels the dispute.
    Description of this image follows
    Description of the illustration.
  4. Next, click main and then open the Functions editor by clicking Functions  (The Functions icon). Take a look at the function that's invoked when a user clicks the Submit or Cancel buttons. It makes a POST call to the callback URL that's received from the skill. This call includes the parameters that were received from the Submit or Cancel buttons. 
    Description of this image follows
    Description of the illustration.

    When a customer clicks the Submit button, the dispute option that they have chosen gets passed to the submitDisputeInfoToDA call module function. Similarly, when users click the Cancel button, the cancel information is passed to the submitDisputeInfoToDA call module function. It makes a POST call to the skill to send the payload in following format:

    {
    	"disputeReason" : "DISPUTE REASON"
    	
    }
  5. Click Run.
    Description of this image follows
    Description of the illustration.

    The application will open in a separate tab.

    Description of this image follows
    Description of the illustration.
  6. Click Submit Dispute. At this point, the submitDisputeInfoToDA function is called, enabling navigation to the next page:
    Description of this image follows
    Description of the illustration.

Prepare the Oracle Visual Builder Application So That It Can Be Called by the Skill

You need to update FinancialDispute application to receive the input parameters and callback URL injected by the FinacialDisputeBot skill, but before we do that, let's take a look back at the webview state in the dialog flow.

In the sourceVariableList variable, the skill passes fullname and amount to the calling application. Along with these parameters, a third parameter, webview.onDone gets added automatically to pass the callback URL. The data is added to the web app’s index.html file.

  webview:
    component: "System.Webview"
    properties:
      sourceVariableList: "fullname,amount"
      variable: "outputfromweb"
      prompt: "Please tap on the link to proceed"
      service: "DisputeFormService"
    transitions:
      next: "output"
      actions:
        textReceived: "onCancel"
        cancel: "onCancel" 

You need to code the web app to take these input parameters and the callback URL that are sent from the System.Webview component. You can configure the app to access the incoming payload in various ways, but to make things easy, we're going to add placeholders that match the names of the source variables to the <script> block and prefix each of them with webview. At runtime, these placeholders will be replaced by the respective data and the callback URL (webview.onDone), which is a JSON-encoded string.

To make this change in the FinancialDispute application:

  1. Select financialdispute in the left navigation pane and then click HTML (The HTML icon).
    Description of this image follows
    Description of the illustration.
    Take a look at the following code in script block:
       window.name = "__YOUR_NAME__";
       window.amount = "__DISPUTE_AMOUNT__";
       window.CALLBACK_URL = "__CALLBACKURL__";
  2. Edit these lines as follows:
       window.name = "webview.fullname";
       window.amount = "webview.amount";
       window.CALLBACK_URL = "webview.onDone";

    These changes are auto-saved.

    Note: window.vbInitParams passes this information to a sub-page, which in this case, is the main-page.

       window.vbInitParams = {
         name, amount, postbackURL
       };
  3. Click Run to ensure that there are no errors.

What you just did: In this section, we updated the Oracle Visual Builder web application, so that it should be able to fetch the input variables and callback URL from the FinancialDisputeBot skill. The Oracle Visual Builder application is now ready. In the next step we will export and optimize this app so that it can be hosted in Oracle Digital Assistant local container.


section 3Export and Build the Oracle Visual Builder Application

To deploy the Oracle Visual Builder application to Oracle Digital assistant, you need to export it and build it with Grunt. As part of the build process, you'll compile the app into a format that can be consumed by the Oracle Digital Assistant local container.

Export the Oracle Visual Builder Application

To export the app:

  1. Go to Oracle Visual Builder Home page by clicking the Home icon (The Home icon) located at the upper left and then click All Applications from the left menu.
  2. Locate the row for your app, and then expand the Application Options menu (The Application Menu icon).
  3. Choose Export.
    Description of this image follows
    Description of the illustration.
  4. Click Export without Data.
    The Export dialog.
    Description of the illustration.

    The application will be downloaded on your local machine.

Build the Oracle Visual Builder Application

  1. Unzip your application and then run npm install on the root folder. This will install the node dependencies required to build the application. The install command retrieves the grunt-vb-build NPM package defined in the package.json file.
    Description of this image follows
    Description of the illustration.
  2.  Enter the following at the command prompt:
    ./node_modules/.bin/grunt vb-build \
        --url=<url of visual builder application> \
        --username=<username> \
        --password=<password> \
        --id=<your visual app ID> \
        --ver=<your visual app version> \
        --git-sources=<local directory for sources>    

    The options that you need to define are as follows:

    Property Value
    url
    The URL for your VB instance (which includes ic/builder).
    username
    The user name.
    password
    Your password.
    id The name of your Oracle Visual Builder app as it appears on the Home page.
    ver The app's version (noted in the in the Home page).
    --git-sources The path of the directory where you have downloaded the exported ZIP
     file.

    Various grunt tasks execute after you run the command:

    Description of this image follows
    Description of the illustration.

  3. Navigate to build > optimized > webapps > financialdispute. The index.html file and the version_* folder are both in this directory:
    Description of this image follows
    Description of the illustration.
  4. Open your command prompt and then navigate to the financialdispute directory (build > optimized > webapps > financialdispute).
  5. Create the archive using following command:
    tar -zcvf financial_dispute_form.tgz *
    Description of this image follows
    Description of the illustration.

    An archived file named financial_dispute_form.tgz is created. Your Oracle Visual Builder application has been exported and optimized, and at this point, it can be consumed by Oracle Digital Assistant.


section 4Create the Webview Service

 In this step, you'll create the Webview Service that registers the Oracle Visual Builder app. To complete this task, you'll need the financial_dispute_form.tgz file. 

  1.  In Oracle Digital Assistant, open your FinancialDisputeBot skill (if it's not already open).
  2.  Click Components (The Components icon.) in the left navbar and then select the Webview tab.
    Description of this image follows
    Description of the illustration.
  3. Click + Service.
  4. Enter DisputeFormService in the Name field. Note that this name must match the service property for the System.Webview component.
  5. Browse to, then upload the financial_dispute_form.tgz file.
    Description of this image follows
    Description of the illustration.
  6. Click Create. The service will be listed under Webview tab. If Oracle Digital Assistant can't create the service with your TGZ, upload the version financial_dispute_form.tgz that we provide, which is located in the resources folder.
    Description of this image follows
    Description of the illustration.
  7. Click Flows in the left navbar and then click Validate. There should be no more errors now since the service is created.

section 5Test the Skill

  1.  Click Skill Tester in the left navbar.
  2.   Enter hi.
  3.  Enter your first and last name.
  4.  Enter the dispute amount. For example, enter 100 USD.
  5.  When prompted, select Tap to Continue. The Financial Dispute application opens in another browsers tab. Note that the fullname and amount values are  passed to the web application.
    Description of this image follows
    Description of the illustration.
  6.  Complete the form (the main page of the app) by first choosing an option and then by clicking Submit Dispute.
    Ths Skill Tester
    Description of the illustration.
  7. Click Submit. The screen will be redirected to next page and a call will be made back to the skill.
    Description of this image follows
    Description of the illustration.

section 6Summary

Through this tutorial, you found out how a skill can pass values to, and receive values from, a web app by configuring the dialog flow with the System.Webview component. You also learned how to configure the Oracle Visual Builder SPA to receive values and pass them back to the skill and how to build an optimize the app so that it can be hosted within Oracle Digital Assistant.


more informationWant to Learn More?