1 Get to Know Oracle Mobile Cloud Service

Welcome to Oracle Mobile Cloud Service (MCS)! MCS is a cloud-based service that provides a unified hub for developing, deploying, maintaining, monitoring, and analyzing your mobile apps and the resources that they rely on.

Your entry point into MCS depends on your role in your team’s mobile project.

If you are a mobile app developer, you use MCS to line up and test the resources you need for your apps to work. This includes selecting from MCS platform APIs and custom APIs and collaborating with other team members to create new custom APIs.

If you are a service developer, you write Node.js-based JavaScript code to implement the custom APIs required by the mobile app developers on your team. You might also find yourself collaborating with mobile app developers to fine-tune API designs and creating connector APIs to connect to enterprise systems.

If you are the team’s enterprise architect, you establish where desired data and functionality will come from, security and environment policies, and the roles and permissions of team members.

If you are the team’s mobile program manager, you use the Analytics features to track usage patterns.

If you are a mobile cloud administrator, you work within the Administration tab to monitor the services in production, use the Diagnostics features to drill down and pinpoint problems, and handle other admin tasks such as the adding and removing of users.

To get a more concrete idea of how all of this works, let’s imagine you work for a company called FixItFast (FiF) that supplies maintenance services for large in-house appliances. To help facilitate speed and quality of service, FiF management wants to roll out a mobile app which customers can use to quickly initiate a service request and provide key information, such as by scanning the bar code of the defective appliance. They’ll call this app FiF_Customer.

Here’s how your team would use Oracle Mobile Cloud Service to develop that app and get the most out of it.

Jump in with Mobile Backends

As a mobile app developer, your first task is to set up a mobile backend for the app.

A mobile backend is a logical grouping of custom APIs, users, storage collections, and other resources that serves as a cloud-based companion to one or more related mobile apps. Within a mobile backend, you organize and develop resources that will be used by your apps (which they access as REST web services). The mobile backend also provides the security context (backed by an OAuth client ID/Client secret pair or by HTTP Basic authentication credentials) for accessing those services from the mobile app.

When you need apps for the same purpose on multiple platforms, all of those apps can use the same mobile backend. Likewise, completely different apps that rely on the same resources can share a mobile backend.

The screenshot below shows the Settings page of a mobile backend.

At development time, here are some of the things you do with a mobile backend:

  • Browse and select the APIs to be available for the apps and test their endpoints with mock data.

  • Create object storage collections and enable offline data caching.

  • Specify a user realm within which you manage the mobile app users who are allowed to access the applications associated with the mobile backend.

  • Set up notifications for your apps using the services provided by the platform vendors (such as Apple Push Notifications Service (APNS) for iOS, Google Cloud Messaging (GCM) for Android, and Windows Push Notification Services (WNS)). If you set up notifications for multiple platforms, you can initiate a single notification and have it delivered to apps on multiple platforms.

Later, at deployment time, the mobile backend serves as a deployment unit with dependency management for all of the artifacts you need to support the set of mobile apps.

However, before you do any of this for the FiF_Customer app that we introduced earlier, assume you’re going to create a custom API to handle much of the app’s heavy lifting.

Design Custom APIs

Especially if your company is new to MCS, one of the first things you’ll need to do is start creating your own set of REST APIs to provide building blocks for your apps.

API creation is divided into two parts: designing and implementing. Let’s talk about designing first.

When you design a REST API, you express the functionality that you expect in terms of resources, along with the HTTP methods they accept, and media types for the request and response bodies. In other words, you essentially define the formats for making a request on the API and for what kind of data is returned in the response. This definition is stored in a RAML (RESTful API Modeling Language) document. You don’t actually fill in the details of how the data is produced and where it comes from right away. Those details are worked out later in the implementation.

For the previously-mentioned FiF_Customer app, you’ll need an API for generating and logging incident reports. Let’s call the API incidentreports. This report will consist of data entered by the customer, including a photo of the appliance’s bar code and a description of the problem.

As the centerpiece to this API, you could define a resource called incidents to represent all incident reports. For that resource, you would have a GET method to retrieve all incidents and a POST to create a new incident. Further, you could define parameters for querying based on given criteria, such as the incident ID.

