---

Ruben Rodriguez Santiago's article presents a use case that demonstrates how you can use Oracle Process Cloud Service, Mobile Cloud Service, and Mobile Application Framework can be used together to expose an Oracle PCS process instance as a web service and call it from an external system, web application, or mobile application.

---

by Ruben Rodriguez Santiago

Technology Context

Oracle Process Cloud Service
Oracle Process Cloud Service (PCS), a Platform as a Service (PaaS) provided by Oracle Cloud, allows you to rapidly design, automate, and manage business processes in the cloud.

Oracle Mobile Cloud Service
Oracle Mobile Cloud Service (MCS) is Oracle's Mobile Backend as a Service (MBaaS) and enables companies to create and deploy scalable, robust, and secure mobile applications quickly and easily.

Oracle Mobile Application Framework
Oracle Mobile Application Framework (Oracle MAF) is a hybrid mobile framework that provides a visual and declarative development experience for the rapid development of multi-platform applications.

Introduction

A common way to start an Oracle BPM (Business Process Management) process instance is by exposing it as a web service and calling it from an external system, web application, or mobile application. We can also achieve this in PCS, where start events are automatically exposed as SOAP web services. PCS instances can be also started using the provided REST API.

In terms of mobile development, the best practice is to consume REST/JSON web services in order to take advantage of performance benefits; using MCS is a good option. Apart from that, MCS provides analytics as well as many features that will increase development productivity.

This article will illustrate how Oracle MCS can be used as the mobile gateway for all Oracle PaaS products by explaining how to:

• Create a process in PCS whose instances can be started either by calling a SOAP web service or using the PCS Workspace
• Consume Oracle PCS REST API
• Consume Oracle PCS SOAP process web services from MCS and create a custom API that will be exposed as a REST service
• Create an Oracle MAF application and integrate it with an MCS instance where we will consume the created custom APIs

Use Case

A client requires the creation of a process in Oracle PCS. Instances of that process will be started using a form in a custom mobile application built on Oracle MAF and using Oracle PCS Workspace. To optimize the communication between the service process and the mobile client, MCS is used to transform SOAP requests into mobile-optimized REST/JSON calls.

To achieve this requirement, we will follow these steps:

1. Design and implement a process in PCS
2. Deploy the process
3. Overview of PCS REST API
4. Create a mobile backend in MCS
5. Create a connector in MCS
6. Create, design, and implement a custom API that calls the connector
7. Create a MAF application
8. Testing

Prerequisites

• Active PCS account
• Active MCS account
• Oracle JDeveloper 12.1.3
• Oracle MAF extension in JDeveloper (2.1.3+)
• Android/iOS/Windows 10 device or tester

Solution

Design and implement a process in Oracle PCS

Create an application

Before we design and implement the process we have to do a couple of things.

1. On the PCS home page, click Develop Processes:
   

   Figure 1

2. Click the Create button and create a new space. (A space is just a way to gather and share applications.)

3. Fill in the name of the space and click Create.

4. Next we have to create an application, so click the New Application button.

5. Fill in the form and click Create. Select the space you just created.

Your application has been created; the next step is to create the Register User process that we will start from our mobile application.

Create a process

As you can see, we can now create a process based on a predefined pattern by clicking one of the options that appears in the middle of the page.

1. Click Start with a form (see Figure 2, below). Web forms define the user interface that allows end users to interact with business processes. This will allow us to start the process instance with this web form and also from the mobile application (because it can be published as a SOAP web service).
   

   Figure 2

2. Fill in the name of the process. In this case, let's call it RegisterProcess.

3. To create the process, just click the Create button at the bottom right.
   

   Figure 3

We've created our process, but there are a couple more steps before we can design and implement the process itself.

Define business objects

1. Click Business Types in the left menu.

2. Click the + icon in the upper right of the page.
   

   Figure 4

3. In the pop-up, fill the name of the Business Object (in this case, UserBO) and click Next.

   Business Objects allow you to model and develop the business entities that are part of your process. You can use PCS Composer to create business objects manually, or you can base them on an XML Schema Definition (XSD).

   

   Figure 5

