Application Builder Cloud Service 17.1.3 release allows users to expose an external web service as a business object by creating a custom business object provider (BOP). In this blog we will create a Business object leveraging the REST API's provided by GitHub using the custom BOP template that comes out of the box.
Evaluate the REST resource
GitHub exposes a set of REST API’s to fetch information regarding the user’s account.The complete list of all resources that can be fetched and the authentication schemes available can be seen here https://developer.github.com/v3/
For the purposes of this blog I have chosen https://api.github.com/users/shraybansal/repos to fetch the repositories information for the user shraybansal, whose account consists of two test repositories. If the user provides the Basic Auth credentials during authentication, then the REST request fetches information regarding private repositories associated with the authenticated user.
An important detail to note is that GitHub supports Cross Origin Resource Sharing(CORS) and allows requests from all origins, which is a requirement for BOP. In case the user wants to use any custom REST service then CORS will have to be enabled on the server for the requests. Moreover, the REST API's should be SSL enabled (https).
To begin, invoke your REST endpoint in a REST client to evaluate the fields that you require in your Business Object. I have used Postman, which is a Chrome plugin, to invoke the GET request for the GitHub repository resource and selected id, repo_name and git_url to represent fields in the ABCS business object.
|
Field
|
Data Type
|
Description
|
|
id
|
Number
|
Id of the repository
|
|
repo_name
|
String
|
Name of the repository
|
|
git_url
|
String
|
The URL to access the repository
|
Configure showcase BOP Provider
In the Extensions section of the Application Settings create a new BOP Extension and give the package name as com.test
Note: In case any other package name is used then replace com.test references used in this blog with the package name provided.
Click on Template and choose the showcase BOP provided with the ABCS instance. The showcase BOP is an example of how the Application Builder API’s are being used in the BOP configuration through Employee and Department entities.
This action creates the files required for configuring a BOP and arranges the files in a defined structure in the Resource Browser.
Modify the Entity Provider
To add the entity definition we will have to include the github repository entity to the existing entity definitions in the MyCustomEntityProvider.js file
In the existing code add the call to the _createGitHub method just before the _createDepartment method.
var github = this._createGitHub();
Add the github variable to the _entities array.
this._entities = [github, employee, department];
Define the GITHUB_ID variable and add the implementation of the _createGitHub entity in the code just before the _createEmployee method.
MyCustomEntityProvider.GITHUB_ID = 'com.test.github';
MyCustomEntityProvider.prototype._createGitHub = function() {
var id = DataModelFactory.createProperty({
id: 'id',
name: 'ID',
type: PropertyType.KEY
});
var repo\_name = DataModelFactory.createProperty({
id: 'name',
name: 'repo\_name',
type: PropertyType.TEXT
});
var git\_url = DataModelFactory.createProperty({
id: 'git\_url',
name: 'git\_url',
type: PropertyType.TEXT
});
return DataModelFactory.createEntity({
id: MyCustomEntityProvider.GITHUB\_ID,
singularName: 'GitHub Detail',
pluralName: 'GitHub Details',
description: 'BO representing details of GitHub Repo of the user',
properties: \[id, repo\_name, git\_url\]
});
};
The code should look like this in the Resource browser
Click on Save before proceeding.
Create the implementation file
Create a Github.js file under the js directory.This file will hold the implementation of the READ operation which will be defined in the operations provider.
****
Add the implementation code to the file. This code is similar to the Employee and Department javascript files.
define([
'operation/js/api/OperationResult'
], function (
OperationResult
) {
'use strict';
var Github = function() {
};
Github.getRepos = function(url, authenticator, operationData) {
var ajaxObj = {
method: 'GET',
url: url,
dataType: 'json',
xhrFields: {
withCredentials: false
}
};
// Include REST call here which performs the real operation retrieving your Employee data
var self = this;
return new Promise(function (fulfil, reject) {
authenticator.invoke( ajaxObj ).then(function (response) {
var arr = Github.\_parseDetails(response);
return fulfil(OperationResult.success(arr));
});
});
};
Github.\_parseDetails = function (response) {
var res = \[\];
var data = response.getData();
data.forEach(function(items) {
res.push(items);
});
return res;
};
return Github;
});
The code in the Github.js file should look like this:
Click on Save before proceeding.
Modify the Operations Provider
The next step is to modify the operations provider MyCustomOperationProvider.js to define the operations allowed on the github entity.For simplicity sake we will add just the READ operation in the MyCustomOperationProvider.js file
Add the BOPAuthenticators and Resource API’s in the define block along with the reference to the Github javascript file created in the previous step to the array of dependencies
'bop/js/api/operation/BOPAuthenticators',
'bop/js/api/resource/Resource',
'com.test/js/Github'
The define block should look like this:
The dependencies will be passed to the definition function as function arguments, listed in the same order as the order in the dependency array. The function is called to define the module once all dependencies have loaded.
function (
BOPAuthenticators,
Resource,
OperationBuilder,
OperationInput,
Pagination,
Operation,
Department,
Employee,
Github
)
Add the dependencies parameter as the argument in the function that is referenced by MyCustomOperationProvider variable. The dependencies parameter is a required attribute in the authenticator implementation.
var MyCustomOperationProvider = function(dependencies)
Declare _dependencies and _resources array variables in addition to the _operations array
this._dependencies = dependencies;
this._resources = [];
Add _initForGithub() call just before the _initForEmployees() method
After the additions the function would resemble
var MyCustomOperationProvider = function(dependencies) {
this.\_operations = \[\];
this.\_dependencies = dependencies;
this.\_resources = \[\];
this.\_initForGitHub();
this.\_initForEmployee();
this.\_initForDepartment();
};
Define the GITHUB_ID variable, which should be the same as defined in the MyCustomEntityProvider.js.
Add method getAuthenticator and associate a function which returns an instance of the default authenticator for invoking rest services
MyCustomOperationProvider.GITHUB_ID = 'com.test.github';
MyCustomOperationProvider.prototype.getAuthenticator = function() {
var self = this;
return BOPAuthenticators.getDefault(this.\_dependencies, {
getResources : function() {
return self.\_resources;
}
});
};
After the modifications the code should look like this:
Add the method _initForGithub that internally calls _getAllRepos method, which associates a function that returns an Operation instance based on the current builder configuration provided by the user. The operation type Operation.Type.READ_MANY is leveraged for retrieving collection data and is available for example when client drops the Table into an empty page.
Moreover, we will also add the list of resources to be whitelisted that are exposed by this BOP in the _getAllRepos method.
MyCustomOperationProvider.prototype._initForGitHub = function() {
var github = Abcs.Entities().findById(MyCustomOperationProvider.GITHUB\_ID);
if (github) {
this._operations.push(this._getAllRepos(github));
}
};
MyCustomOperationProvider.prototype._getAllRepos = function(github) {
var self = this;
var url = '[https://api.github.com/users/shraybansal/repos';](https://api.github.com/users/shraybansal/repos';)
this.\_resources.push(
Resource.create({
id : 'github.fetch',
template : url,
entity : MyCustomOperationProvider.GITHUB\_ID
})
);
return new OperationBuilder({
name: 'Get all Repos',
type: Operation.Type.READ\_MANY,
performs: function(operationData) {
return Promise.resolve(Github.getRepos(url, self.getAuthenticator(), operationData));
}
}).description('Fetch all registered employees with all relevant information.').
takes(new OperationInput({
entity: github
}).parametersAll()).
returns(github).
paginates(Pagination.STANDARD).
build();
};
After adding the two methods the code should look like this:
Click on Save and Reload the extension to complete the BOP configuration process.
Create Business Object
Navigate to Business Objects by going through the Menu and clicking on the Data Designer.
Click on the Business object from external service button and you will see your Business Object Provider (BOP) in the REST Services catalog. Select the BOP and click on Next.
Select the GitHub Detail Business Object and click on next.
Drag and drop git_url and repo_name to the Selected fields column. Click Next
Provide Basic Authentication credentials required for accessing the REST resource. Click Next.
Click Finish. Check the Data tab to see the data from the REST API
More information regarding the Business Object Provider can be seen through the documentation: Creating Business Objects
ABCS Extension API's are documented here: JavaScript Extension Development API for Oracle Application Builder Cloud Service: Home
Subscribe to the ABCS Youtube channel: https://www.youtube.com/channel/UCFMTiIZAE6f3Ib91sY6Ms3g