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 ERP 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 are applicable to 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. It leverages parts of design described in another blog post on integrating DCS and Sales Cloud (link provided in references section). Below is a high-level depiction of the solution.

Figure 1 – Overview of the solution

JCS-SX is a PaaS-for-SaaS offering usually deployed alongside the Oracle SaaS application and pre-integrated with SaaS through Single-Sign-on. 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.

• Documents Cloud REST API
• Project Cloud REST API
• Security
• JCS-SX Service
• Customizing Project Cloud

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 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.
• 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.

• 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.
• 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”.
  
• 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}

• 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.
  
  

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/

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission