X

The Digital Experience Platform blog covers the latest in innovative technologies to help you transform your business.

Quickly Develop Content Connector to integrate Box

Overview

Oracle Content and Experience Cloud (OCE) is a cloud-based content hub to drive omni-channel content management and accelerate experience delivery. Content contribution from existing content repository become key part of content hub.

Content Connectoris the capability which allow end-user to bring content from external repositories. There are prebuilt connector for Oracle WebCenter Content, Dropbox, Google Drive & Onedrive, you can find more information here.

Developercan build custom content connector for any cloud/on-premise content respository. You can refer Sample connector for Stock photo site – Pixel , for more information refer here.

In this article we will learn how to build connector to integrate Box from scratch. You can find source code for this article here

Get started

Connector comprise of two major artifacts 

  • REST Interface Implementation : OCE communicate to connector via REST endpoints. You can find REST interface detail here. Developer need to implement all required method and deployment should be accessible from OCE connector registration page.
  • Content Picker : End user will see this screen for selecting content from source repository. Developer can use any language/framework to implement it. You can either deploy UI project along with REST interface or separately, 

 

We can group development activities in below steps

Generate Starter Code (Optional)

First you need to get Connector SDK from here. Open API based YAML file is available as part of connector SDK. You can generate server-side code based on your language preference using code generator tool.For Box connector we will choose NodeJs.

Your generated code structure will look like 

Implement REST Interface

Auto generated code will include Controller & Service file for each end points. Let’s understand the purpose of each endpoint and what’s required for building Box connector. For detail implementation refer to source code.

  • /api

This return the API version of connector which you are implementing. You can refer documentation for the REST interface version, currently it’s v1.

 

Modify /service/APIResourceService.js to return version as “v1”.

  1. exports.apiVersionAuthorizationAuthorizationURLsPOST = function (clientId, clientSecret, body) {    
  2.   return new Promise(function (resolve, reject) {    
  3.     var response = {};    
  4.     response = {    
  5.       "authorizationURL""https://account.box.com/api/oauth2/authorize?response_type=code&client_id=" + clientId + "&redirect_uri=" + body.redirectURL + "&state=box-connector",    
  6.       "fieldValueMap": {}    
  7.     };    
  8.     resolve(response);    
  9.   });    
  10. }    

Connector Configuration

  • /api/{version}/server

This is the next end point which is invoked from OCE to fetch various configuration value & custom field for connector. You can modify /service/ServerResourceService.js to return response with all configuration & fields.

For Box Connector, we will use below configuration

authenticationType : “OAUTH”

pickerType: “CUSTOM”

fields :Here we need to define all the custom field which are required for the connector. It’s important to understand that list of fields are beyond what you see in registration screen, consider this as variable in OCE which can hold values for you. Each field has attribute to decide who can set the value (accordingly it will be visible on administration screen).

  • Field will be visible on configuration screen where administrator can set it. In our case we will need clientId & clientSecret.
  • Field for keeping the value incontext of individual user, this can be set by end user. For example you might want to store user/password for external system which doesn’t support security integration. 
  • Field for which only connector can store the values in conext of individual users. For box connector we need accessToken & refreshToken as connectorSettable field where connector will get the token using Box API and it will be persisted with OCE for future call.
  • Field which will be send back to connector as callback during the OAuth authorization process. Typically it’s code which you receive from external repository as part of 3-legged authentication process.

supportedConnectorTypes:Keep it default as “COPY”, in future you will have more options.

It’s important to provide localization strings in base language.

 

Note:All the field value will be send with every request from OCE to connector, name of field will be prefixed with “X-CEC-{fieldName}”.For example clientId will become X-CEC-clientId

For Box connector we have set authenticationType as “OAUTH”. For this we need to implement below end points

  • /api/{version}/authorization/authorizationURLs

OCE will send POST request to connector along with all the stored field value. In this case you need clientId & clientSecret to build authorization URL. Response will have the authorization URL & fieldMap ( optional, this is only used if you want to store/update any field values otherwise pass null array)

 

Modify swagger.yaml to replace parameter from name:”headers” to X-CEC-clientID, X-CEC-clientSecret.

  1. exports.apiVersionAuthorizationAuthorizationURLsPOST = function (clientId, clientSecret, body) {  
  2.     return new Promise(function (resolve, reject) {  
  3.         var response = {};  
  4.         response = {  
  5.             "authorizationURL""https://account.box.com/api/oauth2/authorize?response_type=code&client_id=" + clientId + "&redirect_uri=" + body.redirectURL + "&state=box-connector",  
  6.             "fieldValueMap": {}  
  7.         };  
  8.         resolve(response);  
  9.     });  
  10. }  
  • /api/{version}/authorization/completedAuthorizations

After user authorize the access to your Box application then Box send request to OCE call back url with authorization code. OCE passes all the information to connector by posting data to this end point. Here you need to get code and again invoke Box API to retrieve accessToken & refreshToken for logged in user. As response you need to send value as part of fieldValueMap

Modify swagger.yaml to replace parameter from name:”header” to X-CEC-clientId,X-CEC-clientSecret & X-CEC-code.

Fetching Content

  • /api/{version}/content

OCE pull the content from source repository using this end point. The identifier is passed as query parameter as URI (it’s content ID which is passed by Content Picker, refer Customer picker development section).

Modify swagger.yaml to replace parameter from name:”headers” to X-CEC-accessToken which you need to fetch content from underline source repository.

Note: All the reponse header attribute like Content-Disposition are case sensitive, so please refer yaml file for exact syntax. In upcoming release it will be case insensitive.

 

Register Application with Box

To enable the integration of BOX with OCE, you need to register at https://developer.box.comand create Application. You can refer official help documentation.

 

After application creation, navigate to tab Configurationto get Client ID & Client Secret. This value you need to set from OCE connector Configuration screen.

 

 

Custom Picker Development

End user can select the custom connector from menu option, and then he will be presend with interface to select content. This interface is refered as Content Picker, you can either leverage out of box generic picker of develop custom picker as per your requirement. For Box, we will develop custom picker which can be accessed using  http://host:port/picker.

Modify index.js to include route pattern for “/picker” and load the HTML page from /html/picker.html

Includeoracle-oce-custompicker.jsand implement onInit function to get accessToken for logged in user. You can use any framework to build UI or use the native picker provided by the content repository. Here we will leverage the Picker provided by Box and register the listener on chooseeven to send selected item back to OCE via OCE.CustomPicker.addItem

Register Connector

You can follow the step provided for sample connector registration, just make sure to give Connector Service URL pointing to your connector deployment. Also Customer Picker URL will be https://host:port/picker

Make sure to check “Custom Picker uses it’s own OK/Cancel buttons” because Box picker will have it’s own selection button.

On the configuration page you will see autopopulated attribute “Redirect URL”. Copy the value and navigate back to Box application’s configuration page and set this value to “Redirect URI” field as shown below

Last step is to Enable the connector, after that it will be visible to end user under “Add” as shown below

Demo

Let’s see the connector in action

 

Disclaimer: This is tutorial post to demonstrate how easily custom connector can be developed with any content repository. Developer will be responsible for their choice of technology and implementation. Please do not log Oracle SR if any part of sample code is not working as expected, instead you can comment here. 

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.