Status Monitor Service, like most other provided templates, is designed to utilize an internal MongoDB instance for persistence by default. The service application is built on Node.js, much like the cloud and portal applications, and manages dependencies via npm. The database connectivity dependency used within the template is mongoose. Originally built on earlier versions of the Mobile Application Platform, the template requires a few changes to allow proper integration with the newer versions of MongoDB included in more recent OpenShift and Mobile Application Platform releases.

The first change necessitated for compatibility is updating the mongoose dependency. The template initially requests version 3.8.15, which has been changed in the package.json file to 4.11.4.

"dependencies": {
  ...
  "mongoose": "4.11.4",
  ...
}

Second, a slight modification has been made to the application instantiation portion of the application to prevent a race condition from arising. As the template stands at the time of writing, initial database connectivity is attempted before configuration of the application has completed, resulting in errors regarding not yet instantiated or incorrect db connectionUrl info. By wrapping the application initialization code in a SDK call which checks and correctly sets the variables needed, the race condition is eliminated.

var mbaasApi = require('fh-mbaas-api');
var express = require('express');
var mbaasExpress = mbaasApi.mbaasExpress();
var cors = require('cors');

// handle race condition with OCP 3.X; call for connectionString
// and set to enviro var prior to init of monitor
mbaasApi.db({
    "act": "connectionString"

}, function (err, connectionString) {

    if (err) throw err;

    console.log("connectionString fetched: " + connectionString);

    // rest of app init code here
    ...
});

As mentioned prior, most templates will default to using an internal MongoDB setup for persistence. However, it is possible to configure the template to use an external MongoDB instance or cluster by providing a series of environment variables. A quick look at the SDK code responsible for resolving persistence connectivity information yields a list of variables that could be provided to do just that:

if (process.env.FH_MONGODB_CONN_URL) {
  return cb(undefined, process.env.FH_MONGODB_CONN_URL);
} else if (process.env.OPENSHIFT_MONGODB_DB_HOST) {
  return mongoConnectionStringOS2(cb);
} else if ("openshift3" === process.env.FH_MBAAS_TYPE) {
  return mongoConnectionStringOS3(cb);
} else if (process.env.FH_USE_LOCAL_DB) {
...

Note that the FH_MONGODB_CONN_URL can be declared outright to provide the full connectivity string:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

Backwards compatibility for OpenShift 2.X systems also yields another option where the OPENSHIFT_MONGODB_DB_HOST environment variable can be set, as well as a few more variables: OPENSHIFT_MONGODB_DB_PORT, OPENSHIFT_MONGODB_DB_USERNAME, and OPENSHIFT_MONGODB_DB_PASSWORD. OPENSHIFT_APP_NAME can also be used to define which database the application should authenticate against and utilize.

function mongoConnectionStringOS2(cb) {
  debug('Running in OpenShift 2, constructing db connection string from additional env vars');
  var connectionString,
    host = process.env.OPENSHIFT_MONGODB_DB_HOST,
    user = process.env.OPENSHIFT_MONGODB_DB_USERNAME,
    pass = process.env.OPENSHIFT_MONGODB_DB_PASSWORD,
    port = process.env.OPENSHIFT_MONGODB_DB_PORT,
    dbname = process.env.OPENSHIFT_APP_NAME;
  connectionString = mongodbUri.format({
    username: user,
    password: pass,
    hosts: [{
        host: host,
        port: port
    }],
    database: dbname
  });
  process.env.FH_MONGODB_CONN_URL = connectionString;
  return cb(undefined, process.env.FH_MONGODB_CONN_URL);
}

If none of the mentioned variables have been added, an OpenShift 3.X system, by default, will have an FH_MBAAS_TYPE value set, thus leading the code to resolve and return internal connectivity information.

The Monitoring service features an aggregated monitoring endpoint which the cloud application utilizes to collectively evaluate the health of the microservices suite. The cloud application is configured to call this endpoint at each client request, record detailed results of the response, and mask that response down for the client to a simple ok or fail.

request.get(healthUrl, //dynamic url of aggregated health check via enviro prop
    function(error, response, body) {

        if (error) {
            return callback(error, null);

        } else if (response.statusCode !== 200) {
            return callback("ERROR: bad status code " + response.statusCode, null);

        } else {
            var health = JSON.parse(body);

            if (health.result === 'ok') {
                return callback(null, '{"result": "ok"}');

            } else {
                console.error('health check detected a problem, status ' + health.result);
                health.details.forEach(function(serviceEntry) {
                    console.error(serviceEntry.name + ' reported as ' + serviceEntry.result);
                });
                return callback(null, '{"result": "fail"}');
            }
        }
    }
);

Client applications use the cloud API at a regular interval to call the endpoint exposed in the cloud application to retrieve a summation of microservice suite health results and notify the user when their experience will be hindered due to a reported fail status.

$interval(function() {
    AuthService.checkAvailability().then(function(data) {

        $rootScope.availability = (data.status === 'ok');
        console.log("health check..." + data.status + ' response to bool ' + $rootScope.availability);
    });
}, 5000);

Figure 5.1. Client Availability Warning

The Mobile Application Platform offers a scaffolding template for kickstarted development of Node.js cloud applications with SDK and other requirements pre-configured. The cloud application imported in the previous chapter was initially built atop the provided template.

As with most provided templates, a few assumptions are made about the source code which must be addressed for proper platform integration. In the case of cloud applications, an application.js file is assumed which specifies a few basic integrations, such as routing for MBaaS and cloud calls, as well as a health check endpoint & host/port information. A user-defined /cloud endpoint has been added for routing of custom cloud requests.

The majority of routing logic lies within cloud.js, as defined by the express router variable, cloud.

var cloud = new express.Router();
cloud.use(cors());

cloud.get('/products', function(req, res) {...};

cloud.post('/customers/authenticate', jsonParser, function(req, res) {...};

...

All requests made from client applications are received here, logged into activity, then forwarded to appropriate services for handling. Once a response is returned from the service, it’s then packaged accordingly and returned to the calling client.

cloud.get('/products/:sku', function(req, res) {

    activity.record({
        "action": "Product details fetch for sku " + req.params.sku
    }, function(err) {
        if (err) {
            res.statusCode = 500;
            return res.end(util.inspect(err));
        }
        products.get(req.params.sku, function(err, data) {
            if(err) {
                res.statusCode = 500;
                return res.end(util.inspect(err));
            }
            res.send(data);
        });
    });
});

In most request routings, a call to activity.record is made at the start of each process point for received client requests. The activity service works with the Mobile Application Platform data caching API to record each request made so that data usage and analysis can be performed.

activity.record({
    "action": "action to record"

}, function(err) {...};

The express router also allows for fetching and resetting of the activity list via the /activity context.

cloud.post('/activity/list', function(req, res) {

    activity.list(req.body, function(err, data) {
        if (err) {
            res.statusCode = 500;
            return res.end(util.inspect(err));
        }
        res.json(data);
    });
});

cloud.post('/activity/reset', function(req, res) {

        activity.reset(function(err, data) {
            if (err) {
                res.statusCode = 500;
                return res.end(util.inspect(err));
            }
            res.json(data);
        });
    });

A majority of endpoints defined within the express router configuration forward client requests to the API Gateway entry point of the e-commerce microservices suite. A few additional routes handle internal operations such as administration of activity logging. The express router is capable of handling the GET, POST, PUT, PATCH, and DELETE commands used within the microservice suite, as well as a few others not in use. It also handles the passing of URL parameters to the processing function. Requests carrying a JSON payload utilize a JSON parser, bodyParser, to properly translate the contents of the request for service consumption.

Example usage of inline parameters and JSON parsing:

cloud.post('/customers/:userId/orders', jsonParser, function(req, res) {

    activity.record({
        "action": "Save new user order"

    }, function(err) {
        if (err) {
            res.statusCode = 500;
            return res.end(util.inspect(err));
        }
        sales.saveOrder(req.params.userId, req.body, function(err, data) {
            if(err) {
                res.statusCode = 500;
                return res.end(util.inspect(err));
            }
            res.send(data);
        });
    });
});

$fh.sync.init(dataset_id, options, callback)

The cloud sync framework requires handler functions defined at the client application level responsible for providing access to the back end data & management of data collisions. Each unique dataset being synchronized is identified by a dataset_id specified as the first parameter when calling any function of the sync framework. The platform also provides accessibility of sync events at the cloud level via request interceptors. Implementation-wise, both client applications use data sync to maintain and expose a persistent list of "favorite" products for each authenticated user.

Client application sync initialization and usage, SyncService.js:

init: function () {

    var deferred = $q.defer();

    console.log('initializing sync service');
    $fh.sync.init({
        "do_console_log": true,
        "storage_strategy": "dom"
    });

    ...

    $fh.sync.manage(datasetId);
    $fh.sync.notify(function (notification) {
        if ('sync_complete' === notification.code) {
            $fh.sync.doList(datasetId, success, fail);
        }
        else if ('local_update_applied' === notification.code) {
            $fh.sync.doList(datasetId, success, fail);
        }
        else if ('remote_update_failed' === notification.code) {
            var errorMsg = notification.message ? notification.message.msg ? notification.message.msg : undefined : undefined;
            fail(errorMsg);
        }
    });
    return deferred.promise;
  },

  getList: function() {
    return promiseWrap(function (success, fail) {
        $fh.sync.doList(datasetId, function (r) {
            success(unwrapList(r));
        }, fail);
    });
  },

  update: function (item) {
      return promiseWrap(function (success, fail) {
          $fh.sync.doUpdate(datasetId, item.id, item.data, success, fail);
      });
  },

  ...

Client application SyncService usage, HomeController.js:

function addToFavorites(product, $event) {

    $event.stopPropagation();
    SyncService.save(product);
    product.addedToFavorites = true;
    $timeout(function () {
        product.addedToFavorites = false;
    }, 700);
}
instance.addToFavorites = addToFavorites;

Cloud application Sync request interceptor, sync.js:

var globalRequestInterceptor = function(dataset_id, params, cb) {

    console.log('sync intercept for dataset ' + dataset_id + ' with params ' + params);
    return cb(null);
};

fh.sync.globalInterceptRequest(globalRequestInterceptor);

In the example client applications, data caching is used for recording the previously mentioned cloud activity list and tracking of user sessions. Caching functionality is mostly wrapped within calls made to the cloud application. For example, when a user is authenticated in the cloud via a call from a client application, a token is created and cached, which allows tracking/usage of the session from any client application, and automatic expiration after a configurable amount of time.

Cloud token management, sales.js:

exports.setCacheKey = function (cacheKey) {
    key = cacheKey;
};

exports.checkToken = function (userId, callback) {
    fh.cache({
        act: "load",
        key: key
    }, function (err, res) {
        if (err) {
            console.error("error checking token ", err);
            return callback(err, null);
        }
        var tokenList = JSON.parse(res);
        var tokenFound = (tokenList || []).indexOf(userId) > -1;
        console.log("token " + userId + " - " + tokenFound);
        return callback(null, {
            'tokenFound': tokenFound
        });
    });
};

exports.setToken = function (userId, callback) {
    fh.cache({
        act: "load",
        key: key
    }, function (err, res) {
        if (err) {
            console.log("error1 " + err);
            return callback(err, null);
        }
        var tokenList = JSON.parse(res);
        ...
    });
};

exports.removeToken = function (userId, callback) {
    fh.cache({
        act: "load",
        key: key
    }, function (err, res) {
        if (err) {
            return callback(err, null);
        }
        var tokenList = JSON.parse(res);
        ...
    });
};

The Forms Builder allows mobile forms to be quickly and easily created using drag and drop components. While it’s possible to build entire applications around this functionality, integration of a single example form for collection of payment information could better handle form-specific validation and third-party payment system integration. For the purposes of this project, a payment information form was generated to showcase the feature, but not integrated into the client applications:

Similarly to MBaaS Services and APIs, Drag and Drop Apps are a sharable component, and thus housed in their own dashboard within the Mobile Application Platform.

Figure 5.2. Drag and Drop Apps Dashboard

Seen here, drag and drop components allow for easy definition of form content and configuration of each field:

Figure 5.3. Constructing the Form

Figure 5.4. Field Configuration

After construction and configuration, form themes can be created to allow for seamless visual integration into existing apps or complete customization of application appearance:

Figure 5.5. Form Theming

Once developed, forms can further be enhanced via available platform tooling to include field-specific and page-specific rule sets, data source coupling, broadcast of change notifications, submission routing, and more. For more information on using Form Builder, refer to the Red Hat Mobile Application Platform 4.4 Drag and Drop Apps Guide.

$fh.db(options, callback(err, res))

The $fh.db call provides access to hosted data storage, which supports CRUDL (create, read, update, delete, list) and index operations. It also supports deleteall, which deletes all the records in the specified entity.

When using the Build context within the Cordova/Ionic client application, the resulting native mobile artifacts are built via the Mobile Application Platform’s Build Farm. This tool enables automation of the build process, record keeping of previous builds, and creation of deployable artifacts for various mobile platforms without requiring the associated infrastructure and tools (e.g. building iOS binaries from a Linux OS).

In order to accommodate a variety of target platforms while preserving offline capabilities and access to device APIs, the example mobile application uses the Apache Cordova starter template provided within the Mobile Application Platform. Cordova, as one of several cross-platform frameworks supported, features HTML/CSS/JS mobile development via Node.js application. The framework is open source and widely available via npm. For more information on Cordova, visit the official documentation.

The Ionic Framework, built atop Cordova, further simplifies the process of developing cross-platform applications by simplifying access to dozens of native device features via plugin support and themed interface components for rapid UI and feature development.

The Mobile Application Platform offers a scaffolding template to kickstart development of Cordova and/or Ionic applications with SDK and other requirements pre-configured. Such a template was used initially for starting the example ecom-shop source code used for import.

As previously mentioned in the context of importing into the App Studio, a few assumptions are made about the configuration of the client. Contents of the fhconfig.json file are copied directly from the parameters given in the Connection component of the project, using the following structure:

{
  "appid": "<app_id>",
  "appkey": "<app_key>",
  "apptitle": "<app_title>",
  "connectiontag": "<connection-tag>",
  "host": "<app_host>",
  "projectid": "<project_id>"
}

Communications with the cloud app from within the client are performed via SDK. Such calls are wrapped inside services that utilize $fh.cloud(…​) to form and issue the request:

var register = function(user) {

   var defer = $q.defer();
   user.id = null;
   var params = {
       path: '/cloud/customers',
       data: user,
       method: "POST",
       contentType: "application/json",
       timeout: 15000
   };
   $fh.cloud(params, defer.resolve, defer.reject);
   return defer.promise;
};

Users can run an HTML5 presentation of the mobile client locally by issuing the npm install command within the home directory of the project, followed by grunt serve:

$ grunt serve
Running "serve" task

Running "browserify:www/main.js" (browserify) task
>> Bundle www/main.js created.

Running "clean:server" (clean) task

Running "connect:livereload" (connect) task
Started connect web server on http://localhost:9002

Running "watch" task
Waiting...

Once running, a browser tab or window will launch for the application. The user can also visit lab.html to see both iOS and Android renderings of the application:

Figure 5.6. Platform Preview

SDK configuration of the client portal application is completed as follows: