Integrate Oracle Digital Assistant into a Website Built in Oracle Content Management

Introduction

Organizations are often looking to create content-sharing websites (such as marketing sites, sales portals, and partner hubs) for distributing content to internal or external audiences. Oracle Content Management offers tools with powerful features to build such content-sharing websites.

Digital assistants and chatbots enable sales and marketing teams to fast-track their digital business expansion and enhance their customer experience.

Oracle Digital Assistant is a platform that allows you to create and deploy digital assistants, which are AI-driven interfaces that help users accomplish a variety of tasks in natural language conversations. But what happens when you need a content management system (CMS) to serve all of your content? Fortunately, Oracle Content Management, with its rich headless CMS capabilities, has a graceful solution for all your content administration and governance needs.

In this tutorial, we’ll first build a chatbot in Oracle Digital Assistant by leveraging Oracle Content Management as a headless CMS as well as its software development kit (SDK) for content delivery in JavaScript. Next, we’ll use Oracle Content Management’s Site Builder to create and edit a sales enablement website and add the chatbot using an Oracle Content Management custom component.

The tutorial consists of four steps:

  1. Set up your Café Supremo sales enablement website
  2. Build the Oracle Digital Assistant skill
  3. Set up the Oracle Content Management custom component
  4. Add the custom component to the website

Prerequisites

Before proceeding with this tutorial, we recommend that you read the following information first:

To follow this tutorial, you’ll need:

What We’re Building

Café Supremo is a fictional coffeehouse chain, which has store locations worldwide. The Café Supremo sales enablement website is created with Oracle Content Management.

The Café Supremo sales enablement website allows sales representatives of the Café Supremo company across the globe to get all the information they need about sales. To learn what a sales enablement website is and see an introduction to the Café Supremo sales enablement website, see Learn about creating a sales enablement website.

This is an enhanced version of the Café Supremo sales enablement site, which features a chatbot developed using Oracle Digital Assistant (ODA) that pulls content delivered from an Oracle Content Management channel.

This is what the sales enablement site will look like at the end of this tutorial:

This image shows the sales enablement site landing page with the chatbot window open and an ongoing conversation.

Step 1: Set Up Your Café Supremo Sales Enablement Website

In this section, you’ll set up the Café Supremo sales enablement website using Oracle Content Management.

To get started, you’ll need to download the zip file containing the template and sample code for the Café Supremo sales enablement website from the Oracle Content Management downloads page. Once you obtain a copy of the template, upload it to Oracle Content Management, where you’ll use it to create the sales enablement website.

The zip file contains a readme file, license files, and the template zip file.

Note: The images used in the sample template and the Café Supremo sales enablement website are Shutterstock images. If you reuse these images, then they must be licensed through Shutterstock. You can also replace these images with your own images.

To set up the Café Supremo reference sales enablement website:

  1. Sign in to Oracle Content Management as an administrator. If you don’t see an ADMINISTRATION section in the left navigation menu in the Oracle Content Management web interface, you don’t have administrator privileges. In that case, contact your service administrator.

  2. In the left navigation menu, click Developer, and then View All Templates.

This image shows the Developer page in the Oracle Content Management web interface, with links to components, template, themes, and embeddable UI.

  1. On the Templates page, click Create, and choose Import a template package.

  2. In the Pick a File dialog, navigate to the folder where you want to upload the file or create a new folder, and click Upload.

  3. Locate and select the CafeSupremoSalesEnablement.zip template package, and click Open. Wait for the file to be uploaded. Once the file is uploaded, it will be available for selection.

  4. Select the CafeSupremoSalesEnablement.zip checkbox and click OK. The CafeSupremoSalesEnablement template is now included in the list of templates on the Templates page.

  5. Click Content under ADMINISTRATION in the left navigation menu.

  6. Now create a repository, which is a storage location to manage all your digital assets that you use in your website in one place:

  1. Choose Repositories from the dropdown list and click Create in the upper-right corner.

  2. In the Name field, enter a meaningful repository name for your website (for example, ‘CafeSupremoSalesEnablement Repository’).

  3. In the Default Language field, ensure that English (United States) (en-US) is selected.

  4. Click Save. The newly created repository is now included in the list of repositories on the Content page.

