Import the Starter Skill

1. Log into Oracle Digital Assistant.
2. Click in the top left corner to open the side menu.
3. Expand Development and then click Skills.
4. Hide the menu by clicking 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).

   

   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.
   
2. Enter hi.
3. Enter your name and and an amount.

   The skill returns a URL.

   

4. Instead of opening the URL, click Reset and then click then Close ()  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 () 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" 

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" 

16. 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. 

    

    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.

Import the Starter Oracle Visual Builder Application

1. Log into your Oracle Visual Builder instance.
2. In the Home page, click Import.

   

3. Choose Application from file.

   

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.

   

6. In the Home page, click your application.

   

   The Navigator's Welcome page displays.

   

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 (). Otherwise, click financialdispute, and then HTML ().

   

   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.

   

4. Next, click main and then open the Functions editor by clicking Functions  (). 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. 

   

   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.

   

   The application will open in a separate tab.

   

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

   

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 ().

   

   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.

Export the Oracle Visual Builder Application

To export the app:

1. Go to Oracle Visual Builder Home page by clicking 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 ().
3. Choose Export.

   

4. Click Export without Data.

   

   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.

   

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:

   

3. Navigate to build > optimized > webapps > financialdispute. The index.html file and the version_* folder are both in this directory:

   

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 *

   

   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.