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.

Description of the illustration intro_mbe.png

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.

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.

Description of the illustration intro_api_resources.png

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

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:

/**
 * GET ALL INCIDENTS
 */
service.get('/mobile/custom/incidentreport/incidents', function (req, res) {
  //call to custom code SDK, which handles the interaction with the Database Access API
  req.oracleMobile.database.getAll(
    'FIF_Incidents').then(
    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.

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.

Description of the illustration intro_connector_flow.png

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'.
 *   */
req.oracleMobile.connectors.RightNow.post('CreateIncident', 
{Body: {CreateIncident: req.body}}).then(
  function(result){
    res.send(result.statusCode, result.result);
  },
  function(error){
    res.send(500, error.error);
  }
);

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.

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
}

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.

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.

Description of the illustration intro_lifecycle.png

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

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.

Description of the illustration intro_diagnostics_dash.png

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.

Description of the illustration intro_analytics_api_calls.png

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.

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.

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.