MAF 2.1 - Debugger Improvements and Mobile REST Client

I was blogging previously about Oracle Mobile Suite and REST service transformation from ADF BC SOAP service. Today I'm going to blog the next step in the same series - MAF client consuming REST service exposed from Oracle Mobile Suite ESB. I'm going to highlight improvements in debugging process for MAF, provided with the latest 2.1 release. I had couple of challenges implementing and mapping programmatic MAF client for REST service, all these were solved and I would like to share the solution with you.

Previous posts on the same topic:

- Oracle Mobile Suite Service Bus REST and ADF BC SOAP

- How To Add New Operation in Oracle Mobile Suite Service Bus REST Service

Here you can download sample application implemented for today post (contains ADF BC SOAP, Mobile Suite Service Bus and MAF client apps) - MobileServiceBusApp_v3.zip.

High level view of the implemented use case - there are three parts. Service Bus is acting as a proxy to transform ADF BC SOAP service to light REST consumed by mobile REST client (implemented in MAF):

I would not recommend to use auto generated Data Control for REST service - I didn't had positive experience using it. You should invoke REST service from Java, using MAF helper classes (read - here). There must be REST connection defined and tested, later it can be accessed and used directly from Java. REST connection endpoint must include REST service URL (in my case, it by default points to getEmployeesListAll operation):

It is enough to define REST connection, now we can start using it.

Sample application implements REST helper class. Here actual REST call is made through MAF RestServiceAdapter class - see invokeRestService method. Public method invokeFind(requestURI) is supposed to be used to initiate search request. Content type is set to be JSON. Search parameter is always passed as a part of requestURI, therefore we are passing empty post data value:

MAF application contains Java class - ServiceHelper, this class is used to implement Data Control. Each time when search parameter is set, applyFilter method is invoked and it makes REST request. Response is received and with the help of MAF utility (highlighted) is transformed from String to the array of objects:

ServiceHelper class includes a set of variables required to perform successful REST request. Data collection object - employees of type EmployeeBO[] is defined here and later exposed through Data Control:

As you can see from above example of applyFilter method - response String is transformed to the array of objects. I'm using EmployeesList class for conversion. This class contains array of objects to parse from REST response. It is very important to have exactly the same name for array variable as your REST response result set name. In my example, this name is employees:

Finally there is class to represent response object - EmployeeBO. This class is a POJO with attribute definitions:

ServiceHelper class is exposed to Data Control - defined methods will be accessible from MAF bindings layer:

This is all about REST client in MAF implementation - I would say quite straightforward, when you are on the right path.

Let's have a few words about debugger in MAF 2.1. I would say I was positively impressed with debugger improvements. There is no need to do any extra configuration steps anymore, simply right click anywhere in Java class you are currently working on and choose Debug option - Debugger will start automatically and MAF application will be loaded in iOS simulator.

It works with all defaults, you could go and double check the settings in Run/Debug section of MAF project - Mobile Run Configuration window:

Right click and choose debug, don't forget to set a breakpoint:

Type any value to search in the sample MAF application - Employees form. You should see breakpoint is activated in JDEV (as it calls applyFilter method):

Debugger displays value we are searching for:

After conversion from response String to array of objects happens, we could inspect the collection and check if conversion happened correctly:

Response from REST is successfully displayed in MAF UI:

How To Add New Operation in Oracle Mobile Suite Service Bus REST Service

I will use sample app from my previous blog post as the basis - Oracle Mobile Suite Service Bus REST and ADF BC SOAP. I was describing there the main steps in defining transformation from SOAP WS based on ADF BC to the REST WS interface. I will dive a little bit deeper into the same topic and will explain how to add new operation to the REST WS interface.

Here you can download updated sample application - MobileServiceBusApp_v2.zip. In order to add new operation to the REST interface, you should choose Edit REST option for REST Proxy Service in JDEV Service Bus project:

REST Binding editor will appear. Here you should define new resource - I will add /employees to return the list of all employees. New operation should be defined for resource path - /employees, operation getEmployeesListAll in my case:

You can give any meaningful name for the operation. Make sure to select correct resource path and use GET (if you want to fetch data, not update or delete). I'm getting the list of all employees, this means there will be no parameters in this case:

In the response specification tab for the getEmployeesListAll operation, make sure select JSON as the payload. You could use the option to generate sample payload - this shows what kind of result set will be constructed (based on the response XSD - HRRestProxy.xsd, I have created it in the previous post mentioned above):

Once new operation is defined in the REST wizard, we can add it to the mapping. Simply you could copy existing operation mapping to the newly created operation branch. Select new branch and provide required operation name - getEmployeesListAll in this case:

We need to edit request action first and specify empty payload - we want to fetch the list of all employees. For this we could reuse existing transformation file (REST to SOAP):

Important to remember - transformation file is created as a XQuery Map module, where you need to specify source and target types (this will allow to transform REST to SOAP and vice versa):

Request action contains empty value binding - REST variable will be initialised as empty, this will allow to use getEmployeesListAll operation with /employees path:

For response action I'm reusing the same transformation as in getEmployeeList operation - response will be parsed in the same way, using the same binding:

This is how it works - the list of all employees is fetched with /employees path (testing using Postman extension available in Google Chrome):

Previously implemented operation works as well, user could search by First Name/Last Name:

Reading MAF iOS Simulator Logging Output

It could be very handy to know how and where to read MAF logging output from iOS simulator. This is not that obvious to find logging output on Mac OS system. All log is written into application.log file, this file is located inside temporary application directory. I will explain how to locate this directory and how to open application.log file. You can read more about MAF testing and logging here - 18.5 Using and Configuring Logging.

Sample mobile application - ADFMobileLogginApp.zip, is pretty basic and contains System.out.println to write a message into application.log file:

Message is written to the log from Action Listener method, invoked from Save button. Log file application.log is accessible from the following location (you can access it from the console) -

Users/youruser/Library/Application Support/iPhone/ 7.1/Applications/com.company.ADFMobileLoggingApp/Document/logs.

As you can see, application.log file is stored under logs directory in documents folder. You must navigate to the iOS simulator, application temporary folder to access it:

There will be application.log file available:

Log file can be opened directly from console, execute command open -a TextEdit application.log:

Message from saveAction() is printed in the log:

Enjoy MAF coding in Mac OS !

How To Start a Case in Oracle Adaptive Case Management 12c

Blog reader was asking to describe how to start a new case in Oracle ACM 12c. You can read my previous blog post on ACM 12c topic - Adaptive Case Management 12c and ADF Human Tasks. There are multiple ways to start a case, depends if you want just to test the case or really use it. I would recommend to use SoapUI to test the case. In the real scenario, case most likely will be started from third party web service or through ACM 12c Java API. Here I would like to describe, how you could use SoapUI to test ACM process during development.

Once ACM 12c application is deployed, you could open it in EM. There is the option to test deployed composite and invoke it through EM Web Service tester. In the example below you can see startCase operation selected and payload structure displayed. Unfortunately it doesn't work well to test ACM process through EM, payload structure is very confusing and it usually fails with mandatory attributes missing errors:

Instead I would recommend to use SoapUI to test the ACM 12c composite. You could download and use it free of charge. Start the tool and choose to create New SOAP Project:

We need WSDL URL to define a SOAP project in SoapUI. You can copy WSDL URL from EM test screen:

Paste it into SoapUI dialog (Initial WSDL field) and Project Name will be filled in automatically (keep Create sample requests for all operations? option selected):

SoapUI will fetch all operations from the service and new SoapUI project will be generated:

In order to start a new case, expand startCase operation and open Request 1. Request will be pre-filled with default payload structure (similar as we saw in EM):

Save SoapUI project, before doing any changes to the request structure. I would suggest to save it under ACM JDEV application structure - project is saved into single XML file:

Change the request to include custom data payload (you can find this XML code inside sample application available for download) and invoke the service. If request will be successful, you should see case number returned in the response:

Case with the same number should be available in BPM Workspace:

Here you can download sample application with SoapUI project (XML file) included - HotelBookingProcessing_v1.zip.

Oracle Mobile Suite Service Bus REST and ADF BC SOAP

One of the key parts of Oracle Mobile Suite 12c offering is Service Bus product. This is logical choice - Service Bus allows to transform complex SOAP Web Service data into simplified REST format, preferred by mobile client. I think it is essential to use Service Bus, when implementing enterprise mobile applications. It makes sense to learn how Oracle Service Bus works. I would recommend to start from Steven Davelaar excellent tutorial article, available here - Creating a Mobile-Optimized REST API Using Oracle Service Bus – Part 2.

I have created my own ADF BC application with SOAP WS - findEmployees method (filters by first and last name). Here you can download both applications - MobileServiceBusApp_v1.zip. Keep in mind, for some reason Service Bus server doesn't start with JDEV 12c BPM Default Domain, it works only with JDEV 12c SOA Default Domain. Make sure to check, which JDEV you are using, you can check the list features installed:

ADF BC SOAP service is implemented to support Master-Detail (Employee - Department Managed by Employee) structure:

Detail VO is visible in WS response, only when ADF BC SDO classes are generated for the VO:

Here is Service Bus application main diagram. External Services contains a reference to the ADF BC SOAP WS (invoked through HTTP service). Proxy Services contains a reference to the REST proxy (this will be accessed from mobile device). Pipeline contains a mapping resource, this is where transformation between SOAP and REST happens:

REST proxy service is defined to support getEmployeesList operation with parameter - nameVar:

REST proxy service response is configured with EmployeeListResponse element, stored in HRRestProxy.xsd file:

Here is the structure returned by REST proxy service - list of employees and list of departments managed by employee:

Pipeline mapps SOAP and REST services. Here we can define how request and response actions are handled. Request action is processed with mapping stored in EmployeeDetailsPS2BS file:

Request action mapping is simple, it needs to pass search parameter and assign it to nameVar parameter from SOAP WS:

This is how search parameter is initialised in REST -  through special expression, value is taken from REST request and sent to SOAP call through mapping:

Response is handled with EmployeeDetailsBS2PS mapping:

This mapping is more complex and it represents the data, returned by REST proxy service. Here we need to map all attributes from SOAP WS to REST proxy service response. This is the place, where actual transformation happens - here we can decide, how we map attributes and even convert between types:

To test Service Bus application, you can simply right click on REST proxy service and choose run:

Service Bus application should be accessible in Enterprise Manager, list of all operations should be present. In the picture below, we can see both SOAP and REST proxy services present. You can open HRRestService:

Test button is present, this allows to test REST proxy service directly from Enterprise Manager:

Provide search parameter  - it will look for 'w' in both first and last name:

Response is constructed with list of employees:

This is request URL: http://127.0.0.1:7101/MobileSBProject/HRRestService/employees/w, it can be used from mobile client, to retrieve similar data (department managed by employee 200 is present):