This image shows the Create Asset Repository page in the Oracle Content Management web interface.

  1. Click Sites in the left navigation menu.

  2. In the Sites page, click Create in the upper right corner.

This image shows the Sites landing page in the Oracle Content Management web interface, with a Create button in the top-right corner.

  1. In the Create Site dialog, choose the CafeSupremoSalesEnablement template.

  2. Complete the following fields:

This image shows the Create Site page in the Oracle Content Management web interface.

  1. Click Next and add details for your site:

This image shows the site details page in the Oracle Content Management web interface.

  1. Click Create.

The sales enablement website has been created and is now listed on the Sites page.

Step 2: Build the Oracle Digital Assistant Skill

To consume our Oracle Content Management content in an ODA chatbot application, we can use the Oracle Content Management ODA chatbot sample, which is available in an open-source repository on GitHub.

Note: Remember that using the ODA chatbot sample is optional, and we use it in this tutorial to get you started quickly. You can also build your own chatbot application.

To build the chatbot skill in ODA:

  1. Clone the sample repository
  2. Import the ODA skill to your instance
  3. Set up and configure the custom component service
  4. Work with the Content SDK
  5. Use the Content SDK to fetch content
  6. Package and deploy the custom component service

Clone the Sample Repository

The Oracle Content Management ODA chatbot sample is available in an open-source repository on GitHub. You’ll first need to clone the sample from GitHub to your local computer and change your directory into the repository root.


    git clone https://github.com/oracle/oce-integration-samples.git
    cd oce-integration-samples/oce-oda-chatbot-sample

Now that you have your code base, let’s have a closer look at the folders that you’ll be using in this tutorial:

Note: The sales-enablement-custom-component and WebApp folders are part of headless chatbot sample. You can learn more about this headless chatbot sample here.

Import the ODA Skill to Your Instance

The ODAChatbot folder in the code base is the ODA skill used in this tutorial. Follow these steps to create and train your skill on your ODA instance:

  1. In your Oracle Digital Assistant instance, open the navigation menu on the left, then click Development, and then Skills.

This image shows the Oracle Digital Assistance instance with the left navigation menu open and the Skills option highlighted.

  1. Search for the ODA Chatbot skill.

Note: If your instance doesn’t have this skill, then select the contents of the ODAChatbot folder and compress them to a single zip file. On the Skills page in your ODA instance, click Import Skill and import the zip file that you just created. Directly compressing the ODAChatbot folder will result in an error upon import.

  1. On the ODA Chatbot skill card, click the options icon and then Clone.

This image shows the Oracle Digital Assistance instance with the left navigation menu open.

  1. Give the cloned skill a unique display name; for example, add your initials at the beginning, such as ‘AB - ODA Chatbot’. Leave all other values unchanged. Select Open cloned skill afterwards and then click Clone.

Note: The name must begin with a letter and may contain only letters, numbers, periods, and underscores. It can’t exceed 100 characters.

This image shows the Oracle Digital Assistance instance with the left navigation menu open.

  1. Click Train, make sure that Trainer Ht is selected, and then click Submit to train the skill.

Note: You use Ht training in this tutorial, which is quick but superficial. For production work, you should use Tm training, which results in better intent resolution.

This image shows the Oracle Digital Assistance instance with the left navigation menu open.

ODA Chatbot Skill

Skills are individual chatbots that are designed to interact with users and fulfill specific types of tasks, such as ordering food, making reservations, and changing contact information. The ODAChatbot skill helps a user find appropriate sales enablement announcements and stories through a combination of text messages and simple UI elements such as selection lists.

Before you dive into digital assistant and skill development, here are some concepts you’ll want to become familiar with:

To learn more about Oracle Digital Assistant and skills, check out the product documentation.

Set Up and Configure the Custom Component Service

The site-integration/oda-custom-component folder in the code base is the ODA custom component used in this tutorial. First, we need to download dependencies for this ODA custom component. Run the following command from the root/site-integration/oda-custom-component directory:

npm install

Next, we need to configure a few pieces of information so that our Oracle Content Management Content SDK (and any other requests) can target the correct instance URL and API version with the correct channel token.

These values are used in components/server-config-utils.js to instantiate a new delivery client.

