Introduction

The Feedhenry Raincatcher project provides a framework for building Workforce Management (WFM) solutions that includes a mobile hybrid app, a management portal web app and a server that manages synchronization of work orders between the portal and the mobile apps. The synchronization technology is built on the Feedhenry Datasync framework. Deploying the mobile, portal and server repositories on Red Hat Mobile Application Platform (RHMAP) is a straightforward task, which will be discussed more below. Furthermore, adding a new workflow step can also be accomplished using some workarounds which we will look at later in this post.

Integrating the Raincatcher Server with RHMAP

The source for the Raincatcher Server can be found at github. It currently does not contain any integration with Red Hat MAP, so in order to be able to deploy and run the server we need to add some integration code.

Import the Raincatcher Server to RHMAP

The most straightforward way of importing the Raincatcher server is to simply use the RHMAP import tool and point to the feedhenry-raincatcher/raincatcher-server repository at github. Use the CloudApp option when choosing app type. This will create a new project in RHMAP and adding the Raincatcher server as a CloudApp.

The next step is to add the RHMAP middleware to the CloudApp.

Add the RHMAP Middleware

In the RHMAP AppStudio, open the CloudApp’s Editor page. When you look att the directory structure, you’ll see a src folder. You then open the src/app.js file, this is a suitable point to add the RHMAP middleware, and insert the following code:

var mbaas = require("fh-mbaas-api");
var mbaasExpress = mbaas.mbaasExpress();
// list the endpoints which you want to make securable here
var securableEndpoints;
securableEndpoints = ['/'];
// Note: the order which we add middleware to Express here is important!
app.use('/sys', mbaasExpress.sys(securableEndpoints));
app.use('/mbaas', mbaasExpress.mbaas);
// Important that this is last!
app.use(mbaasExpress.errorHandler());

That’s all RHMAP middleware you need to add to the server.
The next step is to connect the server to a MongoDB datastore.

Create a MongoDB datastore

The Raincatcher server doesn’t use the standard RHMAP $fh.db API to access the MongoDB datastore. Instead it uses it’s own MongoDB handler. Therefore we need to provide it with a URL to a MongoDB instance running on RHMAP.
On RHMAP each CloudApp is associated with it’s own MongoDB instance. Take the following steps to connect the instance to the Raincatcher server:

1. In RHMAP AppStudio, open the CloudApp’s Data Browser
2. If there is an option to upgrade the database, then do so
3. In RHMAP AppStudio, open the CloudApp’s Environment Variables page
4. Under the System Variables section you’ll find the MongoDB URL next to the variable FH_MONGODB_CONN_URL

1. Copy the variable’s value which should be a URL starting with mongodb:
2. Open the Editor view for the CloudApp
3. Open the file config-dev.js (this assumes you’re using the default config, otherwise open config-prod.js)
4. Locate the following code block:

function getMongoUrl() {
  if (process.env.MONGO_CONNECTION_URL) {
    return process.env.MONGO_CONNECTION_URL
  }
  if (process.env.FH_MONGODB_CONN_URL) {
    // Legacy env variable only to support in house systems
    return process.env.FH_MONGODB_CONN_URL;
  }
  return "mongodb://127.0.0.1:27017/raincatcher";
}

1. Change the above to return the MongoDB URL you found under System Variables instead of 127.0.0.1:

function getMongoUrl() {
  if (process.env.MONGO_CONNECTION_URL) {
    return process.env.MONGO_CONNECTION_URL
  }
  if (process.env.FH_MONGODB_CONN_URL) {
    // Legacy env variable only to support in house systems
    return process.env.FH_MONGODB_CONN_URL;
  }
  //return "mongodb://127.0.0.1:27017/raincatcher";

    return "mongodb://...";
}

1. Save the file

Now the Raincatcher server will be able to connect to it’s own MongoDB instance.

Deploy the Raincatcher Server

The last step is to deploy the CloudApp, which is done in the CloudApp’s Deploy view.
Use NodeJS 6 when deploying.

