Skip navigation

REST is useful in integrating multiple systems in loosely coupled way. It just works because you do not need to tie this API with any client-side technology. Just due to this reason, lot of use cases can be imagined in (process) integration space, thus making a real opportunity for platform/language independence. Few of such use cases would be,

 

  • API accessed from a client side Web application
  • API accessed from a Mobile (iOS/Android/Windows Mobile) application
  • API accessed from an IoT device

 

Like its other peer services, Oracle Process Cloud Service also can be integrated with Organization’s internal and/or external applications using REST API.

 

The complete reference library of the PCS REST API is available here.

 

The whole bunch of API endpoints is broadly grouped into 8 different tasks (at the time of this blogging) as shown in below diagram.

image2016-5-10 18-2-31.png

To operate with these APIs, one can choose either a command line tool like cURL or platform specific client libraries (like Jersey for Java).

 

Now let us understand both the approaches for “Creating a Process Instance” under “Manage Processes” category.

image2016-5-10 18-2-51.png

The approach has 3 parts to accomplish the requirement.

 

  • cURL setup and other pre-requisites
  • cURL based approach to create process instance
  • Jersey based approach to create process instance

 

cURL setup and other pre-requisites

 

To use cURL to access the Oracle Process Cloud Service REST API, perform the below actions:

 

  • Install cURL as mentioned in Quick Start.
  • In a command window, set the cURL environment variable, CURL_CA_BUNDLE, to the location of your local CA certificate bundle

 

By clicking on the “Create a Process Instance” link in above diagram, you can understand more details like required action type, endpoint (includes the version of the REST API), media type and body parameters for both request and response.

image2016-5-10 18-3-20.png

There are two different ways that you can construct the request payload.

 

{
    "processDefId":"testing~SimpleApplication!1.0~SimpleProcess",
    "serviceName":"SimpleProcess.service",
    "operation":"start",
    "payload":"<payload><formArg><p0:WebForm1 xmlns:p0=\"http://xmlns.oracle.com/bpm/bpmobject/BusinessData/MyBO1\"/></formArg></payload>", 
    "action":"Submit"
}





(or)


{
    "processDefId":"testing~SimpleApplication!1.0~SimpleProcess",
    "serviceName":"SimpleProcess.service",
    "operation":"start",
    "params": {
                  "argument1":"testme",
                  "argument2":15,
                  "argument3":"<MyBO1 xmlns='http://xmlns.oracle.com/bpm/bpmobject/BusinessData/MyBO1'><a1>SG</a1><a2>true</a2></MyBO1>"
              }
    "action":"Submit"
}




 

Let us explore both of these options one each in below two approaches (cURL and Jersey based).

 

Now, know the appropriate request Body Parameters like Operation, processDefID and serviceName for a given process using the below cURL command.

 

curl -u username:password -H "Content-Type:application/json" -H "Accept:application/json" -X GET https://example.com/bpm/api/3.0/process-definitions




 

The generated response contains the required values for all the deployed processes.

 

{"levels":0,"links":[{"href":"https://example.com/bpm/api/3.0/process-definitions", "length":0, "rel":"self"}],
"items":[{
  "processDefId":"default~Incident_Management!1.0~IncidentQualificationProcess",
  "processName":"IncidentQualificationProcess",
  "application":"default", "revision":"1.0", "domain":"default",
  "interfaces":[{
"serviceName":"IncidentQualificationProcess.service",
"operation":"start",
"args":[
{"name":"inputprospect", "type":"{http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile}IncidentProfile", "location":"https://example.com/soa-infra/services/default/Incident_Management!1.0*soa_834cdc34-f2fd-4c1c-a9b6-a1843f663689/businessCatalog/BusinessData/IncidentProfile.xsd", "primitive":false
},
{"name":"inputspouse",      "type":"{http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile}IncidentProfile", "location":"https://example.com/soa-infra/services/default/Incident_Management!1.0*soa_834cdc34-f2fd-4c1c-a9b6-a1843f663689/businessCatalog/BusinessData/IncidentProfile.xsd", "primitive":false
}
  ]}], "processIcon":{"initials":"IM", "colorCode":"rgb(104,77,146)"}}]}




 

The .xsd file in the above output contains the complete list of fields in the respective XML object.

 

Record all the required values to be used in cURL based method and Jersey client application.

cURL based approach to create process instance

 

Create input.json file with the above recorded values in the following format.

 

{
  "processDefId":"default~Incident_Management!1.0~IncidentQualificationProcess",
  "serviceName":"IncidentQualificationProcess.service",
  "operation":"start",
  "payload":
  "<inc:start xmlns:inc=\"http://xmlns.oracle.com/bpmn/bpmnCloudProcess/Incident Management/IncidentQualificationProcess\">
  <inc1:IncidentProfile xmlns:inc1=\"http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile\">
    <inc1:incident_id>MAR0000110</inc1:incident_id>
    <inc1:user_type>PROSPECT</inc1:user_type>
    <inc1:firstname>William</inc1:firstname>
    <inc1:lastname>Scott</inc1:lastname>
    <inc1:email>william.scott@xyz.com</inc1:email>
    <inc1:phone_no>8105810510</inc1:phone_no>
    <inc1:occupation>IT Professional</inc1:occupation>
    <inc1:annual_income>4000.0</inc1:annual_income>
  </inc1:IncidentProfile>
  <inc1:IncidentProfile xmlns:inc1=\"http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile\">
    <inc1:incident_id>MAR0000110</inc1:incident_id>
    <inc1:user_type>SPOUSE</inc1:user_type>
    <inc1:firstname>Kate</inc1:firstname>
    <inc1:lastname>Janes</inc1:lastname>
    <inc1:email>kate.janes@xyz.com</inc1:email>
    <inc1:phone_no>8105810511</inc1:phone_no>
    <inc1:occupation>IT Professional</inc1:occupation>
    <inc1:annual_income>45000.0</inc1:annual_income>
  </inc1:IncidentProfile>
  </inc:start>"
}




 

Though the above representation has proper indentation, keep the version you prepare in compact form and do proper escape check. It should look like below.

 

{"processDefId":"default~Incident_Management!1.0~IncidentQualificationProcess","serviceName":"IncidentQualificationProcess.service","operation":"start","payload":"<inc:start xmlns:inc=\"http://xmlns.oracle.com/bpmn/bpmnCloudProcess/Incident Management/IncidentQualificationProcess\"><inc1:IncidentProfile xmlns:inc1=\"http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile\"><inc1:incident_id>MAR0000110</inc1:incident_id><inc1:user_type>PROSPECT</inc1:user_type><inc1:firstname>William</inc1:firstname><inc1:lastname>Scott</inc1:lastname><inc1:email>william.scott@xyz.com</inc1:email><inc1:phone_no>8105810510</inc1:phone_no><inc1:occupation>IT Professional</inc1:occupation><inc1:annual_income>4000.0</inc1:annual_income></inc1:IncidentProfile><inc1:IncidentProfile xmlns:inc1=\"http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile\"><inc1:incident_id>MAR0000110</inc1:incident_id><inc1:user_type>SPOUSE</inc1:user_type><inc1:firstname>Kate</inc1:firstname><inc1:lastname>Janes</inc1:lastname><inc1:email>kate.janes@xyz.com</inc1:email><inc1:phone_no>8105810511</inc1:phone_no><inc1:occupation>IT Professional</inc1:occupation><inc1:annual_income>45000.0</inc1:annual_income></inc1:IncidentProfile></inc:start>"}




 

Use the following example cURL command posts to create a process instance:

 

curl -u jstein:welcome1
-H "Content-Type:application/json"
-H "Accept:application/json"
-X POST
-d @input.json
 https://example.com/bpm/api/3.0/processes




 

You may use –k (or --insecure) option to bypass the certificate validation, if required.

 

Here, username and password to access Process Cloud Service are entered in plain text.

 

After firing this command, you can check the workspace to track the process instance.

 

The output of cURL command shows the process instance is created and in OPEN state.

 

{"levels":0,"links":[{"href":" https://example.com/bpm/api/3.0/processes/91","length":0,"rel":"self"},{"href":" https://example.com/bpm/api/3.0/processes /91/audit","length":0,"rel":"audit"}],"title":"Instance #91 of IncidentQualificationProcess","processId":"91","processDefId": "default/Incident_Management!1.0/IncidentQualificationProcess","processName":"IncidentQualificationProcess","priority":0,"owner":"IncidentManagement.ProcessOwner","creator":"siva.krishna@oracle.com","state":"OPEN"}




 

Jersey based approach to create process instance

 

Create a Java application in your favorite IDE and add below libraries to application’s classpath.

 

  • jersey-bundle-1.19.jar or higher version
  • Jackson-all-1.9.9.jar or higher version

 

In contrast to the cURL approach, you can choose Weblogic CSF to persist and retrieve the credentials of PCS. Otherwise, you can hard code the credentials in the code directly. The below code snippet highlights the payload construction and invoking the REST endpoint.

import com.sun.jersey.api.client.*;
.....
public class PCSRESTClient {
.....
    private String getAuthString() {
        String authString = username +":" +password;
        try {
            authString = DatatypeConverter.printBase64Binary(authString.getBytes("UTF-8"));
        } catch (UnsupportedEncodingException e) {
        }
        return authString;
    }


    public void invokeIncidentQualificationProcess(IncidentProfiles profiles) throws Exception {
        StringBuffer prospectPayload = new StringBuffer();
      prospectPayload.append("<IncidentProfile xmlns='http://xmlns.oracle.com/bpm/bpmobject/BusinessData/IncidentProfile'>");
      prospectPayload.append("<incident_id>101</incident_id>");
      prospectPayload.append("<firstname>Ryan</firstname>");
      prospectPayload.append("<lastname>Joseph</lastname>");
      .....
      prospectPayload.append("</IncidentProfile>");


        StringBuffer spousePayload = new StringBuffer();
      spousePayload.append("<IncidentProfile …………………………………………………>");
      .....
      spousePayload.append("</IncidentProfile>");


        StringBuffer payload = new StringBuffer();
        payload.append("{");
        payload.append("\"processDefId\":\"default~Incident_Management!1.0~IncidentQualificationProcess\",");
        payload.append("\"serviceName\":\"IncidentQualificationProcess.service\",");
        payload.append("\"operation\":\"start\",");
        payload.append("\"params\": {");
            payload.append("\"inputprospect\":\""+prospectPayload.toString()+"\",");
            payload.append("\"inputspouse\":\""+spousePayload.toString()+"\"");
        payload.append("}, \"action\":\"Submit\"");
        payload.append("}");


        MultiPart multiPart = new MultiPart().bodyPart(new BodyPart(payload.toString(), "application/json"));
        resource = client.resource("https://example.com/bpm/api/3.0/processes");
        ClientResponse res = resource.header("Authorization", "Basic " + getAuthString()).type("multipart/mixed").accept("application/json").post(ClientResponse.class, multiPart);
        if (res != null && res.getStatus() != 200) {
            throw new Exception (res.getStatusInfo().getReasonPhrase());
        }
    }
}




 

Note: To access an Oracle Process Cloud remote SSL based RESTful web service in your local development environment you have to configure your IDE with the RESTful SSL Service Certificate. For example, adding the Oracle Process Cloud SSL Certificate to the JDeveloper keystore.


For More Information

 

Please check this space frequently for more updates on this topic and refer below links for additional information.

  1. Complete PCS REST API Reference: https://docs.oracle.com/cloud/latest/process_gs/CPRRA/toc.htm
  2. Developing RESTful web service clients using Jersey library: https://docs.oracle.com/cd/E24329_01/web.1211/e24983/client.htm#RESTF143
  3. Jersey Client API documentation: https://jersey.java.net/documentation/latest/client.html

 

The views expressed in this post are my own and do not necessarily reflect the views of Oracle.