Open the server-config-utils.js file in a text editor. You’ll see the following:


    contentServer: "https://instance-name.cec.ocp.oraclecloud.com",
    contentVersion: "v1.1",
    channelToken: "4b7b22ad5f5245f28579641d5489a98f",

Change each key-value pair to reflect your instance URL, the API version you want to target, and the channel token associated with your publishing channel. The channel for this tutorial is ODAChatbotChannel.

Work with the Oracle Content Management Content SDK

Oracle Content Management offers an SDK to help discover and use content in your applications. The SDK is published as an NPM module, and the project is hosted on GitHub.

Learn more about the SDK here.

The SDK has been registered as a runtime dependency of this project in the package.json files.

Use the Content SDK to Fetch Content

We can now leverage the Content SDK to fetch content for the chatbot skill through the ODA custom component.

The components/services.js folder contains the code for getting data from Oracle Content Management using the Content SDK.

The components/server-config-utils.js file imports the Content SDK and then creates a delivery client using the configuration specified in it.

The following command imports the SDK:

createDeliveryClient = require('@oracle/content-management-sdk');

The following command creates the delivery client:

deliveryClient = createDeliveryClient(serverconfig);

The components/services.js file contains all the code to get the content items for the chatbot. There’s one main function to fetch all the content for the chatbot.

The following functions are called to retrieve all of the data for a particular taxonomy category from the CafeSupremoSalesEnablement Repository:

function getStoryData(client, categoryName) {
     if (categoryName === 'Announcements') {
       return fetchItemsForAnnouncements(client, false)
         .then((topLevelItem) => {
           const { totalResults } = topLevelItem;
           const promises = [];
           // for each item, retrieve the result object and add it to the promise
           topLevelItem.items.forEach((item) => {
             promises.push(
               retrieveAnnouncementsObject(client, item.id)
                 .then((resultobject) => ({ ...resultobject })),
             );
           });
           // execute all the promises before returning the data
           return Promise.all(promises)
             .then((arrayOfItems) => ({
               totalResults,
               items: arrayOfItems.flat(),
             }));
         });
     }
     return fetchItemsForCategoryName(client, categoryName, false)
       .then((topLevelItem) => {
         const { totalResults } = topLevelItem;
         const promises = [];
         // for each item, retrieve the result object and add it to the promise
         topLevelItem.items.forEach((item) => {
           promises.push(
             retrieveResultObject(client, item.id)
               .then((resultobject) => ({ ...resultobject })),
           );
         });
         // execute all the promises before returning the data
         return Promise.all(promises)
           .then((arrayOfItems) => ({
             totalResults,
             items: arrayOfItems.flat(),
           }));
       });
    }

The getStoryData function makes two different sets of calls depending on whether the request is made for the announcements or a story category.

Announcements Data

It requires one data call to get all the content items for the announcements.

The getStoryData function calls fetchItemsForAnnouncements, which gets all the content items of type ‘SE2-Announcements’. Next, the retrieveAnnouncementsObject function is called and the title and summary fields of the result object are populated with the data from fetchItemsForAnnouncements.

function fetchItemsForAnnouncements(client, limit) {
     return client.getItems({
       q: '(type eq "SE2-Announcement")',
       fields: 'all',
       expand: 'all',
       limit: limit ? 4 : 100,
       totalResults: true,
     });
    }

Story Data

It requires several data calls to get all the content items for the Stories.

  1. First, we get all the content items for the user requested category.

  2. For each content item we get, we make a call to retrieve the media URL.

The getStoryData function calls fetchItemsForCategoryName, which gets all the content items of type ‘SE2-Story’ and taxonomy category name as specified by the user.

function fetchItemsForCategoryName(client, categoryName, limit) {
     return client.getItems({
       q: `(taxonomies.categories.name eq "${categoryName}" and type eq "SE2-Story")`,
       fields: 'all',
       expand: 'all',
       limit: limit ? 4 : 100,
       totalResults: true,
     });
    }

The content item fetched by fetchItemsForCategoryName has a media id field. The retrieveMediaURL function uses this media id to fetch the media URL.