4. Now we add as many as attributes as we want. In this case, we'll add only four attributes (to keep things simple).
   

   Figure 6

Create the form

After creating the Business Objects, we have to create the form we'll use to start the instance:

1. Click on Web Forms on the left menu (see Figure 7, below).

2. Click the + icon in the upper right.
   

   Figure 7

3. Give a name to the form and click Create.

   The form is now created. But now we have to add the fields from the Business Object we just created so we can add Business Object attributes as form fields.

4. Click the icon indicated in Figure 8.
   

   Figure 8

5. Select the Business Object and click OK.
   

   Figure 9

   Now that we have associated the Business Object, we add its fields to the form.

6. Click the green button next to the Business Object name. The fields will be automatically added to the form.
   

   Figure 10

Implement the process

Now it's time to move into the process and define the flow.

1. Click on the Root Directory tab, then click RegisterProcess to open the process diagram.

2. To implement the form start event, click Start.

3. Click Implementation.
   

   Figure 11

   Now we need to associate the form we have just created with the Start activity.

4. Click the Search icon at the bottom of the page.

5. Click Register Form.

6. Give a title to the form. This is the title the user will see when the instance is created through the workspace.
   

   Figure 12

   We could now run the process as-is. But in order to show you how easy process development is in PCS, we’re going to make a couple of changes.

7. Right click on the screen and click Add Lane.
   

   Figure 13

   This will add a new lane to the process, where we will add another activity.After that, on the right hand side of the screen, we have a menu where we can drag and drop components (e.g., gateways, events or system activities) into the process diagram.

8. Drag and drop an Approve activity to the line that joins the Start and End events.

9. Move both Approve and End activities to the bottom lane.
   

   Figure 14

   At this point we already have our process done, but we have to validate it and publish it before we can deploy it and make it available.

10. Click the Validate button and then the Publish button, as indicated in Figure 15.

**![image015.png](https://objectstorage.us-phoenix-1.oraclecloud.com/p/BqK85Rn1zA5MP0vYiqbAdPgs7Z6OmMxw8SD3WCFVm5kY8uReidZ1KPIKkgJ1hCkG/n/axciphqpnohg/b/forums-legacy/o/uploads/jive_attachments/4/9/2/49247154egami.png)  
Figure 15**

Deploy the process

In PCS, deployment is easy. We have two options for navigating to the Manage Deployed Applications page.

1. Navigate to the home page and click the Deployed Applications link on the bottom left of the page.
   

   Figure 16

2. In the process editor, click the Management button.
   

   Figure 17

   On this page we can see a list of deployed applications. There’s a button that lets us take some actions on the application and also see the exposed and consumed services.

3. To deploy the application, click the Deploy link on the left-hand side.
   

   Figure 18

4. In the Deploy pop-up, select the space, the application, and the snapshot to be published.

   In the next step, we review the deployment; in the last step we will configure the revision id of the application (in this case, this is revision 1.0).

   This last step is the same that we find when deploying a BPM process in a WebLogic Server; apart from the revision, we can set the revision as default revision and also override an existing revision.

   Now that we have the application successfully deployed, we need to know the WSDL that we are going to use to make the call to start the instance.

5. Click the button on the application row in the table and select the Web Services menu option.

   In the exposed web services we can see a WSDL. Copy that URL, and we are ready to move to Oracle MCS.

   

   Figure 19

Overview of Process Cloud Service REST API

As mentioned at the beginning of the article, Oracle PCS also provides a REST API. We can manage, for example, processes, tasks and analytics.

I am going to make an example call to start an instance of the process we have just created.

The URL structure we are going to use in this example is:

[https://example.com/bpm/api/3.0/processes](https://example.com/bpm/api/3.0/processes)

• example.com is the host of your instance
• /bpm/api/3.0/ is the fixed prefix for the REST resources
• processes is the resource

We have to make a POST call and set a request body as shown below (we can get the values of the parameters that we need by invoking a GET call to /process-definitions resource):

Figure 20

As you can see in the image, payload parameter is a string with business object data in XML format.

[code}

<payload>

  \<formArg>

     \<user:UserBO xmlns:user=\\"[http://xmlns.oracle.com/bpm/bpmobject/BusinessData/UserBO](http://xmlns.oracle.com/bpm/bpmobject/BusinessData/UserBO)\\">

        \<user:firstName>Ruben\</user:firstName>

        \<user:lastName>Rodriguez\</user:lastName>

        \<user:email>[rest.test@avanttic.com](mailto:rest.test@avanttic.com)\</user:email>

        \<user:country>Spain\</user:country>

     \</user:UserBO>

  \</formArg>

</payload>

[/code]

After setting the request body parameters, we can execute it.

Figure 21

You can check all the available APIs in this link: REST API for Oracle Process Cloud Service.

Create a Mobile Backend (MBE) in MCS

A Mobile Backend (MBE) is the gateway through which we will make all the calls to any Oracle MCS Platform API or Custom API. So the first step is to create an MBE.

1. In Oracle MCS Portal, navigate to Mobile Backends.
   

   Figure 22

2. Click the New Mobile Backend button.

3. Fill in the name of the Mobile Backend and click Create.

   As soon as we finish step 3, the Mobile Backend settings page will be displayed. On this page we can see information such as Base URL, Mobile Backend ID, Anonymous Key and the Application Keys. We are going to use them at the end of this article, when we head to JDeveloper and start coding the MAF Application.

Create a connector in MCS

Oracle MCS provides an option to register SOAP and REST services as a named connector configuration. The connector provides an abstraction that allows developers to apply changes to the service configuration without impacting custom code accessing the service. In this case, we are going to create a SOAP connector because Oracle PCS processes are published as SOAP web services.

1. In the MCS Portal, navigate to Connectors.

2. On the Connectors page, click New Connector. For type, choose SOAP.

3. In the pop-up that appears, provide the WSDL endpoint URL that we got after the deployment in PCS, the API name, and the API description.
   

   Figure 23

   Now the SOAP connector is created—but we need to configure a couple of things before moving to create the Custom API.

4. In the Security train stop of the connector configuration, add oracle/http_basic_auth_over_ssl_client_policy to selected policies. We must select an existing API key or create a new one by clicking on the keys in the csf-key field. This will allow us to automatically send HTTP basic credentials in the web service call.
   

   Figure 24

Apart from these security settings, in the SOAP connector configuration wizard we'll find train stops that will allow us to:

• General stop: Configure service connection settings such as HTTP Read Timeout and HTTP Connection Timeout.
• Port stop: Modify the endpoint and provide alternate names for all the web service operations.
• Test stop: We can use the test client to test the web service call. In test stop, you can see that, although the web service you are trying to call is a SOAP/XML service, you are going to use REST/JSON thanks to the MCS translator that automatically transforms a SOAP/XML to REST/JSON.

Figure 25

The automated SOAP to JSON translation has documented limitations that developers need to consider.

Known limitations are:

• Choice groups with child elements belonging to different namespaces having the same (local) name. JSON does not support namespaces.

• Sequence groups with child elements having duplicate local names

  For example: <Parent><ChildA/><ChildB/>...<ChildA/>...</Parent>

  This translates to an object with duplicate property names, which is not valid in JSON.

• XML Schema Instance (xsi) attributes

Figure 26 illustrate an example of a payload that the translator will not be able to convert into JSON.

Figure 26

The translator does not add the header namespaces to the XML it produces.

In this case, you will still be able to call the web service by circumventing the translator; you just have to use an XML payload and set content-type":"application/xml;charset=UTF-8 and accept":"application/xml as header parameters.

By clicking on Test Endpoint, we can test if the process instance is started when the web service operation is executed. We need to select an MBE and a version.

We need some information about the connector in order to call it from the custom API:

• Connector uri: /mobile/connector/PcsStart_rrs
• Web service method: start

Create, Design and Implement a Custom API that Calls the Connector

Create an API

The last step in MCS is to create a Custom API that will make the call to the connector we have just created. Custom APIs are exposed as REST resources and implemented using Node.js. You use custom APIs to implement the business logic for a MBE.

1. In the MCS Portal, navigate to APIs.

2. On the APIs page, click the New API button.

3. In the pop-up that appears, select an existing RAML document or start to build your API from scratch by filling in the API Name, API Display Name and API Description.
   

   Figure 27

Define the API

Now that we have created the API, we have to start defining it.

1. Navigate to the Security tab.

2. Click the Allow Anonymous User Access button.
   

   Figure 28

   Doing this we don't have to manage users and configure roles. To make the call to the Custom API from our MAF application, we’ll use the Mobile Backend Anonymous Key.

   After we have modified the security, we start defining the structure of our API.

3. Go to the Endpoints tab.

4. Click the New Resource button.

5. Set a Resource Path, in this case pcsregister.

6. Click the Methods link on the right side of the resource to create the HTTP methods that we are going to use in our API.

   
   Figure 29

7. Click the Add Method button.

8. Select POST.

After the method is created, we can set custom response payloads; for example, when a 200 code is sent, the custom message “Process Instance has been successfully started” will also be sent by the API. This is useful when multiple developers are working on the project. While a service developer implements the API, a mobile application developer can consume this API and get the example responses.

Figure 30

We must add a new media type in the request body so our API will accept a JSON body. We can also add an example request, as seen in the image below:

Figure 31

The sample JSON allows you to run the custom API with mockup data. This allows parallel development of the mobile client application and the business logic in MCS.

Implement the API

After the API REST endpoints are defined, we have to implement the logic of our API using node.js.

1. Click the Implementations option on the left (see Figure 31).

2. Click the JavaScript Scaffold button to download the files to implement the API.

   The name of the zip file we have just downloaded matches the name of the API, followed by an underscore and the API’s version number. In this case, the name is: pcsapi_rrs_1.0.zip.

   It also contains a few files:

   

   Figure 32

   Now it is time to modify the files we have just downloaded.

   • package.json: Information relative to the project and where, for example, dependencies are managed.
   • pcsapi_rrs.js: Implementation file. If we open it, we can see that skeleton methods have been created for each endpoint and the methods that we defined for this API in MCS.

3. In package.json we must add the connector we want to call as a dependency.

   
   Figure 33

   The URI we have to add can be found in general step in connectors settings in MCS.

   
   Figure 34

4. Now we must implement our API, so we make the call to the connector.

   
   Figure 35

   Line 5: First we set connector uri in optionList object. As you can see, you have to use connector uri and the name of the method you are going to call.

   Line 7-24: We also have to build a JSON object using some values of the request we have received, using req.body[‘myKey’].

   Line 25: We add the header content-type parameter and set it to application/json.

   Line 27-36: The last thing is to execute a POST call and evaluate whether it returns an error. If it does, we will send the client the returned http code and a custom JSON with the error message. If everything is correct, we will send a 200 http code and JSON with a success message.

   Implementation is now completed. Now we put both files we have modified into the zip file we previously downloaded and upload it to MCS.

The last step in MCS is to select the API we have just created in the mobile backend.

Figure 36

Create a MAF application

The last step in this integration is to create a MAF application that accesses the custom API exposed on the MCS mobile backend. Access is simplified by using the Oracle MAF MCS Utility (mafmcsutility.jar). In MCS, client SDKs exist for Android, iOS, Windows, JavaScript and Xamarin. The MAF MCS Utility is not an official SDK, but provides similar functionality for MAF application developers.

Integrate MAF MCS Utility

Before creating the application, we'll get everything we need to integrate MCS. We can get mafmcsutility.jar in MAF public samples (e.g., C:\Oracle\Middleware\Oracle_Home\jdeveloper\jdev\extensions\oracle.maf\Samples) or download it from:

https://blogs.oracle.com/mobile/entry/maf_mcs_utility_patch_for

After we have the library, we are ready to start building the application:

1. To create the application, click File -> New -> Application.

2. In the gallery, select Mobile Application Framework Application and click OK. In the next popup, choose the location where you want to place the application and the name of the application. After setting those values, click Finish.

3. Add mafmcsutility.jar to the ApplicationController project by going to the Libraries and Classpath menu in Project Properties.

   
   Figure 37

Create a REST Connection

We also have to provide a REST Connection in this method:

1. In the Application Navigator, go to Application Resources.

2. Right click on Connections node.

3. Search for REST Connection.

   In the Edit REST Connection dialog, fill the form with the connection name (in this case, MCS) and with the base URL of the mobile backend that we get in MCS.

   **
   **

   Figure 38

Create the DataControl

1. Create a Java class called MCSDataControl.java. We are going to add some methods from the sample application provided for the MAF MCS Utility.

   • prepareMCSAccess: This method creates a mobile backend object that represents a mobile backend in MCS. Provide the following information about the mobile backend in MCS:

     • Mobile Backend Id

     • Anonymous key

     • Application key

     • The REST connection we have just created (marked in red, below)

       

       Figure 39

   • anonymousLogin: as we set the API to allow anonymous login, we must call this method.
     

        **Figure 40**
     

   • invokeCustomMcsAPI: this method uses a Custom API Service Proxy to execute our custom API
     

       **Figure 41**
     

As we are going to display a pop-up with the result of the API call, we’ll need a couple of methods from this blog post.

• registerUser: We are going to call this method from our page as this will be the only method exposed in the DataControl. This method has four parameters, and those are the values we have to send to the API so we also have to build the JSON.

  We have to get the API URI from MCS and provide it while calling invokeCustoMcsAPI method.

  **
  **

  Figure 42

• In the Application navigator, right click on MCSDataControl class and click Create Data Control.

Create the User Interface

Now we just have to create the user interface and call the method we have just created.

1. In maf-feature.xml file we'll create a new UI. I have called it Register.

2. After the feature is registered we must create a new AMX Page under the Content tab.

3. We also have to add popupUtils.js under Includesand set it as JavaScript type.

   
   Figure 43

   A new file, RegisterForm.amx, has been created.

4. From the Data Controls palette, drag and drop the registerUser method under MCSDataControl to the page and select MAF Parameter Form. This will create four inputText items, one for each parameter of the method, and the button that will call the action.

   Because we are displaying a pop-up, we have to add two hidden buttons, as stated in this blog post.

   
   Figure 44

Testing

To test what we have built, we have to deploy the MAF Application.

In JDeveloper, click Application and move the mouse to Deploy. Choose where to deploy the application (iOS/Android emulator, device or package). In this case, I am going to deploy to an Android emulator. (The emulator has to be running before we try to deploy or the deployment will fail.)

Figure 45

Once the application has started, fill the form's values and click Register at the top right of the screen.

**
**

Figure 46

After MCS Custom API has been called, a pop-up will appear with the message.

**
**

Figure 47

We can check in MCS Analytics and see that a call has been made.

**
**

Figure 48

Lastly, we can see in PCS that the instance has been started and is now in Approval status.

**
**

Figure 49

If we open the form, we can see that the values are those that we sent from our application.

**
**

Figure 50

Conclusion

As this article has demonstrated, Oracle Process Cloud Service allows us to quickly and easily build business processes and expose their interfaces as SOAP web services, or we can interact with Oracle PCS using its REST API.

Thanks to Oracle Mobile Cloud Service, in addition to features such as Analytics, Storage, and Notifications, we can also integrate any cloud or on-demand system using connectors and expose them as REST services, improving the performance of mobile applications.

And with Oracle Mobile Application Framework we can quickly build cross-platform (Android, iOS and Windows 10 in the future) mobile applications with single-code development.

About the Author

Rubén Rodríguez has been working with Oracle products since getting his degree in Computer Science. Rubén is ADF Technical Lead and Cloud Specialist in a Spanish Platinum Partner, avanttic where he is focusing on Oracle PaaS and Oracle Application Development Tools and Frameworks. A regular contributor to community.oracle.com, Rubén also maintains separate blogs in Spanish and English.

---

This article has been reviewed by the relevant Oracle product team and found to be in compliance with standards and practices for the use of Oracle products.

---