Use Oracle Integration to Add Attachments to a Process Instance
Translate multipart/form-data into multipart/mixed using Oracle Integration REST Adapter
The other day it came to my attention that it’s not really straightforward to add attachments to an Oracle Process Instance using the REST API.
One reason for this is that it requires multipart/mixed media type for the request body message format, and producing this kind format is not so common for JavaScript clients. The JS clients are more used to working with multipart/form-data, the de-facto standard for form-based file upload in HTML.
One way of overcoming this is to use Oracle Integration Cloud (OIC) between the JS client and Process REST API. OIC has a REST Technology Adapter that supports sending/receiving attachments in both multipart/mixed and multipart/form-data media types. The goal is to shape in OIC a REST interface that accepts multipart/form-data, to do a translation into multipart/mixed (alongside with other transformations/actions if required) and to call the Process REST API. Below are the main steps for achieving this.
1. Create a REST Connection in OIC for Process REST API.
Go to OIC Homepage > Designer > Connections to create a new connection by selecting the REST Adapter.
For the Connection Properties, setup the Connection URL as:
[OIC hostname]/ic/process/v1
The relative path of the Add Attachments endpoint (/processes/{processId}/attachments) will be setup at integration level, thus we can reuse the Connection for other use-cases involving the Process REST APIs.
2. Create the Integration. Shape de REST interface.
In the OIC Homepage > Designer >Integrations page create a new Integration. Choose the App Driven Orchestration Integration Style. This will give us flexibility if we want to add additional steps in the future, but Basic Routing should work also.
Now, to shape a REST interface for our Integration, add the Sample REST Endpoint Connection as the Trigger activity (Right after START). There’s nothing in particular to be configured for a REST Connection that will be used as Trigger, so we can use this out-of-the-box one.
In the Resource Configuration screen we setup a relative path for the Integration REST endpoint:
/processes/{processId}/attachments
In the Request Parameters screen you can specify that the processId template parameter is an integer.
Next, for the Request configuration we need to tick Accept attachments from request. Now, we have two options for the media type of the request: multipart/form-data or multipart/mixed and the possibility to define the request payload. We can choose multipart/form-data and give an example request payload, but most JavaScript clients will work best if they send the additional information as [key=value] pairs, similar as submitting an HTML form. In this case, we prefer this approach so we tick also Request is HTML form. This will keep the multipart/form-data setting on, although not visible in the wizard screen:
For the Response configuration, for simplicity, we want to return the same response format as from the Process Add Attachments REST API.
For this, we need to pass a sample response body. Choose the one given in the official documentation of the Process REST API (--OR-- enter sample JSON):
All the other settings can be left as default.
3. Configure the REST endpoint for Process REST Connection. Do the mappings.
Now, right after the Trigger activity, let’s add a REST Invoke activity by selecting the REST Connection created earlier for the Process REST API:
In the Basic Info screen we setup the relative path for the Process Add Attachments REST Endpoint:
/processes/{processId}/attachments
In the Request configuration screen, tick Send attachments in request. If we look at the Process REST API documentation for adding an attachment to a Process, we see that two body parts are required to be sent:
- the file attachment itself
- one .json file containing data about the attachment (attachment name and mime type)
Besides selecting multipart/mixed for the request media type, the trick here is to send the json information as a request payload when configuring the REST Endpoint:
So, we configure the request payload with the example .json file structure given in the official documentation of the Process REST API ( — OR — enter sample JSON):
For the Response configuration, we need to setup the same Response Body sample given in the Process REST API documentation (see above the responsesample.json snippet):
All the other settings can be left as default.
Next, we do the first mapping that will build the request to Process Add Attachment REST API. We need to:
- pass attachment Reference
- for the attachment Properties, map the contentType and partName
- map the processId parameter from TemplateParameters; in this example we’ve shaped the Integration relative Endpoint to look the same as the Process REST API one, but, in other cases, we can choose to pass this information as a HTML form data
- extract the attachmentName and mimeType information from input HTML form data and map it to the Process REST API request payload; the JS clients will pass this information in a [key=value] format and the Integration will transform it in a .json payload as required for the Process REST API; to extract the values add the XSLT attribute filters in the Target mapping aria, for both attachmentName and mimeType request-wrapper’s children:
/nssrcmpr:execute/ns23:ParameterList/ns23:parameter[@name= ‘attachmentName’]/nssrcmpr:execute/ns23:ParameterList/ns23:parameter[@name= ‘mimeType’]
The second mapping that we need to complete is for the Response that the Integration will return to the calling clients. As we’ve configured an identically Response as the Process REST API, we just need to map all elements:
This being done, we only need to add a Tracking information for the Integration (for example the processId template parameter) and to activate the Integration:
Testing from Postman
Assuming we have a Process to play with and a running Process Instance, we can test the Integration from Postman. The Endpoint URL should look like:
[OIC hostname]/ic/api/integration/v1/flows/rest/PROCESSATTACHMENTSWRAPPER/1.0/processes/{processId}/attachments(see the How to Run Integration information to get the complete Endpoint URL)
We need to select a form-data Body and add three elements:
- attachmentName (text type)
- mimeType (text type)
- a file name (file type; select a file in the Value column; also setup the Content Type accordingly)
Add a valid Authorization for OIC (for example Basic Auth) and Send the POST request; if everything correctly setup we receive a success response:
If we go to the Process Instance details, Documents section, we can see that the attachment has been added:
We can also track the instance in OIC (OIC Homepage > Monitoring > Tracking) and check the messages that have been received/send and the mappings by looking on the Activity Stream:
Calling from an Oracle Visual Builder Application
Now, I won’t get into details on how to create an Oracle Visual Builder Application and on how to call a multipart/form-data service. A great tutorial shows how to Send photos and files from Oracle Visual Builder apps to Oracle Content and Experience and implicit how to construct a multipart/form-data request body payload.
For this case, I’ve built simple Visual Builder Web Application with a File Picker component, a Text input field for passing the Process Id information and an Upload button.
For the Service Connection information I’ve used the Integration Endpoint URL, not forgetting to setup multipart/form-data as the Request Body Media Type:
Then, when assigning the variables in the File Picker Selection Event Action Chain, I’ve created a new variable that will keep the mime type value of the file:
For the Call REST Endpoint activity (in the Action Chain associated with Upload Button ojAction event) I need to pass the processId parameter (I’m just getting it’s value from an Input Text) and to setup the Content Type as multipart/form-data:
Then, in the {}body mapping I need two pass the two form-data parameters that OIC expects (attachmentName and mimeType) and a reference to the File (the primaryFile name is arbitrary):
All being set, the test page looks like this:
And after the upload being kicked, the file gets into Process via OIC:
I end this post with an useful documentation page on Using the REST Adapter with Oracle Integration when working with attachments.