Now if you look in the Data Browser, you should see a number of new collections created by the server.

The next step is to import the Raincatcher portal.

Integrating the Raincatcher Portal with RHMAP

The Raincatcher portal can be found on github. Also for the portal the RHMAP middleware needs to be added.

Import the Raincatcher Portal to RHMAP

The most straightforward way of importing the Raincatcher Portal is to simply use the RHMAP import tool and point to the feedhenry-raincatcher/raincatcher-portal repository at github. Use the Web App option when choosing app type. This will create a new project in RHMAP and adding the Raincatcher server as a Web App.

The next step is to add the RHMAP middleware to the Portal.

Add the RHMAP Middleware

In the RHMAP AppStudio, open the Web App’s Editor page. When you look att the directory structure, you’ll see a src folder. You then open the src/application.js file, this is a suitable point to add the RHMAP middleware, and insert the same code as you did for the server:

The portal doesn’t use a MongoDB instance, so no further configuration is needed. Next, you deploy the portal, using NodeJS 6 as runtime. Finally you should be able to open the portal using the preview screen the Web App’s Details view in RHMAP AppStudio.

Integrating the Raincatcher Mobile App with RHMAP

The Raincatcher mobile app can be found on github. However the mobile app is a provided as a Cordova app hence no RHMAP integration is required.

Import the Raincatcher Mobile App to RHMAP

Use the same way of importing the Raincatcher mobile app as you did with the server and portal, which is to again use the RHMAP import tool and point to the feedhenry-raincatcher/raincatcher-mobile repository at github. Use the Cordova App option when choosing app type. This will create a new project in RHMAP and adding the Raincatcher server as a Cordova App.

You should be able to see the Raincatcher mobile app in the preview:

Now you have the complete Raincatcher framework up and running in RHMAP! The next step is to add a new workflow step using the Raincatcher step-generator.

Adding a Workflow Step

Raincatcher provides a workflow engine that contains a sequence of steps. I’m not going to go through the details on this here, please refer to the Raincatcher documentation to learn more about workflows and steps. For the purpose of this post, I’m just going to demonstrate how a step is created, then added to the Raincatcher framework running on RHMAP.

Generating a New Step

Raincatcher provides a step generatorwhich can be used to quickly generate the code necessary to implement a step.
Let’s assume you have now generated a new step called ‘mystep’. The step needs to be added to the Raincatcher portal and mobile app. Refer to the Raincatcher step-template documentation for details on how this is achieved.
I used the following method to integrate the step with Raincatcher on RHMAP:

Integrating the Step with RHMAP

When generated, the step code is located in a local folder on your PC or Mac. The way I used to integrate my step was to create a repository containing my step code, and then referring to that repository in the dependency section of package.json for my Raincatcher portal web app and Raincatcher mobile app running on RHMAP, i.e.

"@raincatcher/step-mystep": "git+https://github.com/torbjorndahlen/-raincatcher-step-mystep.git"

Note however that Raincatcher portal and mobile app is built with Typescript which isn’t natively supported by RHMAP. Hence I also needed to rebuild the portal and mobile app locally before being able to deploy and run with the new step. I used the following steps:

1. Clone the portal web app from RHMAP to your local environment
2. Add the necessary integration code to your local copy as documented in the Raincatcher step-template
3. Rebuild the app with ‘npm install’ followed by ‘npm run build’
4. Commit and push your repository back to RHMAP

You should now be able to see the new step in the portal:

The same procedure is repeated for the mobile app.

Summary

Feedhenry Raincatcher is a new, completely rewritten version of the previous WFM template that was part of Red Hat Mobile Application Platform. This new version however, is not going to be provided as a project template on RHMAP, instead importing the Raincatcher repositories is the way to use Raincatcher on RHMAP. Therefore I wrote this post for anyone interested in trying out the framework on RHMAP instead of running everything locally. Creating new workflows using steps is straightforward, however since they are based on Typescript, a bit of local build is also required before deploying on RHMAP. Hope this post will help you quickly getting started trying out Raincatcher on RHMAP!