Oracle by Example brandingDebug Custom Components Locally

section 0Before You Begin

This 45-minute tutorial shows you how to debug a custom component service in the context of a skill's conversation in Oracle Digital Assistant.

Background

Custom components are reusable units of custom code that you can call from your skill's dialog flow. If you need to debug a custom component, you can run the custom component service on a local Node Express server and point your skill to that external service.

In this tutorial, you'll debug and fix a problem in a custom component. You'll learn how to:

  • Run custom components in a local Node Express server using the Oracle Bots Node.js SDK.
  • Add the custom component service as an external service for your skill.
  • Connect JavaScript IDEs, such as Microsoft Visual Studio Code, to the node server that's running on your local machine.
  • Debug custom components in the context of a skill conversation.

This tutorial is for developers who are familiar with JavaScript and Node.js. You should also be familiar with implementing custom components. If you are new to custom components, please complete the Create Custom Components to Integrate with Backend Services tutorial first.

What Do You Need?

To complete this tutorial, you need:

  • Access to an Oracle Digital Assistant instance.
  • A JavaScript IDE that supports Node debugging. For example, Microsoft Visual Studio Code, which this tutorial uses in its screenshots and instructions.
  • Node.js and Node Package Manager (NPM) installed for global access. If you used a Windows or Mac Node installer, then both the node and npm executables should be available to you. To test if you have Node.js and NPM installed, open a terminal window and enter the following commands separately:

    $ node -v

    $ npm -v

  • If your computer isn't available as a server to the Internet, you'll need to use tunneling software such as ngrok, which the tutorial uses in its instructions, or localtunnel. You must either own the computer that you use for this tutorial or your IT administrators must allow you to use tunnelling software. Otherwise, you can't complete the debugging sections in this tutorial, and you'll need to use logging to debug custom component services.

section 1Import or Clone the Quote Of The Day Skill

In this tutorial, you use a quote-of-the-day skill, which we provide, to explore and debug the custom component service. If this skill exists in your instance, you can clone it. Otherwise, you must import it.

Clone the Quote Of The Day Skill

Here are the steps for cloning the Quote Of The Day Skill. If this skill isn't in your instance, skip to the next section for instructions on how to import it.

  1. To open the Oracle Digital Assistant instance, open a browser and go to <your-instance-url>/botsui.
  2. Click icon to open side menu on the top-left corner of the page to expand the side menu.
  3. Expand Development and select Skills.
    Main Menu
  4. Click icon to open side menu again to hide the side menu.
  5. In the Skills dashboard, type quote of the day in the Filter field to find the Quote Of The Day Skill.

    If the Quote Of The Day Skill isn’t available in your instance, then skip to the next section to import it.

  6. On the Quote Of The Day Skill card, click Options Options, and then select Clone.
  7. Name the skill <your initials>_Quote Of The Day Skill, or use any prefix that creates a name that's unique to the instance. For example, FN_Quote Of The Day Skill.
  8. Enter a short description.
  9. Select Open cloned skill afterwards, and then click Clone.

Import the Skill

If your instance doesn't have the Quote Of The Day Skill, then import the one that we provide.

  1. Download quote-of-the-day-skill-1.0.zip to your local machine.
  2. To open the Oracle Digital Assistant instance, open a browser and go to <your-instance-url>/botsui.
  3. Click icon to open side menu on the top-left corner of the page to expand the side menu.
  4. Expand Development and select Skills.
    Main Menu
  5. Click icon to open side menu again to hide the side menu.
  6. Click import skill button to start the import process.
  7. Browse to the folder where you saved the dowloaded quote-of-the-day-skill-1.0.zip file, select it, and then click Open to upload and install the skill.
  8. Locate your Quote of the Day Skill and click it's tile to open it.

    If you don't see the skill, type quote of the day in the Filter field to find it.


section 2Explore the Quote Of The Day Skill

