How can I begin development of an Analytics BUI Extension for External Data using External Objects?
Environment:
Agent Browser UI Extensibility Framework
External Objects (XO)
Issue:
How can I create a BUI virtual table report to serve up data residing outside of Oracle B2C Service by leveraging external objects?
Resolution:
This answer is a step-by-step guide clearing up frequently asked questions on implementing a report from external data leveraging the External Objects & Integration feature. If the external data has an OData or ORDS endpoint, then the virtual table will be available automatically without needing to create BUI extensions. You need to follow this guide in its entirety only for other REST based end points. This answer acts as an extension of the official documentation located here & here.
Step 1: Create the Integration from External Objects and Integrations page
- Login to BUI as an administrator
- From the Administration landing page, open External Objects and Integrations
- Click Add New to create the new integration
- Provide the configuration for connecting to the external endpoint. We have given the name as ‘Employee’
- Save the integration
Step 2: Create the Virtual Table Definition
Use a JSON file to define the table structure, and then upload the file using the Extension Manager. The following code will add a table called ‘Organization$Employee’ into the Data Dictionary.
Below is a sample table structure code for reference purpose only
{
"reportTablePackages": [{
"name": "Organization",
"tables": [{
"name": "Employee",
"label": "Employee",
"description": "EMPLOYEE TABLE",
"columns": [{
"name": "USER_FIRST_NAME",
"label": "FIRST NAME",
"description": "FIRST NAME",
"dataType": 3,
"canDisplay": true,
"canFilter": true,
"canEdit": false,
"isKey": true,
"isNullable": true
},
{
"name": "USER_LAST_NAME",
"label": "LAST NAME",
"description": "LAST NAME",
"dataType": 3,
"canDisplay": true,
"canFilter": true,
"canEdit": false,
"isKey": true,
"isNullable": true
},
{
"name": "USER_EMAIL",
"label": "EMAIL",
"description": "EMAIL",
"dataType": 3,
"canDisplay": true,
"canFilter": true,
"canEdit": false,
"isKey": true,
"isNullable": true
}]
}]
}]
}
In order to define the table parameters for the specific data, please reference the following table.
Table Parameters
| Parameter | Description |
|---|---|
| canDisplay | Whether the column is displayed |
| canEdit | Whether the column can be edited |
| canFilter | Whether the column can be added to a filter |
| dataType |
Column data types:
|
| description |
|
| isKey | Whether the column is a primary key |
| isNullable | Whether the column can contain null data |
| label |
|
| name |
|
Step 3: Register the user function to supply data for the table
For this step we will use the addTableDataRequestListener call back function to supply data to the report just created. Below is an example javascript code that creates and populates the report from external sources. The code is heavily commented for clarity. The below is for educational purpose only.
.then(function(IExtensionProvider)
{
IExtensionProvider.registerAnalyticsExtension(function(IAnalyticsContext)
{
IAnalyticsContext.addTableDataRequestListener('Organization$Employee', sampleDataSupplier);
});
});
return new ORACLE_SERVICE_CLOUD.ExtensionPromise(function (resolve, reject) {
ORACLE_SERVICE_CLOUD.extension_loader.load("Global Extension", "1").then(function (extensionProvider) {
extensionProvider.getGlobalContext().then(function (globalContext) {
globalContext.getExtensionContext('EmployeeReport').then(function (extensionContext) {
// We need to provide the name of the XO integration here
extensionContext.getConnections('Employee').then(function (connectionCollection) {
console.log(connectionCollection);
// Provide connection name
const connection = connectionCollection.get('Employee');
// 'accounts' is the relative url
connection.open('GET', 'accounts');
connection.send().then(function (response) {
var reportData = reportObject.createReportData();
// The following code to populate data is very specific to the endpoint we have used. You would need to write your own code depending on how the endpoint returns the data
response.forEach(function(user){
if(user.firstName!='string') {
addRow(reportObject, reportData, user.firstName, user.lastName, user.email);
}
});
resolve(reportData);
}).catch(function(){
var reportData = reportObject.createReportData();
resolve(reportData);
})
});
});
});
});
});
}
var reportRow = reportObject.createReportDataRow();
var col1 = reportObject.createReportDataCell();
var col2 = reportObject.createReportDataCell();
var col3 = reportObject.createReportDataCell();
col1.setData(firstName);
col2.setData(lastName);
col3.setData(email);
rowRecordInfo.setRecordType(3);
reportRow.getCells().push(col1);
reportRow.getCells().push(col2);
reportRow.getCells().push(col3);
reportRow.getRecordInfoList().push(rowRecordInfo);
reportData.getRows().push(reportRow);
}
Step 4: Create the Analytics extension
- From within BUI, navigate to the Extension Manager
- Create a new analytics BUI Extension
- Upload the extension source code. You would need to make the relevant code changes to process the response received from the endpoint before uploading
- Ensure that the name of the extensions is ‘EmployeeReport’ as that is the name defined in the init.js file.
- The configuration at this point should look like this:
- Give the Extension access to the integration by going to the Connections Permission tab
- Give the Extension the required profile permissions by going to the Profile Access tab
- Click on Publish to publish the extension
- Logout and log back into the Agent Desktop ( **Don't skip this step** )
Step 5: Create the Virtual Table Report
Now that we have uploaded the BUI extension that included our table definition, we should have a new entry in our data dictionary. In this step we will build our virtual report based off of this definition.
- Open the Reports Explorer
- Create a new Blank Report
- We can see that the virtual table is listed in the Data Dictionary section as 'Table (Organization$Employee) '
- Create a report based on that table
- Add any filters if necessary
- Now this report can be added into the BUI anywhere where any other BUI reports (quick search, navigation set, workspace etc.) can be added.
