Oracle APEX - ODA integration #JoelKallmanDay

Recently, I had the exciting opportunity to work on the integration of Oracle Digital Assistance (ODA) with Oracle Application Express (APEX). This integration involves embedding an ODA chatbot within the APEX application, enabling users to interact with the chatbot. In this blog post, I'll delve into the details of integration step by step.

Oracle Digital Assistance (ODA)

Oracle Digital Assistant (ODA) is a sophisticated technology created by Oracle that simplifies and improves the way people interact with computer systems and applications. Think of it as a smart, virtual assistant for your software.

Imagine having a helpful digital friend that can understand and respond to your questions or commands, just like talking to a human. ODA can understand natural language, like English, so you can ask it things like, "What are my upcoming appointments?" or "Can you help me order a product?" It can then fetch the relevant information or perform tasks for you within your software.

ODA can be used in various applications, from customer service chatbots on websites to voice-activated systems in cars or homes. It makes it easier for people to access information and perform tasks without having to navigate complex menus or interfaces.

In essence, Oracle Digital Assistant makes technology more user-friendly by allowing you to communicate with your software in a conversational and intuitive way.

Integration

Oracle Digital Assistance utilises the Native Client SDK for Web, also referred to as the ODA Web SDK, to load the chat window onto your website.

This chat window establishes communication with the published skill directed to the ODA channel. For further information on the Web SDK, please consult Oracle documentation.

ODA can be integrated into multiple platforms, including:

• Facebook Messenger.
• Slack.
• Microsoft Teams.
• Cortana.
• Text-Only Channels: Twilio/SMS.
• Oracle Web.
• Oracle Android.
• Oracle iOS.
• Webhooks.

In this blog post, we will explore Oracle Web integration for web applications and websites.

Step 1 - Creating a Channel

In ODA, channels play a crucial role in making your digital assistants and standalone skills accessible to users. These channels facilitate the flow of conversation between users on different messaging platforms and the digital assistant, along with its various skills. Additionally, there are channels dedicated to user agent escalation and testing.

To get started, we must create one. To do this, follow these steps:

1. Open the ODA menu.
2. Navigate to 'Channels.'
3. Click the 'Add Channel' button.
4. Fill out the form and create the channel."

After creating the channel, the next steps involve routing messages to your published skill and enabling the channel to be accessed by APEX. You will find the channelID on this page, which you will need later when configuring the settings.js file.

Step 2 - Getting the right library

To integrate ODA into APEX, you need to include the JavaScript library from the previously mentioned SDK.

Begin by downloading and extracting the Native Client SDK from here. Inside, you'll find a file named web-sdk.js, which we will incorporate in the next step.

Step 3 - Configuration file

To ensure your chat widget functions correctly, you'll need to set it up by adding a few additional lines of JavaScript. This configuration will be placed in a separate file for clarity, named settings.js.

Alternatively, you can use the following example code, which includes some basic configurations for the chat widget:

'use strict';
/**
 * Initializes the SDK and sets a global field with passed name for it the can
 * be referred later
 *
 * @param {string} name Name by which the chat widget should be referred
 */
function initSdk(name) {
    // Retry initialization later if WebSDK is not available yet
    if (!document || !WebSDK) {
        setTimeout(function () {
            initSdk(name);
        }, 20000);
        return;
    }

    if (!name) {
        name = 'Bots'; // Set default reference name to 'Bots'
    }
    var Bots;

    setTimeout(function () {
        var chatWidgetSettings = {
            // ODA URI, pass the hostname. Do not include the protocol (https://).
            URI: 'your_instance.data.digitalassistant.oci.oraclecloud.com',
            // Channel ID, available in channel settings in ODA UI
            channelId: 'channel_id_releated_to_your_skill',
            showConnectionStatus: true,
        };

        Bots = new WebSDK(chatWidgetSettings);
        Bots.connect();

        // Uncomment and modify the following line to set an initial user message:
        // Bots.setUserInputMessage('Order pizza');

        // Create global object to refer Bots
        window[name] = Bots;
    }, 0);
}

For further details on the settings and styles, please refer to the official documentation available here.

Step 4 - Including ODA in your APEX page

To enable APEX to access your files (web-sdk.js and settings.js), it's essential to place them in an accessible location. The most straightforward and commonly used approach is to upload them as static files. However, you also have the flexibility to upload them to a CDN (Content Delivery Network) or a static location of your choice.

To upload static files in Oracle APEX, follow these steps:

• Navigate to the "Application Builder" in Oracle APEX.
• Select the application where you want to upload static files.
• Go to "Shared Components."
• Under "Files," choose "Static Application Files."
• Click the "Create" button to upload your static files.
• Follow the on-screen instructions to select and upload your files.

After making your files accessible online, you can include them at either the application or page level in Oracle APEX. Once included, you just need to initialise the assistance with a simple line of code:

initSdk('Bots')

Below is an example at a page level:

At this point, your ODA chatbot should now be accessible on the APEX page:

Conclusion

Integrating Oracle Digital Assistance (ODA) with Oracle Application Express (APEX) brings the power of chatbots to your applications, making it easier for users to interact with and get things done.

I hope this quick guide to ODA integration has been helpful, and I'm thrilled to share it in the announcement of #JoelKallmanDay!

Find out more about our APEX services