Integrating Oracle Project Cloud with Documents Cloud Service using REST APIs and business object-level security.

Introduction

Oracle Documents Cloud Service (DCS) enables collaboration through rich set of social and mobile-optimized features. Customers often come across requirements to integrate DCS to Oracle Applications cloud. Such integration improves productivity by taking advantage of features of DCS Service. In this post, let’s take a look at integrating Project Management Cloud, a part of Oracle ERP cloud, with DCS. Contents of this post were written based on R11 of Project Management Cloud and R16.4.5 of DCS Service.

Main Article

Project Cloud and Document Cloud both provide secure REST APIs for integration. In addition, Document Cloud offers UI integration through applinks – short-lived links accessible through HTML IFRAME. Project Cloud offers UI customization through Page Composer, which is sufficient to implement this solution. See links to documentation to these APIs in references section below. The solution described in this post uses aforementioned APIs and tools and a custom integration service deployed to JCS-SX. This custom integration service is a simple java program that implements the handshake between Project Cloud and Document Cloud. Although deployed here to JCS-SX, this java program can be deployed anywhere. JCS-SX is recommended because it is usually deployed alongside the Oracle SaaS application and pre-integrated with SaaS through Single-Sign-on and SAML id propagation (which can be useful for other use cases). Below is a high-level depiction of the overall solution.

001

Figure 1 – Overview of the solution

 

Guidance to implement this solution is split into subsections. For ease of comprehension, these instructions are abstracted. Click on one of the links below to jump to a subsection of interest.

Note: The overall solution leverages parts of design described in another blog post on integrating DCS and Sales Cloud (link provided in references section).

Documents Cloud REST API

The following actions need to be performed through the API:

  • Query whether a sub-folder exists in DCS for the selected project.
  • Create a sub-folder for the project, based on project name.
  • Get an appslink to the sub-folder

Get contents of a folder, in order to verify existence of sub folder with same name as project:
Request:

GET /documents/api/1.1/folders/F7A4AF94F58A48892821654E3B57253386C697CACDB0//items HTTP/1.1
Host: <DocsCloudHostName:port>
Authorization: Basic am9obi5kdW5iYXI6VmlzaW9uMTIzIQ==
.....<br class="none" />

Response:

....
{
"type": "folder",
"id": "FE4E22621CBDA1E250B26DD73B57253386C697CACDB0",
"parentID": "F7A4AF94F58A48892821654E3B57253386C697CACDB0",
"name": "Cloud based HCM",
"ownedBy": {
"displayName": "John Doe",
"id": "UDFE5D9A1F50DAA96DA5F4723B57253386C6",
"type": "user"
}
...<br class="none" /><br class="none" />

Create a new sub-folder:

Request:

POST /documents/api/1.1/folders/F7A4AF94F58A48892821654E3B57253386C697CACDB0 HTTP/1.1
Host: <hostname:port>
Authorization: Basic am9obi5kdW5iYXI6VmlzaW9uMTIzIQ==
…..
{
    "name": "TestFolder1",
    "description": "TestFolder"
}

Response:

HTTP/1.1 201 Created
Date: Tue, 24 Jan 2017 22:14:50 GMT
Location: https://docs-gse00000310.documents.us2.oraclecloud.com/documents/api/1.1/folders/F073C821561724BDA2E6B6C73B57253386C697CACDB0
….

Create appslink to a subfolder:
Request:

POST /documents/api/1.1/applinks/folder/F7A4AF94F58A48892821654E3B57253386C697CACDB0 HTTP/1.1
Host: <DCS host:port>
Authorization: Basic am9obi55iYXI6VmlzaW9uMTIzIQ==
....

{
    "assignedUser": "casey.brown",
    "role":"contributor"
}

Response:

HTTP/1.1 200 OK
 Date: Wed, 25 Jan 2017 00:52:40 GMT
 Server: Oracle-Application-Server-11g
 .....

{
 "accessToken": "eDkMUdbNQ2ytyNTyghBbyj43yBKpY06UYhQer3EX_bAQKbAfv09d4T7zuS5AFHa2YgImBiecD2u-haE_1r3SYA==",
 "appLinkID": "LF0fW2LLCZRsnvk1TVNcz5UhiqDSflq_2Kht39UOZGKsglZo_4WT-OkR1kEA56K91S1YZxSa8pBpQZD6BSWYCnAXZZKAZaela3IySlgJaaAvJrijCvWTazDqCeY56DvyYgHNjAoZPSy2dL0DzaCWi0XA==",
 "appLinkUrl": "https://docs-gse00000310.documents.us2.oraclecloud.com/documents/embed/link/app/LF0fW2LLCZRsnvk1TVNcz5UhiqDSflq_2Kht39UOZGKsglZo_4WT-OkR1kEA56K91S1YZxSa8pBpQZD6BSWYCnAXZZKAZaela3IySlgJaaAvJrijCvWTazDqCeY56DvyYgHNjAoZPSy2dL0DzaCWi0XA==/folder/F7A4AF94F58A48892821654E3B57253386C697CACDB0/_GruppFinancial",
 "errorCode": "0",
 "id": "F7A4AF94F58A48892821654E3B57253386C697CACDB0",
 "refreshToken": "LugYsmKWK6t5aCfAb8-lgdmp7jgF8v3Q9aEtits4oy0Oz9JtaYnL9BOs8q4lwXK8",
 "role": "contributor",
 "type": "applink"
 }<br class="none" /><br class="none" />

Project Cloud REST API

JCS-SX custom service in the solution ensures that only users with access to a project could access the corresponding folder in DCS. This is achieved by invoking Project API with the JWT passed to the  service by project cloud. Without a valid token, the JCS-SX service will return an error.

Here is the sample payload for the service.
Request:

GET /projectsFinancialsApi/resources/11.1.11/projects/300000058801556?fields=ProjectId,ProjectName&onlyData=true HTTP/1.1
Host: <Project Cloud>
Authorization:Bearer <JWT token>
...

Response:

HTTP/1.1 200 OK
Server: Oracle-Application-Server-11g
…
{
  "ProjectId" : 300000058801556,
  "ProjectName" : "Dixon Financials Upgrade"
}

Security

There are several aspects of security addressed by this solution.

  • Project Cloud and JCS-SX integration is secured by single-sign-on infrastructure of which both systems are participants. Single sign-on is enabled for JCS-SX instances and their co-located Fusion SaaS applications. This integration only ensures that the service is invoked on behalf of a valid user of ERP Cloud by using a provided JWT token. Single sign-on could further secure the solution, but it will require additional testing and configuration.
  • The API calls from JCS-SX to Project Cloud are secured by JWT tokens supplied by Project Cloud upon invoking the JCS-SX service. This JWT token is bound the currently logged in Project Cloud user. JWT Tokens are issued with a predetermined expiry time.
  • JCS-SX to DCS integration in this solution is secured by basic authentication. Federation of identity domains could allow seamless authentication and authorization of users between these two systems, with additional effort.

JCS-SX Service

This is a J-EE servlet that takes Project Name, Project ID and a JWT token as query string parameters. The functions of the service are as follows:

  • Using supplied JWT token and Project Id, try to get information about project using Project Cloud REST API. If the request fails, stop processing and return “HTTP 401 unauthorized” error.
  • If the previous step succeeds, query DCS for a sub-folder with the supplied project name. The root folder ID in DCS, basic authentication credentials are available to the servlet.
  • If a sub-folder does not exist, create a new sub-folder.
  • Create an appslink to the sub-folder. Generate HTML content with an IFRAME element pointing to the appslink returned by DCS API.

Customizing Project Cloud

For this integration, Project Cloud must be customized for the following:

  • Invoke JCS-SX service
  • Pass Project information such as Name and Id, along with a JWT token to JCS-SX service.
  • Display the appslink content from DCS.

Project Cloud does not yet provide the app composer tool available in Sales Cloud at the time of publishing this post. However, page composer’s features are sufficient for this integration.  Here are the steps to implement:

  • Create and activate a sandbox, if the current use does not have one already.
  • Navigate to an appropriate page of project management cloud where Document Cloud’s content could be displayed. For this solution, let’s navigate to Home->Projects->Project Financial Management. Then, search for projects and click on a project, then click on Documents tab.

002

  • Click on top right menu and select “Customize Pages”. Page Composer is now activated current page.
  • Click on a section of page where DCS appslink should be displayed.
  • On top left menu of Page Composer, click on “View” and select “Source”. Click on “Add Content”, click on “Components” and select “Web Page” widget.
  • 003Once the widget is displayed, drag the edges to desired size. Then, while the web page widget is selected, click on “Edit” of the Page Composer menu, on top left. Web Page component’s property dialog is displayed. Click the drop-down next to “Source” field and select “Expression Builder”.
    004
  • Once the widget is displayed, drag the edges to desired size. Then, while the web page widget is selected, click on “Edit” of the Page Composer menu, on top left. Web Page component’s property dialog is displayed. Click the drop-down next to “Source” field and select “Expression Builder”. Enter appropriate JCS-SX host and service URI for the JSC-SX service. Notice the bindings variables for project information and JWT token supplied through query string. These variables are available to the page by default.
    https://<JCS-SX HOST>:<PORT>/doccloud?projectID=#{bindings.ProjectId.inputValue}&projectName=#{bindings.Name.inputValue}&buname=#{bindings.Name3.inputValue}&customername=#{bindings.Customer.inputValue}&jwt=#{applCoreSecuredToken.trustToken}

005

  • Click OK to submit and click “Apply” on Component properties page. If the integration works end-to-end, DCS page should be displayed as shown below, with a sub-folder named after the project in focus. Use can drag and drop documents into the Widget to add documents.

    006

Summary

This article explains how to integrate Oracle Project Management Cloud and DCS using REST API and JCS-SX.  It provides API snippets, instructions for customizing Project Cloud and the overall logic of the service deployed on JCS-SX. This approach is suitable for R11 of ERP cloud and R16.4.5 of DCS. Subsequent releases of these products offer equivalent or better integration capabilities. Refer to product documentation for later versions before implementing a solution based on this article. 

References

DCS REST API:

http://docs.oracle.com/cloud/latest/documentcs_welcome/WCDRA/index.html

Project Portfolio Management Cloud REST API:

http://docs.oracle.com/cloud/latest/projectcs_gs/FAPAP/

Blog on Sales Cloud to DCS integration:

http://www.ateam-oracle.com/integrating-oracle-document-cloud-and-oracle-sales-cloud-maintaining-data-level-business-object-security/

 

 

Add Your Comment