function retrieveMediaURL(client, identifier) {
     return client.getItem({
       id: identifier,
       fields: 'all',
       expand: 'all',
     }).then((asset) => {
       let url = null;
       if (asset.fields && asset.fields.renditions && asset.fields.fileType !== 'mp4') {
         const object = asset.fields.renditions.filter((item) => item.name === 'Small')[0];
         const format = object.formats.filter((item) => item.format === 'jpg')[0];
         const self = format.links.filter((item) => item.rel === 'self')[0];
         url = self.href;
       } else {
         url = asset.fields.native.links[0].href;
       }
       return [url, asset.fields.fileType];
     });
    }

Package and Deploy the Custom Component Service

You can deploy custom components to either an embedded container for a skill, a remote Node server, or Oracle Mobile Hub. In this tutorial, you’ll deploy your custom component service to an embedded container. To accomplish this, you first need to package the custom component service into a deployable file:

  1. Save your work in your JavaScript IDE.

  2. Open a terminal window and navigate into the site-integration/oda-custom-component folder.

  3. In the oda-custom-component folder, enter the following npm command

    bots-node-sdk pack

    Because of the prepack script in the package.json file, the command first executes the prepack command to verify the package. The command then packages the Node project and its dependencies into a deployable tarball called oda-custom-component-1.0.0.tgz.

    Your tarball must include all dependencies except for devDependencies.

  4. In your chatbot skill on ODA instance, click the Components icon in the left bar to open the component service page. Click + Service to create a new service.

This image shows an empty services page for a skill.

  1. In the Create Service dialog, do the following:

    1. In the Name field, enter SalesEnablementCustomComponent.

    2. In the Description field, you can add an optional description.

    3. Make sure that the Embedded Container option is selected.

    4. Drag and drop or upload the oda-custom-component-1.0.0.tgz file into the Package File field.

    5. Click Create.

This image shows the Create Service dialog.

  1. Wait for the Status field to show Ready, which may take a few seconds.

  2. With the custom component service deployed to the skill’s embedded container, you are ready to test the component.

To learn more about Oracle Digital Assistant and custom components, check out the training documentation.

Create an Oracle Digital Assistant Web Channel

You’ll create an Oracle Digital Assistant user channel that enables an Oracle Web client to access your skill. To ensure that only your web clients can use this channel, you’ll configure it to require client authentication.

  1. In your Oracle Digital Assistant instance, open the navigation menu on the left, then click Development, and then Channels.

This image shows the Oracle Digital Assistance instance with the left navigation menu open and the Channels option highlighted.

  1. On the Channels page, click + Channel to add a channel.

  2. On the Create Channels page, enter this information as shown in the screenshot below:

This image shows the Oracle Digital Assistance instance with the left navigation menu open and the Channels option highlighted.

  1. Click Create.

  2. In the Route To dropdown list, select the skill that you want to use for this tutorial.

This image shows the Channels page with the Route To dropdown list open.

  1. Switch the Channel Enabled option to On.

  2. Note the channel ID that’s shown for this channel. Later in this tutorial, you’ll use this value in your web app.

This image shows the Channels page with the routing information for the chatbot.

  1. Also note the Oracle Digital Assistant host and domain (which is referenced as the fully-qualified domain name) from the instance URL that appears in your web browser’s address field, for example oda-xxxx.data.digitalassistant.oci.oraclecloud.com. You’ll use this value later in the tutorial.

Your instance is now set up for you to connect a chatbot on your website to the skill.

Step 3: Set Up the Oracle Content Management Custom Component

Now you need to import the SE2-ODA-Chatbot custom component into your Oracle Content Management instance.

Setting up the Oracle Content Management custom component is a three-step process:

  1. Add Oracle Digital Assistant Web SDK
  2. Import the SE2-ODA-Chatbot custom component
  3. Publish the SE2-ODA-Chatbot custom component

Add Oracle Digital Assistant Web SDK

We need to add ODA web-sdk.js file in the SE2-ODA-Chatbot custom component. The SDK connects to the Oracle Chat Server, which stands between Oracle Digital Assistant and the skill (or digital assistant). The chat server then passes messages to the skill for processing and delivers the skill’s response to the client.

  1. Download the latest version of Oracle Web SDK and unzip into a folder of your choice. You can also go to the download page for this SDK from your Digital Assistant instance by opening the side menu and then clicking Downloads.

  2. Copy native-client-sdk-js/web-sdk.js file from your Oracle Web SDK folder and put it in the SE2-ODA-Chatbot/assets/chatbot folder.

