Saturday, August 20, 2016

Oracle JET and Mobile Cloud Service Authentication with OAuth

I will describe with practical example, how to authenticate against MCS in Oracle JET using OAuth. This is based on sample app from my previous post - Oracle JET and Application Container Cloud (with MCS Integration) (download sample app from there). It would be useful to read through MCS documentation - Authenticating with OAuth in Individual REST Calls.

Oracle JET sample application provides login form:


If login is successful, REST call is done and MCS returns data:


In order to authenticate using OAuth, we need to use Application Key defined in MCS Mobile Backend:


Go to Mobile Backend settings screen and note down OAuth property values for Client ID and Client Secret. We are going to use these values in JET application, to initialize OAuth authentication:


There is one test user defined in Mobile Backend - redsam. We can use these user to login from JET over OAuth:


MCS offers to download SDK Java Script code, we could use it in JET application, to authenticate against MCS service through OAuth, Basic or Facebook login. Download SDK from getting started page:


I'm using mcs.js from MCS SDK, you could find helper method in this class - it executes REST POST to authenticate through OAuth and gets temporary access token in return. This token can be used for subsequent requests in the same session:


There is one more wrapper JS file - mbe.js. Here you define mobile backend connection keys. Authentication type is specified as oAuth:


Make sure to add mcs.js module into main.js paths:


Key point - mbe.authenticate() method (call it from JET module, make sure to reference mbe module in require block). Provide username/password and callbacks for login success and login failure:


In login success callback, I'm reading temporary token and passing it through header Authorization : Bearer. This token can be used for REST requests to MCS:


UI component is displayed when authentication is successful:

Tuesday, August 16, 2016

Oracle JET and Application Container Cloud (with MCS Integration)

I have deployed JET application with Mobile Cloud Service (MCS) integration into Oracle Application Container Cloud service. It works perfectly well, you can try to access it yourself (until my trial cloud account expires on 15th of August) by URL: https://rsjetnodejsapp-deoracleem99369.apaas.us2.oraclecloud.com.

Follow excellent blog article written by Lucas Jellema on details how to deploy JET into Application Container Cloud - Deploying an Oracle JET application to Application Container Cloud and running on Node.js.

First step is to generate empty Node.js application, you can do this from command line (install Node.js and express generator before):

express RSJETNodeJSApp

Navigate into generated application folder and add dependencies using npm:

npm install

Node.js application is created and you could run it by:

npm start

You could test JET app locally with the same command, as soon as you add JET content into Node.js app.

Once you access deployed JET application by URL: https://rsjetnodejsapp-deoracleem99369.apaas.us2.oraclecloud.com. You should get into Home tab, where static chart data is rendered (no integration with MCS yet):


I did a test to check how same screen looks on mobile device. JET renders perfectly, template is adjusted, as well as chart itself:


Go to People tab, this is where integration with MCS is done. I have implemented oAuth security authentication in JET, against MCS service (I will describe it in the next post). You can login with redsam/Wel_come1 user:


Same login screeen is rendered on mobile device nicely:


Once login is successful, JET app executes REST call to MCS endpoint and fetches data (originally returned by ADF BC REST service deployed on Java Cloud and accessed by MCS Connector):


Mobile device view doesn't dissapoint again, same page UI looks great:


JET implementation code is copied into Node.js structure public folder. You can open app in NetBeans, this would simplify editing:


I have deployed this app to Application Container Cloud by creating zip archive (make sure to create manifest.json file). Don't include root folder into archive, include application folders/files directly. Deployment is straightforward, create new Node.js application in Application Container Cloud:


Upload archive, give application name and wait few minutes to initialize. All done:


Here you can download complete example of Node.js app with JET content (and all libraries) I was using to deploy to Application Container Cloud - RSJETNodeJSApp.zip.

Sunday, August 14, 2016

Oracle JET Hybrid - Calling Oracle Mobile Cloud REST

Oracle JET allows to build mobile hybrid apps, based on Cordova and deploy to Android or iOS platform. Read more about it here - Go Mobile with Oracle JET As Easy As 1 2 3. In my previous post I have described how to call REST endpoint running on Oracle MCS from JET - Calling Mobile Cloud REST Service from Oracle JET. Its time to demonstrate the same from JET hybrid app, running on my Android phone.

Here is the screen capture of JET hybrid app running on Android device and displaying data fetched from MCS REST endpoint:


To test data re-fetch, I have updated one record directly through MCS endpoint tester UI, using REST PATCH:


In mobile app, I navigated outside Customers screen and back - data is re-fetched, chart is changed:


What is great about JET hybrid, you could use identical code for JET rendered on the Web and JET rendered on mobile device. You could copy paste the same code between Web and mobile hybrid implementations. Here is example from sample app, where chart and list are displayed:


JET model points to MCS endpoint and defines data collection, same as it would be done for JET rendered on the Web:


Data is fetched in special method - handleActivated. This method is invoked automatically when View Model becomes active (user opens it from the menu). This is quite handy, to have such entry points in the app:


Download sample app code - js_jethybrid_v1.zip, where I have packaged Java Script and HTML examples. You should copy it into application with JET libraries to run.

To build JET hybrid app use:

grunt build:dev --platform=android

To deploy to Android device use:

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

Read more about how to create JET hybrid app here - Go Mobile with Oracle JET As Easy As 1 2 3.

Wednesday, August 10, 2016

Calling Mobile Cloud REST Service from Oracle JET

Let's take a look how we can consume REST service exposed from Mobile Cloud Service (MCS). I will show how you could display data coming from MCS endpoint in Oracle JET. I will be using simple scenario in this post, based on HTTP Basic authentication method offered by MCS. In my next post I plan to review more advanced authentication described in this article - Hybrid Mobile Apps: Using the Mobile Cloud Service JavaScript SDK with Oracle JET.

JET application (download release package with sample code - release_jet_mcs_v1.zip) renders bar chart with data retrieved from MCS endpoint returning information about employees:


Once data is retrieved, I can see invocation statistics logged and reported in MCS dashboard. Calls are executed successfully:


To call MCS service from Oracle JET, we need to pass to extra headers - Authorization and Oracle-Mobile-Backend-ID. Values for both headers can be obtained from MCS dashboard. Go to Mobile Backend and navigate to Settings section. You will find required info under HTTP Basic section:


To bypass CORS issue, you can specify Security_AllowOrigin property in MCS (you need to be admin for this). Read more about it in MCS Developer Guide - Environment Policies and Their Values.  Download property file to your local environment, change it and upload back:


For test purposes, I have specified Security_AllowOrigin=allow:


Oracle JET application JS module is pointing to REST URL handled by MCS:


Fetch operation is configured to pass two headers specific to MCS - this will allow to complete REST request and get response:


NetBeans tool Network Monitor displays request headers (both MCS headers are included):


If request is successful, you should see data returned in the response:


Monday, August 1, 2016

Oracle MCS with ADF BC REST Connector

We already learned how to deploy and access ADF BC REST services from Oracle Java Cloud - ADF BC REST 12.2.1.0 Running Live in Oracle Java Cloud. It's time to see how ADF BC REST can be consumed by Oracle Mobile Cloud Service (MCS). In my point of view, key benefit of MCS is ability to simplify Web Service access for mobile clients, by aggregating these Web Services from different sources and simplifying them. I will try to describe it in very structure way, how to define MCS interface based on ADF BC REST.

Let's start from the top - MCS Web Service interface visible to mobile clients. I have defined four endpoints in MCS, based on ADF BC REST service - list of employees, new employee, employee by ID and update employee. As you can see from MCS tester, implementation details are hidden from the user and you would not know there is ADF BC REST is working in the background.

POST

Create new record. Data is supplied through Body:


You should see newly created record data in the response:


PATCH

Update existing record by ID. If value is invalid, ADF BC REST returns validation message:


When we fix value and try to update again, attribute value is changed:


GET by ID

This can be used to fetch resource by key:


GET

Returns a list of resources


At this point you should be familiar with implemented endpoints. Next I will describe how REST Connector, Custom API and Mobile Backend are configured in MCS.

REST Connector

Connector is defined to point to ADF BC REST service deployed on Oracle Java Cloud. We need connector in order to be able to call external Web Service. Connector is named as EmployeesList:


ADF BC REST service is protected by ADF Security. For this reason there is one rule defined to provide authorization header for REST requests:


Custom API

This is a proxy between connector calling external Web Service and service exposed to mobile client. Here we define available endpoints and implement calls to connectors or other MCS services (storage, notifications, etc.) through Node.js:


Endpoints for REST service are defined here, same ones as described above in MCS tester. We have /employees and /employees/{employeeId} endpoints:


Endpoint /employees is suppose to return a list of employees, without specifying a key or to execute POST to create new employee. GET method is defined to return list of employees:


POST method is defined for /employees and is supposed to create new employee:


GET method for /employees/{employeeid} is supposed to return employee by ID:


PATCH method for /employees/{employeeid} is supposed to update attributes for given employee:


Next important thing in custom API is implementation. This is the place where Node.js transformation between Web Service connector and MCS interface is defined. It can't be edited directly in the cloud, you should download JavaScript package to your environment and edit there. Upload it back when done. Download implementation for my sample app - employees_v3.0.zip:


Let's check implementation. This is the structure of implementation archive. JavaScript file employees.js contains implementation for MCS endpoint interaction with REST connector. JSON file package.json provides metadata for the implementation:


Endpoint GET method is implemented to call EmployeeList connector and to retrieve Employees resource (by calling GET). ADF BC REST supports onlyData=true parameter to return data only, we can pass it through HTTP parameters. Callback for successful result transfers data from REST connector to MCS:


GET by ID is implemented in similar way. Only difference - we add EmployeeId to Employees resource, this constructs REST URL Employees/100:


PATCH is a bit more complex. It needs to set Employee ID, pass request body (with JSON String including attributes to update) and specify ADF BC REST supported Content-Type. This makes it easy for mobile consumer, no need to worry about such things as Content-Type, etc. There is also option to log data, it could be useful for debugging purposes:


POST is pretty much similar to PATCH, it calls post method through connector:


Read more about Connector API in developer guide - Calling Connector APIs from Custom Code.

You must explicitly register Connector to be accessible from API implementation, this is done in package.json:


Mobile Backend

I will show how to read debug messages logged in Mobile Backend, when testing endpoints defined by Custom API. We execute PATCH:


All operations are executed through Mobile Backend, this is the place where we can check statistics and see the flow of REST calls and other actions:


These five actions where invoked during PATCH. You can see payload body content printed, this is done from Custom API implementation function: