Skip navigation

Developer Solutions

May 2016 Previous month Next month

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.


    "payload":"<payload><formArg><p0:WebForm1 xmlns:p0=\"\"/></formArg></payload>", 


    "params": {
                  "argument3":"<MyBO1 xmlns=''><a1>SG</a1><a2>true</a2></MyBO1>"


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


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


{"levels":0,"links":[{"href":"", "length":0, "rel":"self"}],
  "application":"default", "revision":"1.0", "domain":"default",
{"name":"inputprospect", "type":"{}IncidentProfile", "location":"!1.0*soa_834cdc34-f2fd-4c1c-a9b6-a1843f663689/businessCatalog/BusinessData/IncidentProfile.xsd", "primitive":false
{"name":"inputspouse",      "type":"{}IncidentProfile", "location":"!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.


  "<inc:start xmlns:inc=\" Management/IncidentQualificationProcess\">
  <inc1:IncidentProfile xmlns:inc1=\"\">
    <inc1:occupation>IT Professional</inc1:occupation>
  <inc1:IncidentProfile xmlns:inc1=\"\">
    <inc1:occupation>IT Professional</inc1:occupation>


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=\" Management/IncidentQualificationProcess\"><inc1:IncidentProfile xmlns:inc1=\"\"><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></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=\"\"><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></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"
-d @input.json


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":"","length":0,"rel":"self"},{"href":" /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":"","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=''>");

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

        StringBuffer payload = new StringBuffer();
        payload.append("\"params\": {");
        payload.append("}, \"action\":\"Submit\"");

        MultiPart multiPart = new MultiPart().bodyPart(new BodyPart(payload.toString(), "application/json"));
        resource = client.resource("");
        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:
  2. Developing RESTful web service clients using Jersey library:
  3. Jersey Client API documentation:


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

Tired with SSLHandshake exception when accessing a HTTPS URL from your application deployed in JCS-SX and wondering what is going wrong and how to fix it. Read on, this blogpost will explain this.


Let's first understand what's happening - In layman's term -


When the application which is deployed in JCS-SX tries to connect to any URL over HTTPS, Server sends its certificate (public key) to the client i.e JCS-SX and  client must authenticate this certificate by checking it against the list of trusted certificate. JCS-SX maintains the list of certificates which it trusts in the store called trustStore.


If you want to try what is explained below, you need to have JCS-SX SDK.

Do not have SDK, follow this link -


Check for the available trusted certificate in this store - To check for the existing certificates which are trusted by default by your JCS-SX env, use below command


javacloud -dc <data-center> -identitydomain <id-domain-name> -serviceinstance <instance-name> -user <user-name> -password <password>  -httpproxy <proxy-server:proxy-port> -list-ssl-certificates


This command will list all trusted certificates in the format below ---


S.NO        - <S.NO>

Alias       - <Alias - Name>

Expired     - <Expiry status>

Expiring in - <Time for expiry in format - 4 years, 236 days, 14 hours, 54 minutes and 7 seconds>


When you see SSLHandshake exception, your server's certificate does not exist in JCS-SX truststore and hence it is not able to validate it. Here is how you can add it in JCS-SX using below command


javacloud -dc <data-center> -identitydomain <id-domain-name> -serviceinstance <instance-name> -user <user-name> -password <password>  -httpproxy <proxy-server:proxy-port> -add-ssl-certificates -path <path to certificate file>


Response will be like below.

[INFO]    - 1 certificate(s) added.


You can check via list-ssl-certificates command for your certificate availability in JCS-SX truststore.



If you want to revoke trust to specific server's certificate, delete its certificate from the truststore using below command -


javacloud -dc <data-center> -identitydomain <id-domain-name> -serviceinstance <instance-name> -user <user-name> -password <password>  -httpproxy <proxy-server:proxy-port> -delete-ssl-certificates -alias <alias-name>

Response will be -

Alias <alias-name> deleted.

If you messed up with your truststore and not sure how to get it right again, JCS-SX comes to your rescue and provide the reset command which you can use to reset the truststore to the default value. Please be aware that it will remove all certificates added and trusted by you.


javacloud -dc <data-center> -identitydomain <id-domain-name> -serviceinstance <instance-name> -user <user-name> -password <password>  -httpproxy <proxy-server:proxy-port> -reset-ssl-certificate-store


Response will be like below -

This will undo all the certificate management operations you have performed.

Are you sure you want to reset SSL trust-store?(yes/no):yes

[INFO]    - The SSL certificate store is reset.


You can download the complete truststore or specific certificates into your local m/c by download-ssl-certificates command as -


javacloud -dc <data-center> -identitydomain <id-domain-name> -serviceinstance <instance-name> -user <user-name> -password <password>  -httpproxy <proxy-server:proxy-port> -download-ssl-certificates -output <output-dir>


Response will be like below -

[INFO]    - 76 certificates downloaded.

[INFO]    - Downloaded at: <output-dir>


Please note that downloaded jks file does not have any password.


Hope this blogpost will help you configuring and trouble-shooting SSL trust specific issues. Enjoy the Cloud Infra


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

Want to get started with Oracle JavaScript Extension Toolkit (JET) Hybrid Application Development but not sure what you need to know first? I will cover here what the tools/frameworks you need to get up and running  and resolving common issues faced while developing your first JET based hybrid app.  Oracle JavaScript Extension Toolkit (JET) provides a seamless hybrid mobile development experience that any organization can leverage to create simple, secure and visual mobile applications.; this link is the best place to get started.


This blog is divided in three parts:

  • Development Machine Setup
  • Creating a JET Mobile App
  • Troubleshooting common issues


Part-I: Development Machine Setup

Here are the main frameworks/tools that need to be setup in the machine to get started. For more detailed documentation, please see the following link. Prerequisites for Developing Applications with Oracle JET




Usage in Oracle JET



Used as package manager for development tools


Package manager for web site components that can contain HTML, CSS, JavaScript, fonts, and image files


Open source tool used to scaffold web or hybrid applications


Used for Building and serving


Cross-platform development targeted to multiple platforms with one code base


SDK for android and iOS

Android and iOS SDK page


Install Node.js

node --version

Node Proxy Setup

Node takes config settings to set the proxy server for http and https. Copy and paste these commands into a shell to execute.

npm config set proxy

npm config set https-proxy


After installing node.js , user  has to use node package manager (npm command) to install the below tools (in any given order)


Install Bower

npm install -g bower

Bower Proxy Configuration

Bower requires a file named .bowerrc in your home directory.

  • Create a file called .bowerrc with the following JSON text.  Bower reads this file to obtain its proxy information.

{ "proxy":"", "https-proxy":"" }

  • Create the .bowerrc file in the %HOME% directory


Install Yeoman and Grunt

npm install -g yo

npm install -g grunt-cli

Yeoman uses the environment variables HTTP_PROXY and HTTPS_PROXY for proxy settings, so nothing additional needs to be done. Verify whether the installation is completed by running the commands to check the versions:

yo --version

grunt --version

Install Cordova

npm install -g cordova

Verify installation by running this command:

cordova --version

Install Android SDK


For installing the Android SDK refer to the following link.  Alternatively you could also download Android studio and update it’s SDK and tools to latest

Part-II: Create a JET Mobile App

Scaffold a Mobile Application

yo oraclejet:hybrid --appName=JETMobileDemo --template=navBar --platforms=android


grunt build:dev --platform=android  (By default it will assume emulator)


grunt serve --platform=android (By default, it will assume emulator)

Part-III: Troubleshooting

Here are some tips to resolve the common issues encountered when deploying your first hybrid application:

Issue 1: Grunt build or Grunt serve command getting stuck or failing

If you are building or installing your application for the first time, especially behind corporate firewalls, you may face issues of build getting failed.


Possible Resolution:

This particular problem may arise in case you are behind corporate firewall and there is some proxy setting that's not correct or proxy itself not set. Please set (or check if already set) your npm and bower proxy settings as mentioned in the above section.


Issue 2: Not able to launch Hybrid mobile app in emulator

There may be a possibility that you are able to build and launch your hybrid mobile application in your Android device, but not able to launch the same application on Android emulator

For instance, you may receive the following logs on your console and they keep on waiting:

Running "serve" task

Running "customServe" task

Invoking cordova serve

Static file server running on: http://localhost:8090 (CTRL + C to shut down)Invoking cordova run

Starting watch

Running "watch" task

  1. Waiting...


Possible Resolution:

Generally when we issue the grunt serve without starting the emulator, grunt will try to start the emulator and any commands that grunt issues might not work as emulator is still booting up.

So in order to avoid this issue:

  • Please start the emulator first!
  • Don't specify the destination parameter for grunt serve (it will deploy to the open/default emulator)
  • Then grunt serve to install the app on your emulator
  • Ensure  grunt build before the grunt serve

Issue 3: Running into CORS issue while debugging

There may be possibility that user is not able to interact with any mobile middleware , .e.g. Oracle Mobile Cloud Service (MCS), e.g like performing authentication while using emulator/web and live debugging (enabled to true by default).


Possible Resolution:

While running on an emulator, please disable the live reload feature otherwise a CORS error will happen when interacting with MCS.

Use the --disableLiveReload feature during grunt serve command

grunt serve --platform=android  --disableLiveReload=true

Issue 4: LiveReload not working on device, alternatives for troubleshooting

Unfortunately when you serve to device, livereload won't work due to a known bug.

Alternate Resolution:

The recommended process is to first develop the app contents within browser using the --web=true flag.  This will lead to faster reloading and faster serve.

grunt serve --platform=android –web=true


Next, then use livereload in emulator (though much slower in Android native emulator).

grunt serve --platform=android (By default, it will install on emulator)

Then at the very last, you can serve your app to device.

grunt serve --platform=android --destination=device --disableLiveReload=true


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


Oracle Sales Cloud provides web services as one of many mechanisms to integrate with and extend Sales Cloud in Oracle Applications Cloud Services. The web services are typically based on business objects and allow the caller to perform operations on the business objects. As an example, the Account Service can be used to perform a find operation to identify accounts meeting a search criterion or to perform an update to a field, like address on a particular account. These web services can be accessed by custom applications deployed on Oracle PaaS (Platform As A Service) like Java Cloud Service - SaaS Extension (JCS-SX) and access data residing in Sales Cloud.

Oracle SaaS (Software As A Service) extensions also enables Sales Cloud to call a web service deployed in Oracle PaaS and thereby utilizing the capabilities built into the custom applications.

Oracle PaaS

Oracle PaaS (JCS-SX in particular) enables customers and partners to extend their Oracle SaaS applications and provide custom functionality to address their specific business needs.

Oracle SaaS comes with tools that allow you to customize and extend the applications. These tools can be used to add new UI elements, add validations, enrich data model, and to create interfaces with external applications.

Customizations/extensions for SaaS applications can be built by utilizing the capabilities offered by the PaaS platform.

This blog focuses on the options available for web service authentication to integrate Oracle Sales cloud with Oracle PaaS (JCS-SX)

Service Association between Oracle Sales Cloud and JCS-SX

Pre-wired security

Oracle Sales Cloud and PaaS instances in the same identity domain (such as JCS - SX) are automatically enabled for SSO capability, with Oracle Sales Cloud acting as the identity provider.

Oracle Sales Cloud and JCS - SX instances in the same identity domain can be associated. Association enables SAML-based identity propagation for Oracle Sales Cloud and JCS - SX web service interactions. Please refer to Security Strategies for JCS-SX and Sales Cloud interactions for more information on authentication and authorization options for interactions between JCS-SX and Oracle Sales Cloud.


Types of Authentication

Authentication of web service requests between associated services is provided by the Oracle Web Services Manager (OWSM) framework. The following mechanisms can be used for authenticating user identity between the service calls:

Username Token (UNT)

The username token authentication is the simplest of the authentication techniques and supported by most of third party clients

  • Client needs to send the username and password to the web service
  • Useful when a client needs to connect to a web service with an identifier that is different from the actual user name
  • Password must be made available to the client in the credential store


Security Assertion Markup Language (SAML) Token

Client needs to send a SAML assertion that contains the user name to the service provider.

  • Client constructs the SAML assertion, server needs to be set up to trust the client
  • Useful for identity propagation where a particular user has already authenticated to the client, and the client needs to propagate this user to the Web service, without having to know user's password
  • Should not be used when the clients are completely outside the domain (ex: end user’s desktop)


JSON Web Token (JWT)

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

  • Because of its size, it can be sent through an URL, POST parameter, or inside an HTTP header. Additionally, due to its size its transmission is fast.
  • The payload contains all the required information about the user, to avoid querying the database more than once.
  • JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA

Invoke Oracle Sales Cloud Web Services from JCS-SX


When JCS - SX invokes Oracle Sales Cloud web services, associated services have the SAML trust pre-established by Oracle. Oracle Sales Cloud can use UNT, SAML or JWT for authentication and authorization with the JCS - SX application.

Configuring Service Client

Assuming that SalesPartyService is a web service proxy used for invoking the Sales Party web service defined in Oracle Sales Cloud, the following code snippet illustrates the security policy configurations required on the client side using UNT and SAML respectively.


SecurityPolicyFeature[] securityFeatures =  new SecurityPolicyFeature[] { new SecurityPolicyFeature("oracle/wss_username_token_over_ssl_client_policy") };

salesPartyService_Service = new SalesPartyService_Service();

SalesPartyService salesPartyService = salesPartyService_Service.getSalesPartyServiceSoapHttpPort(securityFeatures);

//Using wss_username_token_over_ssl_client_policy, provide the username/password

WSBindingProvider wsbp = (WSBindingProvider)salesPartyService;  

       wsbp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY,"your_sales_cloud_user_name"); wsbp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY,"your_sales_cloud_password");

FindSalesParty fSalesParty = new FindSalesParty();


  try {

            SalesParties = salesPartyService.findSalesParty(fSalesParty).getResult();

  } catch (Exception e) { e.printStackTrace();}


Note: The above code snippet specifies user name and password in clear text for simplicity. Use Oracle Credential Store Framework (CSF) to ensure secure management of credentials.


    SecurityPolicyFeature[] securityFeatures = new SecurityPolicyFeature[] { new

    SecurityPolicyFeature("oracle/wss_saml_token_bearer_over_ssl_client_policy") };

    salesPartyService_Service = new SalesPartyService_Service();

    SalesPartyService salesPartyService =   salesPartyService_Service.getSalesPartyServiceSoapHttpPort(securityFeatures);

    FindSalesParty fSalesParty = new FindSalesParty();


    try {          

           SalesParties = salesPartyService.findSalesParty(fSalesParty).getResult();

    } catch (Exception e) {

            e.printStackTrace(); }



The following code snippet assumes that AccountService_Service is a web service proxy used for invoking the Account web service defined in Oracle Sales Cloud and illustrate the security policy configurations required to pass a JWT token obtained from a JSF page in the request HTTP header when making the web service call. Please refer to Using JSON Web Token for Oracle Sales Cloud Mashups for more details on using JWT in Sales Cloud.


   SecurityPolicyFeature[] secFeatures = new SecurityPolicyFeature[] {new SecurityPolicyFeature("")};

   service_Service = new AccountService_Service();

   service = service_Service.getAccountServiceSoapHttpPort(secFeatures);

   String jwt = JSFUtils.resolveExpressionAsString("#{pageFlowScope.jwt}");

  // add JWT auth map to HTTP header

   BindingProvider bp = (BindingProvider)service;

   Map<String,List<String>> authMap=new HashMap<String,List<String>>();

   List<String> authZlist=new ArrayList<String>();

   authZlist.add(new StringBuilder().append("Bearer ").append(jwt).toString());

   authMap.put("Authorization",authZlist) ;



Invoke Web Service deployed in JCS-SX from Oracle Sales Cloud

There could be scenarios where SaaS applications would want to leverage the functions/capabilities provided by web services deployed on JCS-SX. Using the application composer function of Sales Cloud, a reference to the web service can be created as follows:

Click on “Application Composer”, click on “Web Services” link under “Common Setup” on the left pane and click on the “Create a new web service reference” icon and provide the required details:

  • Name: <WSSoapEndpoint_Name>
  • WSDL URL: <JCS-SX_WSDL_URL> (the WSDL endpoint obtained after the deployment in JCS-SX)
  • Security Policy: Select “Invoke with current user credentials using SAML”.

  Security policy can be configured in Oracle Sales Cloud when creating the web service reference enabling secured web service invocation as depicted below:

SOAP Connection.png


In cases where user identities or services are not in the same identity domain, only UNT or HTTP Basic authentication strategies are possible. Please refer to Consuming SOAP Web Services in Oracle Sales Cloud for more details.



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