X

Best Practices from Oracle Development's A‑Team

Integrating PCS, CEC and BI Publisher using OSB/SOACS – Part 2

Derek Kam
Consulting Solutions Architect

Introduction

In this part 2 of the blog, we will examine the OSB design used in this demonstration.  OSB is used as an integration layer for PCS, CEC and BI Publisher as OSB plays an important role acting as an integration layer for protocol translation and message transformation, and it will also serve as a service orchestration layer.

At the time of writing this blog, SOACS is based on SOA Suite 12.1.3, so if you are planning to use SOACS, you will need to use SOA Suite 12.1.3 Quickstart with Jdeveloper 12.1.3 as the IDE tool to design your OSB service. If you are using OSB on-premise, you can use either SOA 12.1.3 or SOA 12.2.1.

In this demonstration, we will expose few SOAP-based OSB services to PCS for interaction with CEC and BI Publisher OSB :

# Proxy Service Proxy /Business Service DOCS REST API BI Publisher Service
1. GenerateBIReportToDOCS BIPublisherReportService
UploadFile
  ReportService/runReport
2. GetFolderByID DOCS_REST    
3. GetFolderByName GetFolderItems
GetFolderItemsByID
   
4. GetFolderItemsByID DOCS_REST /folders/{folderID}/items  
5. GetFolderItems DOCS_REST /api/1.1/folders/items  
6. UploadFile UploadFile    
7. CreateFolder DOCS_REST    
8. CreateMultipleFolders GetFolderByName CreateFolder “/api/1.1/folders/{folder id}  

During the report generation process, it will also upload the generated report in a specific folder created for the PCS instance in CEC using the HTTP Transport.  In order to upload file to CEC using HTTP transport, we will also need to build a multipart message.  The following section of this blog describe the OSB design in detail and how to build a multipart message.

OSB Design

PCS will invoke 2 SOAP based proxy services, CreateMultipleFolders and GenerateBIReportToDOCS. They will then invoke other reusable proxy services to perform the task required by the process.

CreateMultipleFolders is used to create single or multiple folders in CEC.  PCS will pass in an array of folders along with the CEC instance and identity domain name, and PCS instance folder path in CEC. CreateMultipleFolders will then loop through the list of folders and invoke CreateFolder proxy service and DOCS_REST business service to create the folder in CEC.  The DOCS_REST encapsulates the REST API exposed by CEC. For folder creation it will invoke “/api/1.1/folders/{folder id}” resource in DOC.

Prior to the CEC API invocation to create the folder, we will need to retrieve the base parent folder id where the subfolder(s) will be created. In this case, the base folder will be the PCS process instance folder that you have configured in PCS, e.g. “/SalaryReportProcess_1.0/ SalaryReportProcess_Instance_123/Application Documents”.  We will be discussing the GetFolderByName later in the blog.

PCS_DOCS_BI_OSB_CreateMultiFolder

CreateFolder

In CreateFolder proxy pipeline, we will replace the URL with the CEC instance and identity domain name passed in from PCS.

PCS_DOCS_BI_OSB_CreateFolder

GetFolderByName

In this pipeline design, we will invoke 2 proxy services, GetFolderItems and GetFolderItemsByID.  Prior to the invocation, we will need to remove the “bpmn:” prefix folder path, this is because in PCS (16.2.1), the predefined instance_id variable contains the “bpmn:” prefix, however, the folder created in CEC is without the prefix, hence, in order to retrieve the correct folder id in CEC for the PCS instance, we will need to remove the prefix in the request payload.

GetFolderItems will retrieve all root folders for a CEC user that you have configured in PCS-CEC Integration by invoking the CEC API: /api/1.1/folders/items. We will then loop through the response payload and find the matching root folder name we are searching for.

Using the matched root folder ID found in the GetFolderItems, we will then invoke GetFolderItemsByID proxy service to find the folder ID for the remaining folder name.  To do this, we need to invoke the CEC REST API:  /folders/{folderID}/items and pass in the root folder ID. We will then loop through the response payload and find the matching folder name that we are searching for until we find the folder ID for the last destination folder.  The folder ID will then be returned to the calling proxy service.

PCS_DOCS_BI_OSB_GetFolderByName

GenerateBIReportToDOCS

The GenerateBIReportToDOCS proxy service will invoke 2 services, the BI Publisher Report Service and UploadFile proxy service.

GenerateBIReportToDOCS invokes runReport operation in BI Publisher Report Service to generate a PDF report, the report data in response will be base64 encoded.  It will then pass the report data to UploadFile proxy service to decode the data to a byte array and invoke the CEC upload file REST service to upload the doc.

PCS_DOCS_BI_OSB_GenerateBIReportToDOCS

UploadFile

The UploadFile proxy service will construct a multipart message, decode base64 data returned by the BI Publisher using Java Callout, then add the decoded data on to the message.  After the message has been constructed, it will route the multipart message to the CEC upload service using HTTP Transport.

When you are building the multipart message, CEC will require a multipart request message with a specified boundary delimiter,  for example:

Content-Type: multipart/form-data; boundary=MIME_Boundary

The CEC multipart message translates into 2 attachments in OSB and the boundary delimiter:"-- MIME_Boundary" will be added by OSB. For example:

-- MIME_Boundary Content-Disposition: form-data; name="jsonInputParameters" { "parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001" } -- MIME_Boundary Content-Disposition: form-data; name="primaryFile"; filename="example.pdf" Content-Type: application/pdf <Binary File Content> -- MIME_Boundary--

 

The first attachment consists of the following message:

Content-Disposition: form-data; name="jsonInputParameters"

{

"parentID":"',$folderID,'"

}

To build the 1st message part, you will need to add the 1st attachment node using insert action as the first child of attachments variable in OSB, and then replace the node with the correct message:
PCS_DOCS_BI_OSB_OSB_CONFIG1  PCS_DOCS_BI_OSB_OSB_CONFIG2

 

The 2nd attachment consists of the following message with the decoded binary data:

Content-Disposition: form-data; name="primaryFile"; filename="example.pdf"

Content-Type: application/pdf

<Text/Binary File Content>

To build the 2nd message part, you will need to add a new 2nd attachment node using insert action as the last child of attachments variable, then replace the 2nd attachment with the above message.

PCS_DOCS_BI_OSB_OSB_CONFIG3

PCS_DOCS_BI_OSB_OSB_CONFIG4

PCS_DOCS_BI_OSB_UploadFileProxyService

Summary

In this 2nd part of this blog series, we have covered OSB services design for this demonstration.  In Part 3 of this blog, we will discuss the PCS design and how to invoke the services exposed by OSB.

Join the discussion

Comments ( 3 )
  • ioannis Tuesday, May 21, 2019
    Dear Derek Kam,

    Your approach is absolutely perfect. Could you please provide the source code?

    Thanks in advance,
    John.
  • Abhishek Kumar Friday, June 14, 2019
    Hi Derek ,

    Will really appreciate if you can share the code dump as we have similar requirement and hope your code can help us.

    Thanks in advance .

    Regards,
    Abhishek
  • Derek Kam Friday, June 14, 2019
    Unfortunately, I don't the code, the instruction is in the blog, and I believe the API might have changed in the latest version of cloud products used in this demo.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha