article by Frank Nimphius, June 2019

 

A common requirement among Oracle Digital Assistant customers is to export conversation logs using a non-GUI approach.

Oracle Bots Insights, the bot analytic feature in Oracle Digital Assistant, provides a REST API for you to export conversation information based on optional custom filter criteria. The REST API is documented in REST API for Oracle Digital Assistant, which is a part of the Oracle product documentation for Oracle Digital Assistant.

The product documentation  explains the REST API calls, as well as how to set up the export task, for using CURL on a command line. 

This article explains the steps to export conversation logs for a skill in Oracle Digital Assistant using Google Chrome Postman as a client. With this article, which closely follows the product documentation, you get a second option for exporting and accessing conversation data. 

To export conversation logs from Google Chrome Postman, you follow FOUR steps

  1. Get the Client ID and the Client Secret from your Identity Cloud Instance
  2. Authenticate to Oracle Identity Cloud to obtain an OAUTH2 access token
  3. Create an export task for the conversation log to obtain
  4. Download a character delimited document with the log content

Pre-Requisites

Conversation logs are exported for skills, and not Oracle Digital Assistant as a whole. To be able to export conversation logs, you need to first enable Bots Insights for the skill.

There are two options you have available for this

1. Open the Bots Insights panel for a skill and select the Click here to enable it link

2. Or, use the Skills settings and switch the Enable Insights toggle. 

 

Authenticate to Oracle Identity Cloud to obtain an OAUTH2 access token

To use a REST client like Postman or curl for creating export tasks and for downloading export data, you first need to obtain an OAUTH2 access token. For this however you need to pass a request to Oracle Identity Cloud Cloud Service using a specific client ID and client secret in a basic authentication authorization header. 

To obtain the authentication ID and passcode, you need to have access to Oracle Identity Cloud. Oracle Identity Cloud access is provided to you when you subscribe to the Oracle Cloud. You cannot access Oracle Identity Cloud from the Oracle Digital Assistant dashboard. So what you need to do is

1. Access the Oracle Cloud My Service dashboard. The link to this dashboard is contained in the first mail you receive after subscribing to Oracle Cloud. The click the Users link.

2.In the User Management panel, click the Identity Console button

3.Click the hamburger icon to open the side menu. Select Applications. You can then click the hamburger icon again to close the side menu

3.In the Applications menu, set the filter option to BOTSExternalAPIOAuthClient. Find and select the entry for your Oracle Digital Assistant Instance ("ODATRaining02" in the sample of this article)

4. Expand the General Information category. Here you find the Client ID and the Client Secret to pass as a base64 encoded string with the initial authentication request.

Note that Postman is able to do the base64 encoding, as well as the string concatenation for you.

If you prefer using curl, as the documentation does, then you need to create a base64 encoded string of Client_ID_value:ClientSecret_value (note the colon between the two values)

5. The Client Configuration category shows the Resource entry, from which you need to copy the authorization scope. This is needed in Postman when requesting the access token.

Authenticate to Oracle Identity Cloud to get an OAUTH2 access token

An access token is required to request a data export and to download the exported data.

For this you …

1.  Create a HTTP POST request to https://<your identity cloud instance host>/oauth2/v1/token. You can copy the Oracle Identity Cloud host name from the identity console you used to obtain the client id and secret.

 

2. As shown in the image above, in Postman, select the Authorization tab, and choose Basic Auth as the type.

Add the Identity Cloud client ID you accessed in the previous section as the username and the Identity Cloud client secret as the password.

Then click the Preview Request button, which will then create a temporary authorization header parameter as the base 64 encoded string built from the client ID and the client secret.

3. Switch to the Headers tab and create two header entries: Content-Type and Accept-Charset. Set the Content-Type to application/x-www-form-urlencoded and the Accept-Charset to utf-8

4. Next, select the Body tab and create two form parameters: grant_type and scope. 

The grant_type needs to be set to client_credentials, the scope to the Resource string shown in the Oracle Identity Cloud Client Configuration .

The screenshot below is a crop of the image shown in step 5 of the "Authenticate to Oracle Identity Cloud to obtain an OAUTH2 access token" paragraph in this article. 

5. In Postman, press the Send button to send the POST request to Oracle Identity Cloud. 

6. Copy the access token (only the blue token text without the quotes) to the clipboard. Note that the token type is "Bearer" and the expiry time to be within 60 minutes. 

Create an export task 

With the access token, you can now request an export. The export can be configured for a specific date range and, if needed, for a specific intent. 

1. Create a new POST request to https://<your oracle digital assistant host>/api/v1/bots/<skill ID>/insightExports.

Select the Headers tab in Postman and create two headers: Authorization and Content-Type.

The Authorization header needs to be set to Bearer <your_access_token>. The content type needs to be set to application/json.

Note: The ID of your bot can be copied from the Oracle Digital Assistant skill editing environment. Open the skill for which you want to request data exports and copy the ID from the URL (the string after "botId."). The ID of a skill doesn't change so that you only need to do this once. 

Important: The ID of a skill changes when you clone a bot, or when you create a new version of it. The cloned skill and the new version have a different skill ID than the original skill. 

2. Switch to the Body tab in Postman to define the configuration for the export request. The export configuration parameters are explained in the REST API product documentation shown in he image below.

The image below configured the export with a date range of 2 days. 

 

Here's the JSON used in the above image for copy & paste as a starter to your own exports

{
"beginDate": "2019-06-24",
    "endDate": "2019-06-25",
    "createdByName": "Frank Nimphius",
     "name": "Daily_Pizza_Report"
}
 

3. As a result of export request, you get a resourceId, which is a unique identifier for the export job you use to download the exported data. 

 

Download a character delimited export data

Finally, you can download the conversation data as a character delimited file.

1. In Postman, create a GET request to https://<your oracle digital assistant instance host url>/api/v1/bots/53A49B47-90BA-4167-8883-4691921B72FB/insightExports/<the resource of of the export job>/data.

Then, in Postman, switch to the Authorization tab and create a header for "Authorization". Paste the bearer token and prefix it with "Bearer " (without quotes). Sending the request displays the data in Postman. You can use the Postman's download button to get a CSV file. 

2. Send the request to download the exported data

A Few Hints For When You Test The REST APIs

  1. Note that it takes a few seconds before a conversation shows in an export task. So when you test the Oracle Digital Assistant REST APIs, make sure that you give it a few seconds between the user (the test person) completing the skill conversation and the request for an export task.
  2. If you filter the conversation data to a specific intent, then only conversations associated with the intent, which mostly is the NLP request. will be contained in the exported data.
  3. Also, export tasks are snapshots. They don't contain conversation data entered by users after the export was requested. 

Summary

This article explained how to use Google Chrome Postman to obtain an access token from Oracle Identity Cloud to request a conversation data export and to download the exported data.

Using many images, this article followed instructions of the Oracle Digital Assistant REST API Documentation, which explains the same for use with curl on the command line.

Using Bots Insights you can filter data exports to the date range of interest. Using the REST API is a non-GUI alternative to the Bots Insights dashboard accessible from a skill.

The image below shows all available REST API at a glance. An API not explicitly covered in this article, which however makes sense to have in a scripted automated export, is "Get Export Task Status".

Dependent on the size of an export, the processing of a task may take a few seconds.  You can call the "Get Export Task Status" API to check whether the request has completed or not. If it has completed, you can request a download of the data. 

 

Note that export tasks you perform using the REST API can also be accessed from the skill graphical user Interface.

 

Related Content

TechExchange: Oracle Digital Assistant Primer

 

Author