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

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, DOCS 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 DOCS 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 DOCS using the HTTP Transport.  In order to upload file to DOCS 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 DOCS.  PCS will pass in an array of folders along with the DOCS instance and identity domain name, and PCS instance folder path in DOCS. CreateMultipleFolders will then loop through the list of folders and invoke CreateFolder proxy service and DOCS_REST business service to create the folder in DOCS.  The DOCS_REST encapsulates the REST API exposed by DOCS. For folder creation it will invoke “/api/1.1/folders/{folder id}” resource in DOC.

Prior to the DOCS 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 DOCS 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 current PCS (16.2.1), the predefined instance_id variable contain the “bpmn:” prefix, however the folder created in DOCS is without the prefix, hence, in order to retrieve the correct folder id in DOCS for the PCS instance, we will need to remove the prefix in the request payload.

GetFolderItems will retrieve all root folders for a DOCS user that you have configured in PCS-DOCS Integration by invoking the DOCS 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 DOCS 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 DOCS 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 DOCS upload service using HTTP Transport.

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

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

The DOCS 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 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.

Add Your Comment