PCS, MCS and MAF Integration [Tech Article]

Version 9

    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:
      image001.png

      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).
      image002.png

      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.
      image003.png

      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.
      image004.png

      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).

      image005.png

      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).
      image006.png

      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.
      image007.png

      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.
      image008.png

      Figure 8

    5. Select the Business Object and click OK.
      image009.png

      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.
      image010.png

      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.
      image011.png

      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.
      image012.png

      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.
      image013.png

      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.
      image014.png

      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
      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.
      image016.png

      Figure 16

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

      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.
      image018.png

      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.

      image019.png

      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

     

    • 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):

    image020.jpg

    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\">
                <user:firstName>Ruben</user:firstName>
                <user:lastName>Rodriguez</user:lastName>
                <user:email>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.

    image021.jpg

    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.
      image022.png

      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.
      image023.png

      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.
      image024.png

      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.

    image025.png

    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.

      image026.png

      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.
                image027.png

                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.
                image028.png

                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.

                image029.png
                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.

              image030.png
              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:

              image031.png

              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:

                image032.png

                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.

                image033.png
                Figure 33

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

                image034.png
                Figure 34

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

                image035.png
                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.

                image036.png

                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.

                            image037.png
                            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.

                            image038.png

                            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)
                                        

                                image039.png       

                                Figure 39

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

                                     Figure 40

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

                                    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.

                            image042.png

                            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.

                            image043.png
                            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.

                            image044.png
                            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.)

                          image045.jpg

                          Figure 45

                             

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

                              image046.png

                              Figure 46

                                 

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

                                  image047.jpg

                                  Figure 47

                                     

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

                                      image048.png

                                      Figure 48

                                         

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

                                          image049.png

                                          Figure 49

                                             

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

                                              image050.png

                                              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.