Let's take a look at the skill that you just created.

  1. In the Quote of the Day Skill, click Skill Tester Skill Tester, which is located near the bottom of the left navigation bar.
  2. Enter hi in the message field.
  3. When prompted, provide a name.
  4. You should see a message similar to the one below:
    Tester
  5. Notice that, although you provided a name, the skill response contains Hi undefined.
  6. Click Reset link to clear the context variable values.
  7. Click Close button to close the tester.
  8. Click Flows Dialog flow editor icon to open the dialog flow editor.
  9. Note that the askName: state on line 11 prompts the user for a name and the getQuote: state on line 16 passes the provided user name as an input property to the custom component.

    The dialog flow seems to be correct. Therefore, the problem that the user-entered name doesn't print might be caused by an error in the custom component.

  10. Click Components Components icon to open the component service page.

    Notice QuotesCustomComponentService, which is deployed to the embedded container.

    Custom component

section 3Install the Oracle Bots Node.js SDK

The Oracle Bots Node.js SDK is a Node module for building and deploying custom component services for Oracle Digital Assistant. You'll need this SDK when you debug your custom component service. If you haven't already, install the Oracle Bots Node.js SDK on your local machine.

  1. Open a terminal window.
  2. If your Internet access is through a proxy, then you might need to do the following to be able to install the Oracle Bots Node.js SDK from the Internet. An alternative is to find a way to access the Internet without using a proxy, such as by using a mobile hotspot.

    • To get the external IP address of your proxy, open a browser and go to http://www.whatismyproxy.com/.
    • In the terminal window type:

        npm config set proxy http://<external_ip>:80
      npm config set https-proxy http://<external_ip>:80

  3. To install Oracle Bots Node.js SDK for global access on your laptop, type this command:
    npm install -g @oracle/bots-node-sdk
    On a Mac, you use the sudo command:
    sudo npm install -g @oracle/bots-node-sdk
    Tip: You can click Copy in the code box to copy its contents.
  4. To verify the success of your installation, type:
    bots-node-sdk -v
    The command should print the Oracle Bots Node.js SDK version.

section 4Run the Custom Component Service on Your Computer

To debug the custom component service, you must first run it on your local computer. That way, you'll later have a local process that you can connect to from your IDE. The full custom component service source code is in a ZIP file that we provide.

  1. Download quote-of-the-day.zip to your local computer.
  2. Unzip the file into a folder that doesn't contain spaces in its name or path.
  3. Open a terminal window in the directory that contains the quoteoftheday folder.
  4. Issue the following command:
    bots-node-sdk service quoteoftheday

    The output will look similar to this:

    ---------------------------------------------------------------------
    Component Service Ready (no auth):
            http://localhost:3000/components
    ---------------------------------------------------------------------
    quoteoftheday    =>    oracle.sample.QuoteOfDay

    The bots-node-sdk service quoteoftheday command starts the Node Express server to run the custom component. The Express server is part of the custom component service project. It's added automatically when you initialize your custom component project.

  5. Open a browser window and go to localhost:3000/components.
  6. If the service started successfully, you'll see a server response that displays the component service version and the component's name, properties, and supported actions, as shown here:
    Express server test show component details

    The response is from the custom component metadata definition. It's the same information that Oracle Digital Assistant reads when you register the custom component service in a skill. This response indicates that the Node Express server is up and running, and that the custom component is accessible.

    Note that by default, the Node Express server listens on port 3000. You can change the port number with the following command:

    bots-node-sdk service quoteoftheday --port <port-number>

    For example, use bots-node-sdk service quoteoftheday --port 4000 to start the Node Express server on port 4000.


section 5Expose the Component Service to the Internet

Typically, your local computer isn't available as a server to the Internet. To make it available, you'll need to create a network tunnel as described in these steps.

As mentioned earlier, this tutorial uses the ngrok tool to create the tunnel. If you aren't able to use ngrok, you can try other tunnelling solutions such as localtunnel on GitHub. If you don't own the computer you are working on, and if your IT administrators don't allow you to use tunnelling software, then you can't complete the debugging sections in this tutorial. Instead, you can use logging to debug custom component services.

Important: Before using ngrok, ensure that you learn what it is and what it does so that you understand how it works and what the possible risks are. Ensure that you adhere to your company security policies.

This section assumes that the Node Express server listens on port 3000.

  1. Download ngrok from https://ngrok.com/download. The free ngrok offering is sufficient for this tutorial.

    If you get security warnings, try opening the link in a private window (Firefox) or an incognito window (Chrome).

  2. Navigate into the folder in which you installed ngrok.
  3. Launch ngrok.

    Use this command for Windows machines:

    ngrok http <port>

    Use this command for all other operating systems:

    ./ngrok http <port>

    This screenshot shows an ngrok process that was started to listen on port 3000. Notice that the Session Status field shows online, and that it shows the Forwarding URLs for HTTP and HTTPS requests.

    ngrok started

  4. Open a browser window, and then go to the following forwarding URL:
    https://<https-forwarding-url>/components

    The request response should display the custom component's description as shown here.

    ngrok test in browser

    Note: A new URL is generated each time you stop and start ngrok.


section 6Add the External Custom Component Service

To debug the custom component service that's running on your local machine, you'll add a second component service to the skill. When you add the local service, you'll use the External configuration option.

  1. In the skill, click Components Components icon to open the component service page.
  2. Click + Service button to add a custom component service.
  3. Name the service QuotesDebugging.
  4. Provide a brief description.
  5. Select the External option.
  6. Set metadata URL to your ngrok fowarding URL with the /components extension. It's the same URL that you used to test your ngrok configuration in a browser.

    If you forget to add /components to the URL, then you'll get a 404 error when you create the service.

  7. The service isn't password protected. So set the User Name and Password fields to None. The configuration should look similar to the one shown below. Your ngrok URL will be different from the one shown in the screenshot.
    creating new custom component service
  8. Click Create. The skill now attempts to access your local custom component service to register its components. After the registration completes successfully, the QuotesDebugging custom component service should be similar to this screenshot.
    successfully registered component
  9. The same custom component service is now configured twice. Before you can debug the custom component service running on your local computer, you must disable the component service that's deployed to the embedded container.

    Select QuotesCustomComponentService and switch Service Enabled to Off, as shown here:

    disabled service
  10. To test the skill, click Skill Tester Skill Tester
  11. Enter HI in the message field.
  12. When prompted, enter a name such as Frank.

    If your external custom component service works, you should see a quote. Notice the Hi undefined message, which is the same error that you saw when you tested the custom component service that was deployed to the embedded container.

    custom component testing
  13. Click Reset to clear the conversation and the context variables.
  14. In the terminal window in which you started the custom component service's Node Express server, you should see some log messages similar to the ones shown here. One of the log messages will be User name: undefined
    $ bots-node-sdk service quoteoftheday
    ---------------------------------------------------------------------
    Component Service Ready (no auth):
            http://localhost:3000/components
    ---------------------------------------------------------------------
    quoteoftheday    =>    oracle.sample.QuoteOfDay
    
    Invoking component oracle.sample.QuoteOfDay
    Opening quote generator
    User name: undefined
    creating messageModel with payload
    valid messageModel
    Quote found: 'It’s Not What We Teach; It’s What They Learn'
    
     Quote by: Alfie Kohn
    creating messageModel with payload
    valid messageModel

section 7Configure Microsoft Visual Studio Code for Debugging

You can use any IDE that supports Node.js debugging. Here are the configuration steps if you're using Microsoft Visual Studio Code.

  1. Open your JavaScript IDE.
  2. Click File, click Open Folder, and then navigate to and open the quoteoftheday project folder.
    Open quoteofday folder
  3. In Visual Studio Code,click Debug debugging icon in the side activity bar to open the Debug view.
  4. Click the configuration drop-down list, which currently displays No Configurations, click Add Configuration, and then click Node.js as shown here.
    Selecting the Node.js debug option
  5. In the opened tab, click Add Configuration.
    Add Configuration button
  6. In the opened dialog, select Node.js: Attach to Process.
    Select Attach to Process option
  7. Save your changes.


section 8Debug the Custom Component

If you have successfully completed all of the preceding steps, the following things should all be true:

  • The quoteoftheday custom component service is running in the local Node Express server (default port is 3000).
    Node Express instance
  • Your local machine is accessible from Oracle Digital Assistant using ngrok or a similar technology.
    ngrok
  • Your skill has an external custom component service that points to the custom component service running on your local computer.
  • You opened the quoteoftheday custom component service project in your IDE, and you configured it for debugging through the attach-to-process method.

Connect the Debugger to the Service's Process

Here's how you attach the debugger using Microsoft Visual Studio Code.

  1. In Microsoft Visual Studio Code, click Debug debugger in the activity bar that's on the side.
  2. Select Attach by Process ID from the DEBUG configuration drop-down list.
    Attach to Process Id option
  3. Click the green triangle Run icon.
    start debugging
  4. Select the quoteoftheday service in the opened dialog.
    quote of the day service

Debug the Custom Component Code

Now we'll set a breakpoint and step through the code to see what's happening. Here are the steps using Microsoft Visual Studio Code.

  1. Click Explorer Visual Code Explorer icon in the activity bar.
  2. Expand the components folder and open the QuoteOfDay.js file.
    Selecting QuoteOfDay.js file
  3. Set a breakpoint in line 25. In Microsoft Visual Studio Code, you click in the margin to the left of the line number column to set a breakpoint.
    Setting a breakpoint
  4. Go back to the Quote Of The Day Skill, which you should still have open in your browser.
  5. Click Skill Tester Tester icon to open the tester.
  6. Enter hi in the message field.
  7. When prompted, provide a name.
  8. Switch to your IDE. The breakpoint should be highlighted as shown here for Microsoft Visual Studio Code.
    breakpoint in MS Visual Studio Code
  9. Hover the mouse over the usr variable in line 25. A popup should open and display undefined.
  10. In line 25, click the usr variable to see all of its uses. The goal is to find the variable definition, which is in line 17 as shown in this screenshot.
    Find definition of user variable
  11. In line 17 you can see that the usr variable value is read from conversation.properties(). Therefore, you can assume that there's a problem with this call.
  12. In line 17, hover the mouse cursor over the conversation variable. The conversation handle is a reference to the custom component SDK, and it contains all the information that was passed in the skill's request-message payload.
  13. In the popup dialog, expand the _request node, and then expand the properties subnode as shown here.
    Introspecting the properties

    Notice that there's a user property, which has a value ("Frank" in this screenshot). Apparently, there isn't a usr property, but there's a user property. This means that you've found the problem in the custom component code.

  14. To fix the problem, change the usr variable in the payload definition to user. To do this in Microsoft Visual Studio Code, right-click the usr variable, click Change All Occurences, and change the name from usr to user.
    Rename symbol

    Your code should now look like this:

    change variable name
  15. Save your changes.

Retest the Custom Component

Before you can retest the custom component, you need to restart the Node Express server that runs the custom component service on your local machine. The restart is required for the code changes to take effect. You don't need to restart the tunneling software (e.g. ngrok).

  1. Go to the terminal window that you used to launch the quoteoftheday custom component service.
    terminal window executing the component
  2. Press Ctrl+C to stop the process.
  3. Enter this command to restart the service:
    bots-node-sdk service quoteoftheday

    After you restart the service, verify that the tunnel URL is still valid. If not, restart the tunnel, and then update the component service's Metadata URL in the skill's Components page.

  4. In Microsoft Visual Studio Code, click Debug debugger in the activity bar.
  5. Ensure that the Attach by Process Id option is selected as the DEBUG option.
    Attach to Process Id option
  6. Click the green Run icon to restart the debugger.
    start debugging
  7. Select the quoteoftheday service in the opened dialog.
    quote of the day service
  8. Switch to the Quote Of The Day Skill in the browser.
  9. If the skill tester isn't open, click Skill Tester Tester.
  10. The previous debugging session has probably expired. Click Reset in the skill tester to clear the conversation.
  11. In the message field, enter Hi.
  12. When prompted, enter a name.
  13. In your IDE, hover the mouse over the user variable in line 25. You should see the name that you provided.
    corrected variable value
  14. Finish debugging by clicking Continue in the debugger toolbar (it's the first icon on the left in the screenshot below), or by pressing F5.
    Finish debugging
  15. Switch to the skill tester. You should see a message similar to the one in the image below. Notice that the provided name is included in the skill response.
    Working skill conversation
  16. Click Reset.
  17. Close the skill tester.

Stop Processes

Now that the problem is solved, you can close the following terminal processes and software:

  • Press Ctrl+C to close the tunnel, e.g. ngrok. For security reasons, always close the tunnel software immediately after you no longer need it.
  • Press Ctrl+C to stop the Node Express server that runs the local custom component service.
  • Close the JavaScript IDE.

section 9Re-Deploy and Test the Custom Component

Re-Deploy the Custom Component Service to the Embedded Container

  1. Open a terminal window and navigate to quoteoftheday folder.
  2. To package the modified custom component service project for deployment, enter this command:
    npm pack

    Because of the prepack script in the package.json file, the command first executes this command to verify the package:

    npm run bots-node-sdk -- pack --dry-run

    The command then packages the Node project into a deployable tarball, my-custom-component-1.0.0.tgz.

  3. Switch to the Quote of the Day Skill in the browser.
  4. Click Components Components icon to open the component service page.
  5. Select the QuotesCustomComponentService component service.
    Selecting the QuotesCustomComponentService
  6. Click Change.
  7. In the opened dialog, navigate to the quoteoftheday folder, and then select the my-custom-component-1.0.0.tgz file.
    Select tgz file
  8. Click Open to re-deploy the custom component service.

    Note: Re-deploying the custom component service also switches Service Enabled to On.

  9. Select the QuotesDebugging component service that you used for debugging.
  10. Click Delete to remove the external service.
    Delete
  11. After you delete it, you should have a single component service.
    remaining component
    Tip: If you want to keep the custom component service that you used for debugging, you can switch Service Enabled to Off, so that it is inactive. For this to work, don't stop the tunnelling software and the local Node Express server until after you disable the service.

Test the Re-Deployed Component

Even though you saw that the bug was fixed at the end of your debugging session, you'll want to verify that the embedded service is also fixed.

  1. Click Skill Tester Tester icon.
  2. Enter Hi in the message field.
  3. When prompted, provide a name.
  4. The skill response should contain the provided name in a message that similar to the one shown here, which is Hi Frank. Here's a quote for you.
    Final proof

section 9Validate the Dialog Flow

You've debugged and fixed the custom component, and you've verified your fixes by testing it in the skill tester. There's one more test that you should do — validate the dialog flow.

  1. Click Flows Dialog flow editor icon to open the dialog flow editor.
  2. Click Validate in the top bar.

    You'll see a message like this:

    We found some problems with the Quote of the Day Skill skill bot. Open the logger window to see more details.
  3. Click View problems affecting this skill bot Bug icon to view the list of dialog flow errors.

    You should see error descriptions like the ones in the following screenshot. They indcate that the state is missing the name property, and that it's passing the user property, which is not a valid property for the custom component.

    Validation errors
  4. In your IDE, look at the metadata section, which is shown below, and look at the properties object.
      metadata: () => ({
        name: 'oracle.sample.QuoteOfDay',
        properties: {
          name: {
            required: true,
            type: 'string'
          },
        },
        supportedActions: []
      }),

    The metadata, which is like an API description for the component, says that the component requires a name property, yet the actual code parses a user property. Because input parameters aren't validated at runtime, you won't catch these types of bugs by using the IDE debugger. Therefore, always remember to validate your dialog as part of your testing.

    The fix for this bug is to change the property name in the metadata, and then reload the component package.


more informationWant to Learn More?

To learn more about building and deploying custom components, see Backend Integration in Using Oracle Digital Assistant.