This image shows the Web-sdk file in the SE2-ODA-Chatbot/assets/chatbot folder.

Import the SE2-ODA-Chatbot Custom Component

To import the SE2-ODA-Chatbot custom component:

  1. Navigate to site-integration folder and compress the SE2-ODA-Chatbot folder to a zip file.

  2. Log in to Oracle Content Management web interface as an administrator.

  3. Click Developer in the left navigation menu and then click View All Components. If you don’t see the Developer option, you don’t have the required user roles.

  4. On the Components page, click Create and choose Import Component.

This image shows the Components page with the Create dropdown menu open. At the bottom of that dropdown menu is the Import Component option.

  1. Go to the folder in your Oracle Content Management instance where you want to upload the component or create a new folder. Click Upload , then find the SE2-ODA-Chatbot.zip file and click Open.

  2. Select the SE2-ODA-Chatbot.zip file and click OK.

This image shows the Pick a File page with the SE2-ODA-Chatbot.zip file selected and the OK enabled.

If the component or layout name or ID already exists, you’re prompted to resolve the conflicts. You may need to create a new component or you can overwrite the existing component with the imported version.

After the SE2-ODA-Chatbot component has been uploaded successfully, it’s listed on the Components page.

Publish the SE2-ODA-Chatbot Custom Component

Now you need to publish the SE2-ODA-Chatbot component that you imported:

  1. On the Components page, select the SE2-ODA-Chatbot component and click Publish from the actions bar or right-click menu.

This image shows the Components page with the SE2-ODA-Chatbot component selected and the Publish option enabled.

  1. In the Publish Component dialog, select Confirm to proceed and click OK.

This image shows the Publish Component page with the ‘Confirm to proceed’ checkbox selected and the OK button enabled.

Once the SE2-ODA-Chatbot component has been published, a notification is displayed at the top of the page to confirm this.

Step 4: Add the Custom Component to the Website

As the final step, we’ll add the SE2-ODA-Chatbot custom component to the sales enablement site by dragging and dropping it in Site Builder.

Adding our chatbot to the sales enablement site is a two-step process:

  1. Edit the website
  2. Publish the website

Edit the Website

The first step is to add a chatbot to the sales enablement site using the SE2-ODA-Chatbot custom component:

  1. Log in to the Oracle Content Management web interface and open the Sites page.

  2. Select your newly created website and choose Open from the actions bar or right-click menu to open it in Site Builder.

  3. Put the site into edit mode by toggling the View/Edit switch.

  4. Enter a name for the update and click OK.

  5. In the left sidebar, click Components and then Custom to show the list of custom components.

This image shows the list of components in Site Builder with the Custom option selected.

  1. Now let’s add an ODA chatbot widget to the home page using the SE2-ODA-Chatbot custom component. Drag and drop the SE2-ODA-Chatbot component anywhere on the page. Click the title of the SE2-ODA-Chatbot component to make sure its parent is what you wanted. This is a useful way to see where any component resides within the structure of the web page.

This image shows the custom component on a web page in Site Builder.

Complete the custom settings in the General tab:

Repeat the steps above to add the chatbot on any page of your website.

Publish the Website

Now that you’ve successfully added the chatbot to your website, you can publish it to make it available online for your users to see.

  1. Once everything looks good, commit your changes to the base website by clicking Commit in the upper-right corner of Site Builder.

This image shows the step to commit your changes in Site Builder.

  1. In the Commit Update dialog, click Commit.

This image shows the commit dialog in Site Builder.

  1. Once the changes have been committed, the website is ready to be published. Close Site Builder.

  2. Click Sites in the left navigation menu in the Oracle Content Management web interface and select the website.

  3. Choose Publish from the actions bar or right-click menu.

This image shows the step to publish your site in Site Builder.

  1. Once the website has been published, a notification is displayed at the top of the page to confirm this.

  2. On the Sites page, select the website again, and then choose Bring Online from the actions bar or right-click menu. In the Bring Online dialog, choose Confirm to proceed and click Bring Online.

This image shows the step to bring your site online.

This image shows the Bring Online dialog in Site Builder.

That’s it. Your website is now online and others can view it.

To view your public website, select View from the actions bar or right-click menu, or open the URL in your web brower.

How to Use the Chatbot

Here are some ways that you can use the chatbot in your site: