The Mobile & Digital Assistant Blog covers the latest in mobile and conversational AI development and engagement

TechExchange Quick-Tip: Accessing Remote Rest Services from Custom Components Using The Node.js HTTPS module

Frank Nimphius
Master Principal Product Manager

article by Frank Nimphius, March 2020


You use custom components in Oracle Digital Assistant to access REST services for querying or updating data. Because custom components are developed in Node.js, you use Node modules to handle the REST service access. In this article I explain how you use the Node https module to query data and how to write data back to an Oracle Digital Assistant skill. 

Note: If you are new to custom components in Oracle Digital Assistant, I do provide links to tutorials and article at the end of this blog article. 

Node.js: Basics about accessing REST services

Becase of its simplicity, the most popular Node module for accessing REST service is "request". The request module however is flagged as deprecated and is no longer actively developed. For this reason, you should use the https Node module. The benefit of the https module is that it is part of the Node.js core package, which means that you don't need to install any additional Node module, and that it is well documented. 

The https module supports all HTTP methods and thus is very suitable for use with REST. The documentation for the https.get method call can be found at https://nodejs.org/dist/latest-v13.x/docs/api/https.html#https_https_get_options_callback .

The most important hint to give is highlighted in the image below. You can click the http.get() link to get access to the HTTP documentation, which provides you with a lot more code examples for how to use http(s).get(), http(s)post() calls and more.

Node.js HTTP doc (to see samples you can use with HTTPS)https://nodejs.org/dist/latest-v13.x/docs/api/http.html#http_http_get_options_callback

But keep in mind, that Oracle Digital Assistant requires you to access your REST services through https for security reasons. 

A very basic setup for issuing a https GET request from a custom component in Oracle Digital Assistant is shown below. The https object takes a minimum of 1 argument, which is the REST URL. Other arguments are request options and callback functions. For this article I am keeping it simple, so please refer to the https documentation for code samples using the options and callback arguments.

The important thing to notice for the  HTTP GET request is that it has two events defined on('data', ...) and on('end', ...). The data event is called when a REST service returns its response data in chunks. You use this event to compile or aggregate the response and save it in a variable for later use. The end event is called when the REST request ends, which means that this is the even you use to deal with REST service response data and returning data to Oracle Digital Assistant. 

const https = require('https');
https.get(<url>, (res) => {
   res.on('data', (d) => { //for services that return result in chunks, aggregate content });
   res.on('end', (d) => { //return data to skill or display data });
}).on('error', (e) => { //report error in calling REST });


Sample REST service used in this article

For this article, I chose a public service that returns dummy employee data. The service doesn't require any subscription, which makes it a good candidate for this little how-to article. 

Sample Rest Service: https://dummy.restapiexample.com/api/v1/employees

To better visualize the JSON structure of the returned data, you can use any JSON formatter that you can find on the Internet. For this article, and the screen show shown below, I used https://jsonformatter.curiousconcept.com/

What you can see in above screenshot is that the JSOn response contains a status attribute as well as a data attribute. The data attribute holds an array of employee objects and is the object to return to the skill. 

Custom Component

The custom component source code can be downloaded at the end of this blog article. In the following I am briefly calling out code lines of interest. 

The image below shows the custom component metadata, which becomes the component interface signature after the custom component is registered with a skill in Oracle Digital Assistant. I defined a parameter variable that will hold the name of the dialog flow variable that should get the data array at the end of the REST query. 

In this example, the REST Url is provided as a static string in the source code. I don't recommend this for custom components you want to use in production. Here the URL should be passed as an input parameter so it can be changed for production environments and development environments. Especially when issuing POST requests that perform data updates or creation, distinguishing between a production and development environment becomes important. 

Notice line 17, which actually provides a handle to the https module. 

If the status of the GET request is not 200, then the component transitions to an error state that needs to be defined in the dialog flow. For this, the metadata section of the custom component has an "error" and a "success" action defiled. This way the skill developer knows about the transitions to setup for the component. Note that some REST URLS return HTTP 201 for data creation and update (POST, PUT). If this is what the REST services does that you use in your custom component, then ensure you don't handle 201 as an error. 

As mentioned before, the https module allows you to listen for the "data" event and the "end" event. The data event is used to fetch data from the RERST service call. The "end" event then is used to parse the collected data. In line 37, the REST JSON string response is parsed into a JSON object. 

If the status attribute in the JSON response of the dummy REST service used for this article has a value of "success", then, as shown in the image below, the custom component can return the data array to the skill where it is saved in a dialog flow variable. Remember that the custom component has an input parameter "variable" defined that holds the name of the variable to update with the queried data. The transition triggered by the component is to the "success" action transition.

When registering a custom component services with a skill, you can enable logging. When logging is enabled then all log messages are shown in the Diagnostics panel of the custom component service. The Diagnostics panel shows printed logs at runtime as well as a crash report in case your custom component service cannot installed. Usually the crash report is created because of missing Node dependencies (node modules that are not uploaded with the custom component service) or syntax problems in your component code that makes a component invalid and un-deployable. 


Dialog Flow

The custom component writes an array object to a dialog flow variable. This variable is called result in the sample dialog flow. Notice in the image below how the possible transitions triggered by the custom component are mapped to dialog flow states in the skill (lines 21 - 23). 

In the sample skill that you can download from a link at the end of this article, I use a System.CommonResponse component to display queried employee data in a card layout. Notice how, in line 37, then Common Response component references the result variable in its iteratorVariable property. This prints a card for each employee. Also notice line 36 in which Apache FreeMarker is used to check wether the employee profile contains an image URL or not. If no URL is found then a dummy image is used. For this article, no images URLs are provided through the REST call, so that all employees will have the dummy image shown instead. 

Notice the rangeSize and rangeStart properties in line 38 and 39. Because messengers restrict the number of cards that can be shown at a time, you may need to implement pagination for the objects in the result array. 

The image below shows the embedded conversation tester in Oracle Digital Assistant skills.  For each employee, you see a card created with the name, the employee ID and employee age on it. Clicking the Select button will then, in a next dialog flow step, print the selected employee name. 


Sample skill (ODA version 20.x and later). Skill contains the custom component. 

Custom component source code (JavaScript file)

Related Content

Learning custom component development: Tutorial

Debugging locally deployed custom components

Custom Component SDK overview (PDF)

TechExchange: Integrating Oracle Digital Assistant with Oracle Rest Data Service (ORDS)

TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube





Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.