For the bodies of the requests sent to the incidents endpoint and responses returned from it, you’ll define the media types (such as application/json) that they accept and then provide examples for those bodies. Those examples serve as mock data that is used when you (and eventually the users of your API) test the way the API works in a mobile backend.

Once you are happy with the structure of the API, a service developer can get to work on coding the implementation.

Implement APIs

As a service developer, you will work on APIs that have been sketched out for you by app developers (or perhaps on APIs that you have designed yourself). Once you have a set of endpoints to work with (like /mobile/custom/incidentreport/incidents, as outlined above), you can start implementing them with custom code.

This custom code takes the form of Node.js-based JavaScript. For each API implementation, you create a Node.js module. Within each module, you write a route definition for each endpoint that specifies how to respond to a client request to that endpoint. These route definitions are based on conventions promoted by the Express.js web framework for Node.js. You can also include other Node.js libraries in the module to support your custom code.

Let’s go back to the GET method on the incidents resource that we were just talking about. Imagine that you have created a route definition for it that retrieves the incidents via the Database Access API. The custom code implementing the endpoint might look something like this:

service.get('/mobile/custom/incidentreport/incidents', function (req, res) {
  //call to custom code SDK, which handles the interaction with the Database Access API
    function (result) {         
      res.send(result.statusCode, result.result);       
    function (error) {         
      res.send(500, error.error);       

In the real world, your implementations will probably need additional logic and perhaps need to aggregate data with multiple API calls, but this sample should give you an idea of the basic mechanisms involved.

In much of your custom code, you’ll probably also need to access various enterprise resources that reside outside of MCS, such as databases, CRM software, and other cloud services and legacy systems. Read on to learn more about accessing those resources and shaping them for use in your mobile apps.

Get the Data

Chances are that the main purpose of many of your custom APIs is to pull data into your app from various business applications and other systems maintained by your company, whether cloud or on-premises. As a service developer, your challenge is to do so in a way that’s manageable, especially if you don’t have detailed knowledge of the systems or the interfaces needed to access them. MCS answers this problem with connector APIs.

Connector APIs provide a bridge between your custom APIs and the enterprise services you want to process with those APIs. Using the REST, SOAP, and ICS (Integration Cloud Service) connector types, you create connector APIs for each data source that you want to access. You define a connector API by filling in info on the target resource, creating rules for the call parameters to "shape" the returned data so that it works well in a mobile context, and specifying security policies. The result is a reusable service that’s exposed as a straightforward REST API that you can view in the Custom Code API Catalog. Service developers can call this connector from their custom code just like they would any other API and do not have to worry about tricky specifics like security policies and identity propagation.

For the Incident Report API, there are a number of resources that you’ll want to interact with, such as an API for geolocation and customer data through your company’s CRM software. In this example, the custom code calls a connector called RightNow to add an incident report to an Oracle Service Cloud instance that is used to manage customer service interactions.

 *  The following example calls the 'CreateIncident' resource
 *  on a SOAP connector named '/mobile/connector/RightNow'.
 *   */
{Body: {CreateIncident: req.body}}).then(
    res.send(result.statusCode, result.result);
    res.send(500, error.error);


When you use connector APIs in your apps, you get other MCS advantages when your apps call the API, including diagnostics to measure API performance and API call analytics to evaluate how mobile apps are used.

Use Platform APIs

In addition to custom APIs, you can use MCS platform REST APIs in your apps. You can call these APIs directly from your apps and/or via the implementation code of custom APIs. You can also access many of them through MCS’s SDKs for the iOS, Android, Windows, Cordova, and JavaScript platforms.

The available platform APIs include the following:

  • Storage to work with collections and objects (such as images and documents) that you associate with your mobile backend.

    You set up collections in the web interface (and optionally populate them). Then you can use API calls to add, modify, and delete objects in those collections.

  • Mobile User Management to store and retrieve data related to mobile users.

  • Location to define location devices and places and query for them from your mobile apps.

  • Notifications for writing code to send notifications to your mobile apps.

  • Analytics Collector to initiate logging of specified events in the running apps. These logged events are collected and can be viewed through the prism of various reports in the Analytics tab in the MCS user interface.

  • Database Access to access an Oracle Cloud database with REST calls. For security reasons, you can access the Database Access operations only from custom API implementations by using the custom code SDK, as described in Accessing the Database Access API from Custom Code. You can't make direct requests from client applications.

  • Database Management to add, view, replace, and drop tables that are created (and updated) automatically when you POST or PUT a JSON object using Database Access API.

  • App Policies to retrieve application configuration properties that you have set in the mobile backend.

Call APIs from Your App Code

Once you have selected the custom APIs to use in your mobile backend, you can call their REST endpoints from your mobile app code. Platform APIs are automatically available for all mobile backends, but calling them works the same way as calling custom APIs.

Here is a call from some Android app code to use the incidentreport custom API to post an incident.

String url = "http://<MCS_SERVER>:<PORT>/mobile/custom/incidentreport/incidents"; 

HttpClient httpClient = new DefaultHttpClient();
HttpPost post = new HttpPost(url);
post.addHeader("Content-Type", "application/json");
post.addHeader("Authorization", basic bWNzOldlbGNvbWUxKg==); 
try { 
    JSONObject newIncidentReport = new JSONObject();
    newIncidentReport.put("EmailAddress", email); 
    newIncidentReport.put("ImageLink", imageLink); 
    post.setEntity(new StringEntity(newIncidentReport.toString())); 
    HttpResponse response = httpClient.execute(post); 
    StatusLine statusLine = response.getStatusLine(); 
    if (statusLine.getStatusCode() == HttpStatus.SC_OK) { 
        // Success 
}catch (Exception e) { 

And here is an example of using the Storage API in an Android app to post to a collection called FiF_Images that has been associated with your mobile backend:

String url = "http://<MCS_SERVER>:<PORT/mobile/platform/storage/collections/FIF_Images/objects";

HttpClient httpClient = new DefaultHttpClient();
HttpPost post = new HttpPost(url);
post.setEntity(new ByteArrayEntity(imageBytes));
post.addHeader("X-Backend-Token", "FixItFast_Customer/1.0");
post.addHeader("Content-Type", "image/jpeg");
post.addHeader("Authorization", "basic bWNzOldlbGNvbWUxKg=="); 
HttpResponse response = httpclient.execute(post); 

StatusLine statusLine = response.getStatusLine();
if (statusLine.getStatusCode() == HttpStatus.SC_CREATED) {  
     // Image uploaded successfully

Call Platform APIs with Mobile SDKs

In addition to being able to call MCS APIs with straight REST calls, MCS provides SDKs to simplify use of some of the platform APIs in native code.

Here’s some code for an Android app that uses the SDK classes (StorageCollection and StorageObject) for object storage.

Storage storage = 
    try { 
        StorageCollection imagesCollection = storage.getStorageCollection("FIF_Images"); 
        StorageObject image = imagesCollection.get("3x4mp1e-st0r4g3-0bj3ct-k3y"); 
        byte[] imageBytes = image.getPayloadBytes();
    }catch (ServiceProxyException e) { 
        int errorCode = e.getErrorCode(); 

A similar call with the iOS SDK might look like:

AppDelegate* appDelegate = [[UIApplication sharedApplication] delegate];
OMCMobileBackend* mbe = [appDelegate myMobileBackend];
OMCStorage* storage = [mbe storage];
OMCStorageCollection* aCollection = [storage getCollection:FIF_Images];
OMCStorageObject* aObject = [aCollection get:3x4mp1e-st0r4g3-0bj3ct-k3y];
NSData* data = [aObject getPayloadData];

Set Up and Manage Your Mobile App Users

With the app just about ready to go, it’s now time the person on your team who has the Oracle Cloud identity domain administrator role to set up the users of the app. To manage the users of your mobile apps, you set up user realms. A realm is a collection of mobile app users with similar properties. Each mobile backend in an environment is associated with one realm. However, a realm can be used by multiple environments and multiple mobile backends. (Keep reading for more information on environments.)

You can also set up roles, which are sets of permissions that you can assign to users to control which users have permissions to what APIs and other resources. For example, you could have a role for customer service reps that provides them permissions to access the APIs that are needed for their job, such as for assigning cases. Similarly, you could have a role for technicians that allows them to access APIs relevant to their job, such as getting notifications for open cases and marking a case as resolved.

If you already have an identity provider for the future users of your apps, you can use MCS’s Enterprise Single Sign-On support to enable those users to log in to apps that use MCS mobile backends. Similarly, you can use MCS’s support for Facebook login for consumer apps.

Deploy Code between MCS Environments

Once your code is developed and your mobile backend is configured, it’s time to proceed with deployment.

An environment is a predefined arena for working in MCS. You develop artifacts (mobile backends, APIs, and user realms) or custom code in a development environment and deploy to a runtime environment for testing and distribution. You can work in one environment at a time.

For example, if you have a three-environment setup, you might use it this way:

  • Designate one as a development environment to create your mobile backend, define custom APIs, create new services using custom code, set up storage for your collections, and so on. Typically, such an environment is where your team does most of its development work, and it isn’t exposed to end users.

  • Designate one as a staging environment where you can deploy completed project code for testing. Team members with broad permissions in the development environment might have no access to this staging environment if testing is handled by another team.

  • Designate one as a production environment where you can promote fully tested code for real world distribution through an app store, such as the Apple App Store or Google Play Store. Not many team members need access to the published project code in this environment.

For more information about environments, see MCS Environments.

When you deploy, you follow this process:
  1. Publish numbered versions of your artifacts, essentially freezing them, so those versions can no longer be edited. To make a change to a published artifact, you need to create a new version, make necessary changes, and publish again.

  2. Set (or verify) dependencies between relevant artifacts, such as between API versions and their implementation versions.

  3. Set (or verify) environment policies to determine things such as what security credentials are associated with the environment, what versions of an app can access the mobile backend, timeouts, etc.

  4. Push the artifacts to the target environment.

To release updates, you simply create a new version in your development environment and follow the deployment process again.

Monitor and Administer the Mobile Infrastructure

As the mobile cloud administrator, you use the Administration tab in the user interface to monitor the health and performance of your apps in all of your environments, particularly Production. The Administration tab provides graphical and tabular data on the server load and the request backlog. If any problems arise in production, you can view logs of server and app activity, filter them, and drill down to identify any trouble spots.

Analyze Your Mobile Projects

Once your apps are in production, the mobile program manager can step in to evaluate long-term usage and performance patterns in your mobile backends.

MCS comes with a host of built-in metrics such as API calls, API call response time, new users, active users, session count, and session duration.

You can also track any custom events that have been created in your apps using the Analytics API. For example, imagine your app uses the Analytics API to post an event each time a mobile app user creates a new incident report and capture properties such as appliance type, make, model, and model year. You could then generate graphs and tables based on those events and filter the data in any number of ways, such as how many incident reports were filed for water heaters every month for the last year.

What About Security?

Oracle Mobile Cloud Service is designed with enterprise-grade security baked in.

Security begins at the level of the mobile backend. For an app to access any resources through a mobile backend, its user first has to be authenticated with the mobile backend, whether it is using OAuth, enterprise single sign-on (SSO), Facebook login, or HTTP Basic authentication. See Authentication in MCS for the details.

Once a user is authenticated, access to APIs is controlled through MCS’s mobile user management features. Realms allow mobile apps to use a shared set of users and data, and roles define permissions that control user access to APIs and resources from those mobile apps. For an introduction to users, roles and realms in MCS, see Set Up Mobile Users, Realms and Roles.

Security for custom APIs can be configured individually for each API. On the Security tab in the API Designer, you can decide whether or not an API can be accessed anonymously (without a user login). If you choose No, you can define the authorization policy by specifying which roles can access the API or specific endpoints. For details, see Security in Custom APIs.

MCS connector APIs also have access to security functionality, which is especially important if the connection involves transmitting proprietary or sensitive information. For details, see Security Policy Types for REST Connector APIs and Security Policy Types for SOAP Connector APIs.

Video: Security Overview

This video illustrates the key security aspects of MCS:

Job Descriptions and Learning Paths

Let’s take a few moments to talk about the various jobs (e.g. mobile developer, service developer, etc.) that we introduced at the beginning of the chapter. MCS is designed to meet the needs of widely disparate team roles, so the way you interact with MCS depends on your given responsibilities. To help you better understand how your responsibilities fit with MCS, here’s more specific detail about what we mean by each job and links to the parts of the guide that are most relevant to those jobs.

Mobile App Developer

As a mobile app developer, it’s your job to create new applications for the iOS and Android platforms. Often these apps incorporate existing enterprise functionality, which you’ll need to optimize for phones and tablets.

To make things easier, you’ll want to leverage existing APIs wherever possible. You can find our built-in APIs for common functions (like storage, mobile user management, notifications, and analytics) in Oracle Mobile Cloud Service’s API Catalog, as well as APIs that other team members have created. When the API you need isn’t available, use the API Designer to sketch out the API quickly and supply some mock data. Then you can go back to work on your app and let the service developer fill in the details (or do it yourself, if you prefer).

Here are the sections you’ll be most interested in.

If you haven’t gone through them already, here are some tutorials to help you get started quickly:

Here are some other resources that you may want to look at:

  • This video overview of the API designer shows you how to quickly sketch out an API design, which you can then pass to a service developer for implementation.

  • The YouTube channel for Oracle Mobile Platform, which contains instructional videos covering a plethora of MCS topics, including designing and testing mobile backends, security, registering and configuring notifications, the storage API (including testing and examples), creating custom reports with the Analytics API, building connectors, and more.

Service Developer

As a service developer, your primary task in Oracle Mobile Cloud Service is to write the JavaScript code that implements the custom APIs that your organization's mobile apps rely on. These APIs might draw on existing enterprise services, platform APIs provided by Oracle Mobile Cloud Service, or other APIs your team has developed in Oracle Mobile Cloud Service.

In addition, you may be called upon to work with mobile developers to refine APIs they’ve already sketched out, and to create connector APIs that make it easier for your custom APIs to access enterprise resources.

Here are the chapters you’ll be most interested in.

If you haven’t gone through them already, here are some tutorials to help you get started quickly:

  • Mobile Backends (Access this tutorial by signing into MCS and clicking Get Started on the home page.)

  • Custom APIs

  • Connectors

You may also want to subscribe to The YouTube channel for Oracle Mobile Platform, which contains instructional videos covering all of the areas above.

Enterprise Architect

As the enterprise architect, you’re concerned with designing a secure and scalable mobile solution for your business. It’s your job to determine what can be built, where desired data and functionality will come from, and what security and environment policies need to be implemented. You’re particularly attuned to establishing best practices, consistency, and reusability in your resources and repeatability in your processes.

In addition to establishing the mobile architecture, you also oversee how apps are deployed initially, updated, and patched.

You will be most interested in the following topics:

You may also want to subscribe to the YouTube channel for Oracle Mobile Platform, which contains instructional videos covering all of the areas above.

Mobile Cloud Administrator

As the mobile cloud admin, you are responsible for setting up MCS for your team members and making sure that it keeps clicking both for the team members working with MCS and the end users of your apps. In your day-to-day work, you monitor the Administration tab to make sure that the service is running smoothly. When you detect issues or when problems are reported to you, the built-in diagnostics tools help you identify and fix the problems.

You will be most interested in the following chapters:

If you haven’t gone through it already, you may want to look at the Mobile User Management tutorial, which shows how to quickly set up an additional realm.

You might also want to look at this video on managing your mobile deployments as well as the YouTube channel for Oracle Mobile Platform, which contains instructional videos covering all of the areas above.

Mobile Program Manager

As the mobile program manager, you’re responsible for the success of your mobile strategy. You want to know how many people are using your applications, and how they’re using them. To achieve that, you will probably want to use Oracle Mobile Cloud Service's Analytics features to track standard metrics (such as registered and active users, number of transactions, etc.) and create your own events to track.

You will be most interested in the following chapter:

In addition, you may be interested in looking at this video on MCS’s Analytics and the YouTube channel for Oracle Mobile Platform.