Raincatcher Introduction

1. RainCatcher 1.1.0

RainCatcher is a Workforce Management Platform.

RainCatcher allows you to move from paper based forms and processes into complete mobile enabled solution. RainCatcher connects an organization’s back-office with its fleet of mobilized employees by providing two fully customizable applications:

Mobile worker (operator) application
Management Portal (back office) application

Both applications are utilizing Node.js based server through RESTful api.

1.1. Goals

The primary goal of RainCatcher is to minimize development effort required to build WFM applications. It achieves that by providing set of modules that can be integrated into existing applications. Developers can effectively reuse them in their applications or base on RainCatcher reference applications that integrate all modules into fully functional solution. RainCatcher targets to satisfy requirements that each production website and mobile application needs. In particular:

Mobile development (using Apache Cordova plugins)
Real-time Data Access and synchronization
Authentication and Authorization (using multiple providers)
Security (using best patterns for mobile and website security)
Logging (tracing issues out of the box)
User interface (AngularJS based interface that can be customized)

It allows developers to leverage production hardened applications by extending them to suit their business needs. Each application can be customized by writing or reusing one of the available RainCatcher modules.

RainCatcher separates modules into different categories:

Core modules containing main functionality (@raincatcher/*)
- Client modules used in mobile and portal applications
- Server modules to be used only in server application
User interface modules (@raincatcher/angularjs-*)
Step modules (@raincatcher/step-*)
Example step modules (@raincatcher-examples/*)
External modules build by RainCatcher users and custom code in reference applications

1.2. Process Management

RainCatcher focuses mainly on digitalizing business process by including set of the modules responsible for the process management to the user applications.

Main features of the Process Management modules:

Creation customizable processes (called workflows)
Creation of process instances called workorders
Creation workflows using steps
Providing customization to the process using step definitions
Integrating workflows and workorders into the mobile application
Providing number of predefined steps that can be used for any business needs

Process Management framework can be extended by Step Definitions which are responsible for wrapping business processes into single reusable units. For more technical information about Step Definitions please refer to the Process Management Guide.

1.2.1. Process Management overview

Developers can extend RainCatcher solution by providing Step Definitions. Are provided as one more more npm modules that needs to be added to both mobile and portal applications. All included steps will be available as library that can be accessed and used to build workflows in end user applications.

Portal administrators can build workflows which containing ordered Steps that each mobile operator needs to complete.

Workflows can be instantiated as Workorders which will contain specific details and be assigned one of the field operators. Once workorder is created it will be populated in the mobile field operator application.

1.3. RainCatcher Reference Material

1.3.1. Highlighting RainCatcher Areas of Focus

Table 1. Areas of Focus
Area	Focus
Framework	A generic and developer friendly framework (set of classes) for building mobile and website Workforce Management solutions
Modules	Modules specific to RainCatcher, for example: signature-module, scheduler
Integrations	Integrations to satisfy RainCatcher needs, for example: authentication, storage, offline capabilities, server side synchronization
User Interface	Graphical User Interfaces are implemented in AngularJS and Angular

1.3.2. RainCatcher at a Technical Level

Node.js used for server side code
Hybrid mobile development using Cordova
Object Oriented approach (classes and interfaces)
Focus on module reuse and flexibility
Incorporates open-source technologies: MongoDb, Keycloak, Passport.js and others.

1.3.3. Identifying RainCatcher Repositories

RainCatcher is available in three github repositories:

Table 2. RainCatcher Repositories
Repository	Description
raincatcher-mobile	Contains the Mobile application.
raincatcher-portal	Contains the Portal application.
raincatcher-server	Contains the Server application.
raincatcher-docs	Repository contains RainCatcher documentation
raincatcher-core	Contains the contribution repository of the supported modules and server.
raincatcher-angularjs	Contains the contribution repository angularJS user interface for the mobile and portal

1.3.4. Differentiating RainCatcher from 'Tech Preview'

The RainCatcher project was originally called Tech Preview. The Tech Preview codebase is now deprecated and is accessible at Tech Preview Documentation. The main differences between RainCatcher and Tech Preview are:

Mediator pattern is removed from RainCatcher
Tech Preview is not object oriented
RainCatcher is written in Typescript

Getting Started with the RainCatcher Applications

2. Running the RainCatcher Applications on a Local Machine

Get started by running RainCatcher applications on your local machine. Follow these steps and use the public NPM Registry to set up the RainCatcher applications that contain sample Steps, Workflows, and Workorders.

Prerequisites

The following must be installed on your system:

Node and npm (tested version: 6 LTS)
git
MongoDB
Redis

You must have access to GitHub to install the RainCatcher applications.

Cloning the Git Repositories

Clone the Git repositories as follows:

git clone git@github.com:feedhenry-raincatcher/raincatcher-server.git
git clone git@github.com:feedhenry-raincatcher/raincatcher-mobile.git
git clone git@github.com:feedhenry-raincatcher/raincatcher-portal.git

The master branch of each Git repository provides the latest version. Previous versions have the release-* tag. For example, run the following command to checkout version 1.0.0:

cd raincatcher-server/
git checkout release-1.0.0

Installing Repository Dependencies

Run the npm install command in each repository to download the dependencies. For example, download dependencies for the Core server as follows:

cd raincatcher-server/
npm install

Starting MongoDB and Redis

Ensure MongoDB and Redis are running on your local machine. For more information, see:

MongoDB: Start MongoDB Processes
Redis: Starting Redis

Starting the Core Server

Run the npm run start command to start the Core server as follows:

cd raincatcher-server/
npm run start

Note	After you start each RainCatcher application, it continues to run in the terminal. Closing the terminal stops the application. You must start the Portal and Mobile applications from separate terminals.

Starting the Portal and Mobile Applications

Start the Portal application first, as follows:

cd raincatcher-portal/
npm run start

Next, start the Mobile application as follows:

cd raincatcher-mobile/
npm run start

The Portal and Mobile applications automatically open in a browser. If they do not open automatically, access them at the following URLs:

Portal application: http://localhost:9002/?url=http://localhost:8001
Mobile application: http://localhost:9003/?url=http://localhost:8001

2.1. Credentials for the Portal and Mobile Applications

The Portal and Mobile applications contain sample Steps, Workflows, and Workorders that you can use to evaluate workforce management processes.

Application Username Password

Application	Username	Password
Portal	`max`	`123`
Mobile	`trever`	`123`

Portal

max

123

Mobile

trever

123

For all available users, see: users.json

Note	Users are valid for both passport and Keycloak auth providers.

As a next step, you can:

Use the sample Workflows and Workorders. See Learn to Use Workflows and Workorders.
Create your own business logic. See Building a Workflow.

3. Learning to Use Workflows and Workorders

RainCatcher applications streamline process management with reusable objects called Workflows and Workorders.

A Workflow is a set of steps that end users follow to complete a process. Administrators create Workflows with the Portal application.
A Workorder is an instantiation of a Workflow that contains specific details. Administrators can assign Workorders to end users. End users access Workorders in the Mobile application.

In the following section, you can use the sample content in the RainCatcher applications running on your local machine.

3.1. Working with the Portal Application

The Portal Application is used by an administrator to essentially manage the Workorder.

Prerequisites

Ensure you have:

Access to the Portal Application

Creating a Workflow

Login as an administrator to the Portal Application
In the navigation panel on the left, click Workflow
To create a new Workflow, click NEW Workflow
1. This will bring you to the Create Workflow screen
Add a title to the Workflow
Click CREATE Workflow to navigate to the Add Step screen
Give the Step a name and then select a Step Type from the list
1. All Steps, default and custom, will appear in this list
To submit the new Step to the Workflow, click ADD STEP

Note	Use the Add Step screen to add additional steps to the Workflow.

Working with a Workflow

To make updates to a Workflow or to delete a Workflow, use the the pencil (to update) or the trash (to delete) icons in the top right side of the screen. Updating a Workflow will increment the version of the Workflow however, do note that any existing Workorders that are based on the original Workflow will continue to use the older version of the Workorder. Naturally, a new Workorder can be created and based on the incremented Workflow.

A Step can be modified or deleted. Use the circle with the plus icon to create a new Workflow. This new Workflow can be used to create or update Workorders.

Refresh the screen to see the new Workflow appearing in the list in the center panel. You can access existing Workflows by selecting them in the list in the center panel. The options presented for editing a Workflow are the same for the creation of a Workflow.

Creating a Workorder

A Workorder is an individual instance of a Workflow and it can be assigned to an end user.

Login as an administrator to the Portal Application
In the navigation panel on the left, click Workorder
To create a new Workorder, click NEW Workorder to open a form for completion
Add data to the form and when complete, click CREATE Workorder
1. Once the Workorder is created, it will sync with an end user’s account and is now accessible on the Mobile Application
The page will refresh and the new Workorder will appear in the list on the middle panel
To edit a Workorder assigned to an individual end user, select the Workorder from the center panel list

Working with a Workorder

To update a Workorder’s title, assignee or Workflow, use the the pencil icon. The updates will sync to the end user’s Mobile Application after UPDATE Workorder is clicked. To access the Workorder screen, click the circle with a plus icon on the bottom right side of the screen.

3.2. Working with the Mobile Application

The Mobile Application is used by an end user to interact with Workorders that have been assigned to them.

When an end user is logged in, they are presented with the Workorders screen. To log out, click the menu icon in the top left hand side of the screen. This will open a sidebar with options, one being the option to log out.

Prerequisites

Ensure you have:

Access to the Mobile Application

Completing a Workorder

Log into the Mobile Application as an end user
1. The end user will see the Workorders assigned to them
Select a Workorder to view the first Step in the Workorder:
To add data to the Workorder, click START WORKFLOW and add the necessary data
To move to the next Step, click CONTINUE
When all Steps have been completed, click CONTINUE on the bottom of the screen to proceed to the Summary screen
Once you are on the Summary screen, the Workorder has been completed
To return to the Workorder home screen and view the updated status of the Workorder, click the Menu icon in the top left hand side and return to the Workorders screen.
The Workorder is now marked with a green tick which means it was successfully completed.

Once the Mobile Application has synced with the Portal Application, a full summary of the completed Workorder is available for viewing on the Portal Application.

3.3. RainCatcher Application Reference Material

3.3.1. Credentials for the Mobile and Portal Application

Table 3. Credentials for the *Mobile* and *Portal* Starter Applications
Application	Username	Password
Mobile	`trever`	`123`
Portal	`max`	`123`

For complete list of users available by default see gitub repository

3.3.2. Structure for the Mobile and Portal Starter Applications

The UI Starter Applications present a consistent directory structure that can serve as a sensible base for customizations.

The following list highlights the function of the main folders:

src/app: Main folder containing the logic for the application. The app is mainly concerned in providing the setup and configuration values for the RainCatcher and AngularJS modules that are used by it.
src/app/initialization: Contains configuration values and initial bootstrapping code for the AngularJS application.
src/app/services: Contains AngularJS services that are utilized by the RainCatcher modules to retrieve data. The app has the opportunity to provide an implementation that utilizes any technology for data retrieval, including static fixtures for testing.
src/res: Contains resource files (mostly bitmaps) that are used by the UI. These are also included in the various resolutions expected by the native apps.
src/sass: Contains app-wide SAAS files that are compiled by the build pipeline.
scripts/: Contains auxiliary scripts for the development environment.
www/: Generated directory containing the output files of the local build process.

Building a Workflow

4. Building Your First Workflow Step

Steps are internal part of the RainCatcher.

The following guide describes structure of the Step and some basic principles required to build one. A basic knowledge of AngularJS is required to build a Workflow Step.

4.1. Structure of a Step

Steps are divided into two linked categories, the AngularJS Module and the Step Definition.

4.1.1. Module

Modules can contain one or more AngularJS directives for rendering Steps in the Portal and Mobile applications. RainCatcher Steps use AngularJS directives to build a user interface as part of executing a Work Order. Each Step is divided into two directives:

Table 4. A Step’s Directive
Directive	Description
Edit Section directive (Form)	The Edit Section is displayed when a workflow is executed and allows users to edit information - typically this would be a form. The Edit Section consists of the a html template and a directive.
Preview Section directive (View)	The Preview Section is displayed as a summary when a workflow has been completed. The Preview Section consists of a html template and a directive.

4.1.2. Definition

A Definition contains the Step Definition which outlines the properties such as the name and the description of a Step, for the Work Flow in the Portal application. Each Step requires a Definition. and the definition.json file can contain a Definition of a single Step or an array of Definitions with the size corresponding to the number of Steps in the Step Package. The following is an example of a Definition:

Example:

[
    {
        "code": "base-form",
        "name": "Base Form",
        "description": "base form used to for steps",
        "templates": {
            "form": "<base-form></base-form>",
            "view": "<base></base>"
        }
    }
]

The Module and the Definition are exported to be exported from the Step Package, which is a regular NodeJS package. The following is an example of a Step Package’s main javascript file:

Example:

module.exports = {
  ngModule: require('./angular-module'),
  // Definition for this step that is being used in portal
  definition: require('./definition.json')
};

4.2. Creating new Step Package

A Step Package can be created manually from a template or by using the RainCatcher Step Generator.

4.2.1. RainCatcher Step Generator

The RainCatcher Step Generator provides a way to generating a Step Package automatically by answering a simple set questions via a command line interface.

The generated Step Package will contain sample UI directives that should be modified for the users' needs.

It is available as the generator-rcstep NPM package.

4.2.2. Template

Instead of utilizing the Step Generator, developers can use a provided Step Package template:

When developing a custom Step Package, clone the step-template sample repository and make modifications to the cloned repository.

4.2.3. Modifications

For more information about modifying a Step and importing a Step into the Portal and Mobile applications, see the Step Template’s README

5. RainCatcher's Packaged-Steps

A Packaged-Step is a Step with basic functionality and comes as standard with the RainCatcher Application. A Packaged-Step is designed to be versatile so that it can be used with a wide range of Workflows.

5.1. The Signature Step

The Signature Step is a Packaged-Step and it is used to capture a signature. A user inputs their signature through the UI and it is stored as an image. A user uses their finger or stylus, for example, to input their signature on a mobile device (the mobile device must have a touch screen). The captured signature is displayed as part of a completed Workorder.

Like all Steps, a Signature Step is made up of a module and a definition.

5.2. Packaged-Step Roadmap

The following list displays the Packaged-Steps that are on the RainCatcher roadmap:

Plugable authentication
Image capture
Geolocation
Internal Messaging and 3rd party Messaging
Mobile Forms
Real-time Data Access
Integration of sensor data

Top Level Applications Overview

6. Understanding the RainCatcher Application

The RainCatcher Application consists of three components:

A Mobile Application for end users
A Portal Application for administrator users and accessed through a web browser
A Cloud Application for backend server functionality (there is no user interface)

An administrator can define a business process or procedure via a custom Workflow. A Workflow contains one to many Steps. A Workorder is an individual instance of a Workflow and it (the Workorder) is assigned to an end user (or to many end users) as a job that they are to complete. An end user can view their Workorder via a Mobile Application. An administrator can manage the Workorder via the Portal Application.

Note	The RainCatcher Application is supplied with demo users and data, and both are used to assist a User when demonstrating RainCatcher functionality.

The Portal Application is used by an administrator to essentially manage the Workorder. An administrator can view, edit and assign a Workorder and also create a new Workflow. When an administrator logs into the Portal Application, there are two separate areas that they can access on the Portal Application: the Workflow and the Workorder.

Table 5. Available Areas on the Portal Application
Area	Functionality
Workflow	Create, read, update, delete and list operations can be executed against a Workflow. Manage Workflows and add additional Steps to an existing Workflow.
Workorder	Create, read, update, delete and list operations can be executed against a Workorder. Manage Workorders by assigning them to individual end users.

Important

Once a Workorder has been created, any Workflows based in this Workorder become unchangeable, that is, the sequence of Steps that make up the Workorder cannot be changed.

7. RainCatcher Supported Modules

This section describes RainCatcher’s core list of modules. The latest list of modules is found at RainCatcher Modules.

Table 6. RainCatcher Supported Modules
Module	Description
@raincatcher/express-auth	The RainCatcher Security Interface is used to apply authentication and authorization, used in conjunction with a security provider chosen by you.
@raincatcher/auth-passport	The RainCatcher implementation of Passport.js which is the default security module for Mobile and Portal applications.
@raincatcher/datasync-cloud	The RainCatcher Cloud implementation of fh-sync used in conjunction with @raincatcher/datasync-client. This is used to sync data between the Cloud and Mobile applications.
@raincatcher/datasync-client	The RainCatcher Client implementation of fh-sync used in conjunction with @raincathcer/datasync-cloud. This is used to sync data between the Cloud and Mobile applications.
@raincatcher/wfm	The RainCatcher Work Flow Management module which allows developers to map a business process into an organized set of tasks to suit a businesses needs.
@raincatcher/wfm-rest-api	The RainCatcher Work Flow Management API module exposes express API endpoints for Work Flow Management Objects.
@raincatcher/wfm-user	The RainCatcher Aggregates all user operations for RainCatcher modules.
@raincatcher/wfm-demo-data	This is a sample module containing static data definitions and when running, it allows the user to see the RainCatcher demo project example.

8. Mobile Application

Mobile AngularJS based application that provides interface for field operators. Developers who base their solution on RainCatcher can extend it by providing additional UI elements, themes and functionalities.

8.1. Running on a browser

After installing all dependencies, run these commands to test this application on a local browser:

npm start

grunt serve:local --url=http://localhost:8001

The url parameter should be the root of the API server application running the api endpoints. See server side documentation for information how to run server

8.2. Repository Structure

Table 7. RainCatcher Mobile Application Repository Structure
Folder	Description
src/app	Main folder containing the logic for the application. The app is mainly concerned in providing the setup and configuration values for the RainCatcher and AngularJS modules that are used by it.
`src/app/services`	Contains AngularJS services that are utilized by the RainCatcher modules to retrieve data. The app has the opportunity to provide an implementation that utilizes any technology for data retrieval, including static fixtures for testing.
`src/app/app.js`	Has a small AngularJS controller for displaying a template before data is loaded from the backend server.
`src/sass`	Contains app-wide [Sass](http://sass-lang.com/) files that are compiled by the build pipeline.
`src/app/initialization`	Contains configuration values and initial bootstrapping code for the AngularJS application.
`src/res`	Contains resource files (mostly bitmaps) that are used by the UI. These are also included in the various resolutions expected by the native apps.
`www/`	Generated directory containing the output files of the local build process. This directories contents are what is served by the local development web server.

8.3. Running on a Device Emulator

To run this application on a device emulator, setup the appropriate native SDKs and run the app through the following commands:

Change config.xml content field to point to running application server Provide valid url value.

<content src="index.html?url=http://localhost:8001" />
Build Android

cordova prepare cordova build android --verbose
Push apk to your device

cordova run android

See the [Apache Cordova project documentation](https://cordova.apache.org/docs/) for details on how to configure your environment for running applications on a device emulator.

9. Portal Application

Portal AngularJS based application that provides interface for process management. Developers who base their solution on RainCatcher can extend it by providing additional UI elements, themes and functionalities.

9.1. Running on a browser

After installing all dependencies, run these commands to test this application on a local browser:

npm start

grunt serve:local --url=http://localhost:8001

The url parameter should be the root of the API server application running the api endpoints. See server side documentation for information how to run server

9.2. Repository Structure

Table 8. RainCatcher Portal Application Repository Structure
Folder	Description
src/app	Main folder containing the logic for the application. The app is mainly concerned in providing the setup and configuration values for the RainCatcher and AngularJS modules that are used by it.
`src/app/services`	Contains AngularJS services that are utilized by the RainCatcher modules to retrieve data. The app can utilize any technology for data retrieval, including static fixtures for testing.
`src/app/home`	Has a small AngularJS controller for displaying a temporary template before data is loaded from the backend server.
`src/app/sass`	Contains app-wide [Sass](http://sass-lang.com/) files that are compiled by the build pipeline.
`www/`	Generated directory containing the output files of the local build process. This directories contents are what is served by the local development web server.

10. Server Application

The Server Application is a Node.js server that provides APIs for mobile and portal clients. A Developer can use RainCatcher as a base solution and can extend it by providing additional API and using custom plugins. The Server Application has a modular structure, that is, all functionality and integrations are imported as modules and can be removed or replaced at a later point.

10.1. RainCatcher Server

Active Release Version

The Active Release version contains all resources including javascript and other build artifacts. https://github.com/feedhenry-RainCatcher/RainCatcher-server master version always contains the most recent release.

Note
You can refer to a specific release version by using tag.
Active Development Version

The Active Development version is used by RainCatcher contributors and contains only TypeScript source code. https://github.com/feedhenry-RainCatcher/RainCatcher-core/blob/master/demo/server

10.2. Server-side Application Development Guide

To launch the Cloud Application, execute npm run start:ts, this runs the Server Application from its TypeScript sources.

To start debugging, execute npm run startDebug.

Note	Both commands use a tool called `ts-node` and this runs a process without compiling Typescript source code.

To run the code using Node.JS, ensure you compile the code first:

npm run build
npm run start

When compiling source code, the ts-node command uses compiled Javascript files. To clean compiled Javascript files, execute npm run clean

10.2.1. Prerequisites for a Local Environment

Note	If you run the RainCatcher solution as part of the RHMAP platform, this prerequisites does not apply.

mongodb installed and running on port 27017 | URL controlled by process.env.MONGO_CONNECTION_URL and config-{env}.json file
redis installed and running on port 6379 | URL controlled by process.env.REDIS_CONNECTION_URL and config-{env}.json file

10.2.2. Server-side Configuration

The Server Application offers different configuration profiles depending on the target application deployment.

config-dev.js (for developer/local setup - used by default)
config-prod.js (for production uses)

You can also add another profile name using the config-profile-name.js pattern.

Profiles can be changed using process.env.CONFIG_PROFILE variable, for example:

// use production profile.
process.env.CONFIG_PROFILE === 'prod'
// it will load config-prod.js file in top level application

By default, the server will load a development profile. All configuration parameters are documented directly in Javascript file. Developers building their solution on top of the RainCatcher are free to extend the configuration.

10.2.3. Structure

modules - this folder contains a sample implementation for RainCatcher integrations, for example, sync or security. Developers are free to modify and tweak these.
user-routes - contains custom routes (non RainCatcher specific)
app.js - the main application code that mounts express routes

10.2.4. Configuring Custom Query Parameters for Mobile Clients

A Mobile client that is based on the sync framework might not require all WorkOrders in order to operate.

To save on local memory usage, data traffic and also to improve performance, additional filters can be added to limit those.

In the sample implementation, WorkOrders whose status are complete are no longer sent to mobile clients after two days of their completion. This is configured via the sync.daysToExcludeCompleteWorkorders configuration key. It illustrates a way to include a relatively complex MongoDB query filter into the chain that is used by the list handler for the sync framework.

RainCatcher Integrations

An integration is the use of existing Open Source projects to solve specific needs or provide extra functionality for RainCatcher.
RainCatcher has a number of intergrations that leverage other Open Source projects for their expertise in paticular fields and particular important features.
These integrations enable the inclusion of domain expertise in, for instance, the areas of authentication, authoriztion and security, and data synchronization in RainCatcher.

11. Sync

11.1. Introducing the RainCatcher Datasync Module

The RainCatcher Datasync Module is an implementation of the FeedHenry Sync Framework. Datasync is made up of two modules, the Cloud module and the Client module. The primary function of Datasync is to synchronize data, for example, a workorder, between the Client Application (mobile) and the backend server.

Datasync key features:

Allows mobile applications to use and update data while being offline
Provides a mechanism to manage bi-directional data synchronization from multiple clients into back-end data stores via the server.
Allows data updates (that is, deltas) to be distributed from the server to connected clients
Provides facilities for managing data collisions from multiple updates in the cloud

For advanced usage of the Datasync module, see the Sync Documentation

11.1.1. Datasync Cloud

The Datasync Cloud is a wrapper for the FeedHenry datasync server. The Datasync Cloud creates a server side service that allows clients to synchronize offline data to a preferred back-end data store. By default, the Cloud module utilizes a MongoDB database back-end for storing the client data.

For instructions on how to implement the Datasync Cloud, see README

To view an example, see the Datasync Cloud example.

11.1.2. Datasync Client

The Datasync Client is based on the sync.js client. In order to work, the Datasync Client requires the Datasync Cloud to be running on an Express.js based web server. The Data Synchronization Library can be used for offline storage of the client’s data.

For instructions on how to implement the Datasync Client, see README

To view an example, see the Datasync Client App example.

12. Security introduction

12.1. Introducing RainCatcher Security Features

RainCatcher Security is built around a Security Interface which abstracts itself from all RainCatcher security libraries. RainCatcher allows you to integrate a custom security solution. RainCatcher also provides two out-of-the-box security implementations called Keycloak and Passport.js.

Keycloak and Passport.js both provide server side authentication and authorization. Keycloak and Passport.js implementations are interchangeable since they implement the RainCatcher Security Interface, and thus can operate with all modules and also any of the reference applications.

12.1.1. Authorization using the Security Interface

If you build a custom security implementation, the endpoints are secured in the same way as the Keycloak and Passport.js implementations.

If you choose to build a custom security implementation, you will need to:

Import the EndpointSecurity interface from the Passport.js implementation
Implement the interface in the custom security implementation
Use the protect method to guard routes (the security permissions being role based)

Note	All express routes outside of RainCatcher modules must implement the EndpointSecurity Security Interface.

12.1.2. Introducing Passport.js

Passport.js is a lightweight authentication middleware solution for Node.js and can be bundled into an existing Node.js server. Passport.js offers a comprehensive set of strategies that support authentication using a username and password, existing social media and other 3rd party accounts, and more.

For more information, see passportjs.org.

The PassportAuth Module is RainCatcher’s implementation of Passport.js and is the default authentication and authorization module for RainCatcher.

12.1.3. Introducing Keycloak

Keycloak is a complete identity management solution. It extends standard authorization and authentication functionality, and comes with all the overheads involved in running a separate server. Red Hat recommends using Keycloak in production to avail of the many features available for enterprise security including:

Single-Sign On
User Federation
Client Cert Authentication
2FA with OTP
User Session Management
Auditing
Brute Force Detection

Note	Keycloak is not available by default when running the default RainCatcher solution.

12.1.4. Choosing Passport.js or Keycloak

Passport.js:

If you want a standalone Node.js based authentication solution that is ready out-of-the-box, choose Passport.js.

Keycloak:

If you want a full identity management solution that can be tied into existing SAML/LDAP/SSO solutions, choose Keycloak.

13. Using Keycloak

13.1. Introducing Keycloak within RainCatcher

Keycloak is a complete identity management solution.

The RainCatcher demo application allows for authentication and access management using Keycloak however, Keycloak is not the default authorization and authentication module for RainCatcher.

The configuration for Keycloak’s integration is found within the demo application.

Note	To configure your own instance of Keycloak, see the Keycloak documentation Getting Started Guide.

13.1.1. Keycloak Reference Material

Credentials for the Keycloak Admin Console

Table 9. Keycloak Admin Console Credentials
Username	Password
admin	admin

13.2. Introducing the Security Strategy for Keycloak

The RainCatcher Keycloak Security Strategy describe the security aspects for Keycloak and cover areas such as:

Understanding Keycloak Terminologies
Understanding Keycloak Client Adapters
Understanding Keycloak Session Management
Defining Keycloak Access Control
Defining Keycloak Password Storage
Keycloak Authentication
Keycloak Authorization

13.2.1. Defining the Security Strategy for RainCatcher Keycloak

Understanding Keycloak Terminologies

There are some key concepts and terminologies to be aware of before using Keycloak. For more information on these key concepts and terminologies, refer to the Keycloak Core Concepts documentation.

Understanding Keycloak Client Adapters

RainCatcher uses the Node.js Client Adapter for the RainCatcher server and the Javascript Client Adapter for the RainCatcher mobile and portal.

For more information on the Node.js Client Adapter, see the Keycloak Node.js Adapter For more information on the Javascript Client Adapter, see the Javascript Adapter documentation.

Understanding Keycloak Session Management

The express-session module provides session management functionality and the management of sessions is performed on the Keycloak server For more information on express-session, see express-session.

Defining Keycloak Access Control

Keycloak provides role-based access control and is configured on the Keycloak server.

See the Protect Express Routes section on how routes are protected in the application. For more information on protecting express routes, see the Keycloak Node.js Adapter.

Defining Keycloak Password Storage

Keycloak uses the PBKDF2 algorithm for password hashing by default. Keycloak also provides enforced password policies from the server.

For more information on server administration topics, see Keycloak documentation on identity-broker and user federation.

Keycloak Authentication

Keycloak has a wide variety of authentication mechanisms available. For more information, refer to the Keycloak Authentication Documentation.

Keycloak Authorization

Authorization is fully documented in the Keycloak Authorization Documentation.

13.3. Enabling Keycloak

Important

Enabling Keycloak requires the disabling of PassportAuth.

13.3.1. Prerequisites

Ensure you have completed Getting Started
A Docker installation (tested with version: <latest version>)
Knowledge of Keycloak terminologies. See the Understanding Keycloak Terminologies section for more information.

Note	If you choose to run your own Keycloak instance, ensure that a Keycloak realm is setup for the RainCatcher applications to use. For more information, see Setting up a Keycloak Realm section.

13.3.2. Running the Keycloak Docker Image

Open a terminal and run the Keycloak Docker image

docker run -p 8080:8080 feedhenry/raincatcher-keycloak

For more information about the Keycloak Docker Image, see the Keycloak README.md.

Important

The Keycloak realm setup included in this docker image is configured for local development only. Ensure that you provide proper client configurations for production environments. See Keycloak Configuration for Production Environments for more information.

13.3.3. Setting up a Keycloak Realm

Note	This step is only valid if you choose to run your own Keycloak instance or if you prefer to create your own Keycloak realm. The Keycloak Docker image comes with a pre-configured RainCatcher realm therefore it does not need to be manually configured.

The Keycloak realm can be configured in two different ways:

Use the existing Keycloak realm configuration and import it to your own Keycloak instance.
Create your own Keycloak realm.

Importing the Keycloak Realm Configuration

Download the RainCatcher realm configuration
Login to the Keycloak admin console. See Accessing the Keycloak Admin Console for more information.
Click 'Add Realm'
Import the RainCatcher realm settings you downloaded
Click 'Create'

This will create the demo RainCatcher realm which includes the setup for three different clients: raincatcher-portal, raincatcher-mobile and raincatcher-cloud.

Important

The provided RainCatcher realm configuration is only configured for local development. Ensure that you provide proper client configurations for production environments. See Keycloak Configuration for Production Environments for more information.

Creating your own Keycloak Realm

Warning

Creating your own Keycloak Realm requireds an advanced understanding of Keycloak and its Node.js and Javascript Adapters.

See the Keycloak documentation on realms for more information on how to create a new realm within a Keycloak instance.

The realm must adhere to the following configurations in order to use it with the RainCatcher applications:

Realm settings
```
Required SSL: external
```

Client settings

The realm must have three different clients for each of the RainCatcher applications: Server, Portal and Mobile.

Server Client:

Enabled: true
Client Protocol: openid-connect
Access Type: bearer-only

Portal Client:

Enabled: true
Client Protocol: openid-connect
Access Type: public
Standard Flow Enabled: true
Valid Redirect URIs: [Ensure that this is configured with the correct URL patterns]
Web Origins: *

Mobile Client:

Enabled: true
Client Protocol: openid-connect
Access Type: public
Standard Flow Enabled: true
Valid Redirect URIs: [Ensure that this is configured with the correct URL patterns]
Web Origins: *

For more information on the configurations above, see the Keycloak OpenID Connect configurations documentation.

User settings
- Ensure that each user has the following attribute fields:
  - id: Used as an identifier for the user.
  - avatar: A link to the user’s avatar image to be displayed on the user panel (Used in the mobile application).
  - name: The name of the user to be displayed on the user panel (Used in the mobile application).
- For more information on user attributes, see the Keycloak user attributes documentation.
- Ensure that each user has the appropriate roles. For more information on roles, see Defining Keycloak Access Control.

13.3.4. Adding Keycloak Configuration

Adding Keycloak Configuration in the Server Application

Choose which configuration file to edit:

Table 10. Keycloak Configuration File

Area File Name File Location

Development

config-dev.js

/config-dev.js

Production

config-prod.js

/config-prod.js

Table 10. Keycloak Configuration File
Area	File Name	File Location
Development	config-dev.js	/config-dev.js
Production	config-prod.js	/config-prod.js

Open the configuration file and fill in the missing field values for realm, auth-server-url and resource:

"keycloakConfig": {
  "realm": "raincatcher",
  "bearer-only": true,
  "auth-server-url": "http://localhost:8080/auth",
  "ssl-required": "external",
  "resource": "raincatcher-cloud",
  "use-resource-role-mappings": true
}

Note

Ensure that the realm, auth-server-url and resource values correspond to your client configuration within your realm. Ensure that the values for the fields bearer-only, ssl-required and use-resource-role-mappings are not changed. For more information, see the Keycloak Node.js Adapter documentation.

Important

Filling in the realm, auth-server-url and resource fields in the keycloakConfig also enables Keycloak in the server application

Keycloak Configuration in the Mobile Application

The Keycloak Configuration for the mobile application is already filled in. This may be customized by changing the realm, url and clientId fields within the application’s config.json to values which corresponds to your own client configuration.

Note	Ensure that the values for the rest of the fields apart from the realm, url and clientId are not changed.

For more information on Javascript Adapter configurations, see the Keycloak Javascript Adapter documentation.

Keycloak Configuration in the Portal Application

The Keycloak Configuration for the portal application is already filled in. This may be customized by changing the realm, url and clientId fields within the application’s config.json to values which corresponds to your own client configuration.

Note	Ensure that the values for the rest of the fields apart from the realm, url and clientId are not changed.

For more information on Javascript Adapter configurations, see the Keycloak Javascript Adapter documentation.

13.3.5. Enabling Keycloak on the RainCatcher Applications

Enabling Keycloak on the Server Application

Fill in the Keycloak configuration in the server application.
At this point, the routes are protected by Keycloak.

See Adding Keycloak Configuration in the Server for more information.

Enabling Keycloak on the Mobile Application

Open the file app.js in location /src/app/
Disable Passport.js and require Keycloak
```
  require('./keycloak')
```

Note	Ensure that Passport.js is disabled by not requiring ./passport and @raincatcher/angularjs-auth module.

Enabling Keycloak on the Portal Application

Open the file main.js in location /src/app/
Disable Passport.js and require Keycloak
```
  require('./keycloak')
```

Note	Ensure that Passport.js is disabled by not requiring ./passport.

13.3.6. Accessing the Keycloak Admin Console

To access the Keycloak Admin Console, navigate to http://localhost:8080/auth/

See Credentials for the Admin Console section to see the credentials used by the Keycloak docker image.

13.3.7. Keycloak Configuration for Production Environments

The provided Keycloak realm is configured for local development only. Ensure that you provide proper configurations for production environments.

Client Configurations

The existing Keycloak realm provides three clients for the server, mobile and portal applications. These three clients are using OpenID Connect authentication protocol. Ensure that these clients are configured properly to be secure for production environments.

User Configuration

The existing Keycloak realm is configured with sample users. Ensure that you provide proper user and user storage configuration when moving to production environments.

13.4. Implementing Keycloak

13.4.1. Prerequisites

Ensure you have completed Getting Started
A Keycloak server

13.4.2. Using Keycloak to secure Express endpoints

Note	The RainCatcher applications uses the Keycloak Node.js and Javascript Client Adapters. For more information, see Understanding Keycloak Client Adapters.

13.4.3. Implement the EndpointSecurity Interface

Import the EndpointSecurity Interface.

import { EndpointSecurity } from '@raincatcher/express-auth';

Implement the EndpointSecurity interface

See the sample Keycloak implementation of the EndpointSecurity interface as a reference on how this can be implemented.

13.4.4. Enable Keycloak Security Middleware for Route Protection

Instantiate Keycloak and install the Keycloak middleware to your express app.

This is implemented in the Keycloak implementation within the init function.
Apply this init which returns the Keycloak security middleware to be used for protecting express routes.
```
import { init as initKeycloak } from './keycloak';
...
const securityMiddleware = initKeycloak(app);
```
See the security setup as a reference on how this can be applied.

For more information on how to setup the Keycloak Node.js Adapter, see the Node.js Adapter documentation.

13.4.5. Protect Express Routes

The following code is an example of how to protect routes:

// This implementation supports role based authentication
app.use('/test', securityMiddleware.protect(role));

The RainCatcher server application includes configurable admin and user roles within its security configuration. This is used by the server application security setup. See the security setup as a reference on how routes can be protected.

For more information on protecting express routes, see the Node.js Adapter documentation.

14. Using Passport.js

14.1. Introducing the RainCatcher PassportAuth Module

The RainCatcher PassportAuth module is RainCatcher’s implementation of Passport.js. It is the default authentication and authorization module for RainCatcher.

PassportAuth provides pluggable authentication using strategies. Passport.js offers a comprehensive set of strategies that support authentication using a username and password, existing social media and other 3rd party accounts, and more.

PassportAuth provides:

Access Control of Express routes
Authentication using the default strategies
Express session middleware using express-session

14.2. Introducing the Security Strategy for PassportAuth

The RainCatcher PassportAuth Security Strategy describes the security aspects for PassportAuth and covers areas such as:

Understanding Session Management
Defining Access Control
Defining Password Storage
PassportAuth Authentication
PassportAuth Authorization
Customizing a Strategy
PassportAuth Demo Users and Access Roles
PassportAuth Login Pages

14.2.1. Defining the Security Strategy for RainCatcher PassportAuth

Understanding PassportAuth Session Management

The express-session module provides session management functionality for PassportAuth. For more information, see express-session.

Defining PassportAuth Access Control

Routes are protected by PassportAuth which provides role based access control. AuthService is an an implementation of PassportAuth. For more information, see the following example:

app.get('/testAdminEndpoint', authService.protect('admin'), (req: express.Request, res: express.Response) => {
  res.json({ routeName: '/testAdminEndpoint', msg: 'authorized to access admin endpoint' });
});

Note	Demo roles are defined in users.json.

Defining PassportAuth Password Storage

The PassportAuth user data is stored in a User Repository. Make sure that the User Repository Interface is implemented in order to point PassportAuth to a datasource.

PassportAuth Authentication

RainCatcher authentication is handled by the server using the user’s unique username and password combination. The PassportAuth service has a default authentication strategy based on Passport.js's local and JWT strategies.

PassportAuth uses authenticate middleware for cookie based authentication. To access express routes, a user must login using their credentials. A cookie containing a user session key is used to authenticate and authorize a user upon each request to the server.

Note	In the Demo Applications, the cookie login route has an authenticate() method that checks user credentials against the stored credentials in the users.json file. It also checks the user’s role against the role on users.json.

PassportAuth uses authenticateWithToken for token based authentication. To access express routes, a user must login using their credentials. A generated JSON web token (JWT) and the user’s profile is sent to the client upon successful authentication.

Note	The JWT token needs to be included in every subsequent request after a successful login as part of the Authorization header

For more information, see the PassportAuth example.

PassportAuth Authorization

Authorization is supported by protect middleware that validates a session or a JWT token depending on the Passport.js strategy used and checks if the user has the required role.

Customizing a Strategy

The default strategies for the PassportAuth module implements the Passport.js local and JWT strategy. To customize the existing strategies, override the PassportAuth.setupCookie or PassportAuth.setupToken method. To use a different security strategy that is supported by Passport.js, override the PassportAuth.init method.

PassportAuth Demo Users and Access Roles

PassportAuth is by default integrated with the Demo application and contains sample users and access roles which are defined in the demo data JSON file.

PassportAuth Login Pages

For more information on how to customize the login pages used by PassportAuth, see Customizing PassportAuth Login UI section.

14.3. Enabling PassportAuth

Important

Passport.js is the default auth provider for the RainCatcher applications and is enabled by default in all of the RainCatcher applications. The following steps are only valid if PassportAuth has been disabled to enable Keycloak.

14.3.1. Prerequisites

Ensure you have completed Getting Started

14.3.2. Enabling PassportAuth on the RainCatcher Applications

Important

In order to enable PassportAuth in the RainCatcher applications, Keycloak must be disabled.

Enabling PassportAuth on the Server Application

Ensure that the Keycloak configuration in the server application is not filled in.

There are two configuration files available in the server application: config-dev and config-prod.

Ensure that the values for realm, auth-server-url and resource properties are empty within the Keycloak configuration.
```
  "keycloak": {
    "realm": "",
    "bearer-only": true,
    "auth-server-url": "",
    "ssl-required": "external",
    "resource": "",
    "use-resource-role-mappings": true
  }
```

Enabling PassportAuth on the Portal Application

Open the file main.js in location /src/app/
Disable Keycloak and require PassportAuth
```
  require('./passport')
```

Note	The login page used by PassportAuth in the portal application is served by the server application. For more infromation on how to customize this login page, see the Customizing PassportAuth Login UI section.

Enabling PassportAuth on the Mobile Application

Open the file app.js in location /src/app/

Disable Keycloak and require PassportAuth

  require('./passport'),
  require('@raincatcher/angularjs-auth')()

Note

Ensure to enable the @raincatcher/angularjs-auth module along with the PassportAuth module. This package contains the AngularJS implementation of the login page used by PassportAuth for the mobile application. For more information on how to customize the PassportAuth login page used by the mobile application, see the Customizing PassportAuth Login UI section.

14.4. Implementing PassportAuth

14.4.1. Prerequisites

Ensure you have completed Getting Started

14.4.2. Pointing PassportAuth to a Datasource

The default PassportAuth implementation uses a JSON file which contains a set of sample users for demo purposes. The following steps describes how to replace the current set of users by pointing to a different user datasource.

Implement the UserRepository Interface

The UserRepository Interface needs to be implemented in order to retrieve user related data from a data source.

Import the UserRepository Interface.

import { UserRepository } from '@raincatcher/auth-passport';

Implement the UserRepository Interface.

See the sample UserRepository implementation as a reference on how this can be implemented.

Implement the UserService Interface

The UserService Interface defines a set of requirements for mapping specific fields from the user data that is returned from the UserRepository.

Import the UserService Interface.

import { UserService } from '@raincatcher/auth-passport';

Implement the UserService Interface

Important

The UserService Interface contains a getProfile() function, which is used to retrieve the user’s profile data. Ensure that any sensitive data is filtered out before returning the user’s profile data.

See the sample UserService implementation as a reference on how this can be implemented.

14.4.3. Enable PassportAuth for Route Protection

Prerequisites

Ensure you have the Pointing to a Datasource step completed

Set up a PassportAuth Service

Instantiate a UserRepository and UserService to be used by PassportAuth

  const userRepo: UserRepository = new YourUserRepository();
  const userService: UserService = new YourUserService();

Instantiate PassportAuth to be used for Route Protection

  const authService: PassportAuth = new PassportAuth(userRepo, userService);

Initialize a PassportAuth Service

PassportAuth can be initialized in two different ways depending on what Passport.js strategy you would like to use.

For more information on PassportAuth init function, see PassportAuth init() documentation.

Initialize PassportAuth to use the Local Strategy

Passport.js local strategy is used for authenticating with a username and password. In RainCatcher, this strategy is used to authenticate users in the portal application by default.

In order to configure PassportAuth to use the local strategy, the following steps needs to be completed:

Define express session options to be used with PassportAuth for session management

Express session is used to provide session support for PassportAuth. In RainCatcher, the session options are defined in the config-dev and the config-prod configuration files in the server application.

For more information on express session options, see the express-session documentation.
Initialize PassportAuth

PassportAuth needs to be initialized with an express router and the express session options you have defined in the previous step.
```
  authService.init(expressRouter, yourSessionOptions);
```
For more information on PassportAuth local strategy implementation, see PassportAuth web strategy documentation.

Initialize PassportAuth to use the JWT Strategy

Passport.js JWT strategy is used to authenticate a user with a JSON Web Token. In RainCatcher, this strategy is used to authenticate users in the mobile application by default.

In order to configure PassportAuth to use the JWT strategy, the following steps needs to be completed:

Generate a secret to be used for signing the JSON Web Token.

Important
The secret is used to sign a JSON Web Token. Ensure to provide a secure secret in order to prevent attackers from carrying out unauthorized actions.

In RainCatcher, the secret used for the JWT strategy is defined in the config-dev and the config-prod configuration files in the server application.
Initialize PassportAuth

Note
Passport.js JWT Strategy does not require session support, therefore it should not pass any session options.

PassportAuth needs to be initialized with an express router and the secret you have defined in the previous step.
```
  authService.init(expressRouter, undefined, yourSecret);
```
For more information on PassportAuth JWT strategy implementation, see PassportAuth JWT strategy documentation.

14.4.4. Using the PassportAuth Middleware for Route Protection

Prerequisites

Ensure you have the Enable PassportAuth for Route Protection step completed.

PassportAuth Authentication

Authentication with PassportAuth can be done in two different ways depending on the strategy used. For more information on Authenticating with PassportAuth, see PassportAuth Authentication section.

Authenticate using Local Strategy

PassportAuth wraps the Passport.js authenticate middleware in PassportAuth’s authenticate() function.

The following code is an example of how to authenticate using PassportAuth local strategy:

  router.post('/login', authService.authenticate('local', {
    successReturnToOrRedirect: '/',
    failureRedirect: '/loginError'
  }));

For more information on PassportAuth authenticate() functionality, see PassportAuth authenticate() documentation.

Authenticate using JWT Strategy

PassportAuth provides an authentication middleware for authenticating with the Passport.js JWT strategy. The following code is an example of how to authenticate using PassportAuth JWT strategy:

  router.post('/login', authService.authenticateWithToken(yourSecret, userService, userRepo));

Note	The JWT token needs to be included in each subsequent requests after a successful login as part of the Authorization header

For more information on PassportAuth authenticateWithToken() functionality, see PassportAuth authenticateWithToken() documentation.

Protecting Express Routes

PassportAuth provides a protect middleware for protecting routes from unauthenticated and unauthorized requests. The following code is an example of how to protect express routes using PassportAuth:

  // This implementation supports role based authentication
  app.use('/test', securityMiddleware.protect(role));

For more information on PassportAuth protect() functionality, see PassportAuth protect() documentation.

15. Logging

RainCatcher Logger creates logging facade for JavaScript based applications that is used by all RainCatcher modules. Developers can use custom loggers by wrapping their implementation into the provided logger interface.

For more information about the logger interface structure, see logger api documentation

The RainCatcher demo application contains two implementations of the logger interface a

BunyanLogger Implements Bunyan. Used for server side logging.
ClientLogger Implements LogLevel. Used for client (web and mobile) logging.

To see a logging example, see the Cloud Logger example.

16. File storage

File storage allows step developers to manage files like photos and documents directly in the steps.

File storage implementation provides:

server module with multiple storage implementations.
client module that can be used to store and retrieve files from the server
optional camera wrapper for capturing photos using phone camera

Main functionalities:

Ability to store and retrieve files
Offline queue for uploading, downloading files when device is offline
Multiple storage implementations available

Camera module provides wrapper around Apache Cordova camera plugin for seamless image capture and file integration.

16.1. File storage modules

To use file storage functionality new modules should be added

16.2. Example Gallery step

Storage and camera modules are integrated together as part of the example Gallery step

Modifying the UI

17. The Technology and Structure of the User Interface in a RainCatcher Project

The User Interface of RainCatcher consists of a series of modules made available through the public NPM registry and built as modules the AngularJS Framework.

17.1. UI Frameworks

The RainCatcher modules are intended to be used as part of a regular AngularJS application and used by it as AngularJS modules.

RainCatcher also utilizes Angular Material extensive as both a set of widgets and for achieving a consistent design philosophy.

17.2. Styling

RainCatcher supplies SASS files with every module, allowing users to take advantage of its features to quickly customize the look and feel of the modules by simply defining and altering simple variables in the stylesheets.

17.3. Mobile app tooling

In addition to being a regular AngularJS application, the Mobile Starter App uses Apache Cordova project to interface with the device’s native resources. This setup allows for simple testability without requiring any actual mobile devices or emulators until the latest stages in the development cycle.

18. Extending the User Interface

RainCatcher framework provides a set of extension points that allows a developer to modify an Angular User Interface (UI). You can modify the UI by writing additional modules that provide a set of the Angular.js directives to extend the Mobile and Portal UI. The RainCatcher Application is shipped with the angularjs-extensions example that extends the Mobile and Portal Applications:

https://github.com/feedhenry-raincatcher/raincatcher-angularjs/tree/master/packages/angularjs-extensions

This Module contains the example directives that are used for demo purposes and it can be used as a template to extend the existing RainCatcher UI.

18.1. Extending the Workorders UI

By default, RainCatcher provides a minimal set of defined fields for a workorder. If your step results contain additional data, for example, gps location, an address or a description UI element, you probably want to extend the workorders UI to display that data.

18.1.1. Building Directives

To extend a workorder, implement two Angular Directives:

Table 11. Angular Directives for Extending a *workorder*
Angular Directive	Description
`workorder-data`	A Data directive used to implement static fields that display data.
`workorder-data-edit`	A Data-edit directive used to implement fields that allow modifications to be made to a workorder’s data.

Note	Directives operate (with respect to existing fields) outside of a workorder to avoid naming conflicts, for example, `workorder.data.yourcustomfield`

18.2. User Interface

Include any required additional styles or libraries in the top level application. The Mobile and Portal Applications contain standard bootstrap and Angular material directives and are located in the top level of the application. For more information, see the Latest API.

18.3. Development of a template

To build a template, use grunt wfmTemplate:build. To rebuild a template after making changes to it, use grunt wfmTemplate:watch. Each change to a template requires a distribution build.

18.4. Integration

An Entry File exposes a new implementation of an Angular module, mount it in a root application module. Integrate any new NPM modules into both the Mobile and the Portal Application, so that the User can view the data belonging to the revised workorder.

Note	The RainCatcher Application contains the `@raincatcher-examples/angularjs-extensions` module. If you require a new custom module, remove the RainCatcher Application to avoid collisions.

18.5. Publishing

For RainCatcher to consume a module, best practice is to ensure that the module is published to the public or private NPM registry. When publishing a custom module, ensure that the package’s name and the author’s name are updated. If you choose not to publish a custom module, you can include all directives directly in the RainCatcher application.

19. RainCatcher UI App Customization

Follow these procedures to start applying changes to the Mobile and Portal Apps. Refer to the RainCatcher Application Reference Material for more information about their overall structure.

19.1. Adding UI elements

19.1.1. Creating your own AngularJS module with routing

In order to add new elements to the RainCatcher UI, you must create your own AngularJS module and add it to the array of dependencies of the main application module.

RainCatcher utilizes UI-Router for AngularJS to modularize the user interface components in separate routes that can be referenced by navigation links.

The Applications follow a 2-column module in the case of the Portal App, and a single column plus an optional toolbar section in the case of the Mobile App. The applications can provide the HTML ids of these container elements to the individual modules, allowing them to insert views into them through the UI-Router.

The following is a tiny example of how a module can be structured:

module.exports = function(config) {
  var moduleName = 'my-module';
  angular.module(moduleName, [])
  .config(['$stateProvider', function($stateProvider) {
    var views = {};
    views[config.mainColumnViewId] = {
      template: '<p>Hello from the custom module!</p>'
    };

    if (config.listColumnViewId) {
      // optional for use in the portal app
      views[config.listColumnViewId] = {
        template: '<p>Hello from the list view for this route!</p>'
      };
    }

    if (config.toolbarViewId) {
      // optional for use in the mobile app
      views[config.toolbarViewId] = {
        template: '<p>Hello from a toolbar for this route!</p>'
      };
    }

    $stateProvider.state('app.custom', {
      url: '/custom',
      views: views
    });
  }]);

  return moduleName;
};

Your module should:

Export a function that receives a configuration object and returns the name of the module for convenience;
Utilize the UI-Router’s $stateProvider to include any new routes;
Define states that are nested states of app (app.custom in the above example), since otherwise the views in the custom state will replace the application’s entire interface instead of inserting their content in the containers. See Nested States & Nested Views for more information.

Refer to the AngularJS Module documentation for further information on creating new modules.

19.1.2. Adding the new module to the main application config

To configure the Apps to utilize your module, add it to the array of dependencies of the main app module for the App:

angular.module('app', [
  //...
  require('./my-module')({
    listColumnViewId: "column2",
    mainColumnViewId: "content@app",
  }),
  //...
]);

For the Mobile App, this is located at src/app/app.js.

For the Portal App, this is located at src/app/main.js

At this point, running the App and navigating to /custom should navigate to the custom route and display the messages defined in the template keys in the previous section.

19.1.3. New navigation option on the navigation sidebar

To add a navigation link to the new custom route on the main navigation sidebar, edit the main.tpl.html file (present on both Apps), and add a new md-list-item that utilizes the navigateTo() method that’s available on the main controllers.

<md-list>
  <!-- ... Other navigation items -->
  <md-list-item ng-click="navigateTo('app.custom')" ng-class="{active: $state.includes('app.custom')}">
    <md-icon md-font-set="material-icons">bookmark</md-icon>
    <p>Custom link</p>
  </md-list-item>
  <md-divider></md-divider>
  <!-- ... Other navigation items -->
</md-list>

See the mdIcon documentation for the list of icons that you can utilize with the new navigation item.

19.2. Customizing SASS and Themes

RainCatcher utilizes SASS in order to supply extra features on top of standard CSS. These files are entry point to customizing and adding new styles to the App’s interface.

19.2.1. Adding extra Stylesheets

In order to add new SASS files, simply include a new file in the src/sass/ directory of your App and @import it from the App’s main .scss file:

// In custom.scss
.my-class {
  color: #0000FF;
}

// In the main .scss file
@import './custom.scss';

It’s recommended to include custom rules in new files and even use namespaced or prefixed class names to avoid collisions with updates in the RainCatcher codebase.

19.2.2. Changing the theme of RainCatcher components

RainCatcher components inherit their look and feel from global variables defined in the top section of main SASS file, by changing these values all elements will reflect the new values after the standard build process regenerates the compiled CSS files from them:

$secondary-text-color: rgba(0,0,0,.54);
$divider-text-color: rgba(0,0,0,.12);

$white-text-color: rgba(255,255,255,1);
$white-secondary-text-color: rgba(255,255,255,.7);
$white-divider-color: rgba(255,255,255,.3);

$primary-color: #3F51B5;
$secondary-color: #303F9F;

$accent-color-1: #a63db8;
$accent-color-2: #4d5bb3;
$accent-color-3: #1aa094;
$accent-color-4: #283593;

$success: #388E3C;
$danger: #F44336;

19.3. Customizing RainCatcher Login UI

Customizing the PassportAuth Login Page for the Portal Application

The login page for PassportAuth in the portal application is served by the server application. It can be rendered like the following example below:

res.render('login', {
  title: 'Your Title',
  message: 'Your Invalid Credentials Message'
})

The PassportAuth portal login page is fully customizable by configuring the login.hbs within the server application.

Customizing the PassportAuth Login Page for the Mobile Application

The @raincatcher/angularjs-auth package contains the AngularJS implementation of the PassportAuth login page. This is used with the PassportAuth module for the mobile application.

The package needs to be enabled along with the PassportAuth module within the mobile application. The title of the login page can be specified by adding the title as a parameter to the module.

require('./passport'),
require('@raincatcher/angularjs-auth')({
  title: 'Your Title Here'
})

The PassportAuth mobile login page can be customized by customizing the login page template in the @raincatcher/angularjs-auth module. Ensure that the templates are built by running the following command

grunt build

19.3.2. Customizing Keycloak Login UI

The Keycloak login page can be customized by providing a custom theme for Keycloak. For more information on how to provide your own custom theme for Keycloak, see the Create a custom theme for Keycloak article.

20. RainCatcher AngularJS modules

This section describes RainCatcher’s list of modules that are built to work with the AngularJS Framework. The latest list of modules is found at RainCatcher Modules.

Table 12. RainCatcher AngularJS Modules
Module	Description
@raincatcher/angularjs-auth-keycloak	The RainCatcher client-side authentication module for use with a KeyCloak back-end.
@raincatcher/angularjs-auth-passport	The RainCatcher client-side authentication module for use with a ExpressJS + passport.js.
@raincatcher/angularjs-auth	User Interface module for use with the authentication packages linked above.
@raincatcher/angularjs-http	Data access module based on AngularJS’s $http module.
@raincatcher/angularjs-workflow	The RainCatcher User Interface package for rendering Work Flows
@raincatcher/angularjs-workorder	The RainCatcher User Interface package for rendering Work Orders
@raincatcher/angularjs-extensions	Extra AngularJS directives to attach and display extra data in Work Orders.
@raincatcher/step-accident	Example RainCatcher Step for an accidental crash with a motor vehicle scenario.
@raincatcher/step-vehicle-inspection	Example RainCatcher Step for a vehicle inspection scenario.
@raincatcher/angularjs-signature	Example RainCatcher Step for capturing a user’s signature as a bitmap.

Production setup

21. Production checklist

Following guide provides set of guidance and actions that needs to be verified before releasing ${PRODUCT_NAME} to production.

21.1. Server configuration

Server application provides abstraction for configuration that allows users to create profiles. Application is created with 2 default profiles:

development (config-dev.js)
production (config-prod.js)

For more information about profiles go to Server side reference

When moving to production developers should review their configuration to make sure that a

Most important areas to review:

MongoDB configuration pooling
Redis configuration
Session
Security tokens
Application logging

Most important values

seedDemoData (disable demo data by false)
passportjs.jwtSecret: secret value used with Passportjs
session.secret: secret value for the session

Note	Configuration contains critical elements for application security. Please make sure that you not going to use any default values from the profile provided with server application.

Please follow integrations documentation for more details about specific sections of the configuration

21.2. Mobile application

Mobile configuration should be adjusted before building mobile application. Configuration can be found config.json file

Developers can adjust sync options improve overall performance. For more information see Performance Guide Additionally Keycloak configuration can be changed.

Most important values

sync_frequency: can be used to adjust time sync framework will pool the server)

21.2.1. Cordova configuration

Apache Cordova configuration needs to be adjusted before doing release. Configuration can be found in Cordova config.xml file Developers should review Cordova file by removing permissions and plugins that aren’t used. Additionally developers should restrict and remove any origins that aren’t used in the application

<!--Remove wildcard-->
<access origin="*" />

21.3. Portal configuration

Portal configuration can be found config.json file

21.4. Remove redundant code from all applications

RainCatcher reference applications including all npm modules that are available as part of the solution. Depending on use case developers can choose to use different technologies. Before moving to production any redundant code and npm modules should be removed from package.json

Please follow individual application documentation to see what elements can be removed.

22. Performance Guidelines

RainCatcher integrates multiple technologies and frameworks into single solution. Developers can build on top of the provided applications and use technologies that aren’t part of the standard applications.

Node.js based server can rely on customer preferred database or external API. This may have significant impact on overall application performance. RainCatcher was designed to expose all configuration into single files. Thanks to that developers can move applications to production by changing configuration in one place.

Server side application supports profiles (by default development and production) that will also help to differentiate between production and development configuration. This will ensure that application will be secure and perform to growing number of users.

22.1. Purpose of this guide

In document provide guidelines for RainCatcher integrations by exposing common parameters and documenting performance guidelines for integrations.

22.2. Server application

Server exposes number of parameters that can be changed by adjusting server configuration. For more information see configuration config-prod.js

22.2.1. MongoDB

MongoDB connection options should be configured to properly maintain connection pooling. See server side configuration. config-prod.js

22.2.2. Indexes on the mongodb data

If MongoDB is being used as storage for sync data, developers needs to create indexes to improve performance.

Workorder:

id
assignee

Workflow

22.2.3. Redis Cache

RainCatcher using redis indirectly to store user sessions. Please refer to official redis client options. Redis configuration can be changed in config-prod.js file.

22.2.4. Passport.js

When designing authentication service on top of the Passport.js developers can choose their own user source. Passport.js integration performance will mostly depend on Repository implementation. Implementation abstract from the any database layer. Developers will need to make sure that Repository implementation will return results without significant delays. Additional network timeouts can be provided. To provide best performance please make sure that no external network requests are made.

22.2.5. FeedHenry Sync

FeedHenry Sync is being used by default in the mobile application to synchronize data between mobile device and server. RainCatcher provides thin layer on top of the sync framework with number of helpers that are RainCatcher specific.

Sync documentation:

Changing sync frequency

Mobile application allows developers to change client sync frequency by modifying config.json file

WFM implementation using only single workorders dataset. We can change frequency as bellow:

{
  "workorders": {
    "sync_frequency": 60
  }
}

Note	default 10 seconds frequency is being used on the server. If you wish to change server frequency please follow sync documentation.

Note	For best performance users should keep the same frequency on the server and client.

22.3. Keycloak/SSO authentication

RainCatcher integrates with Keycloak/SSO using official clients. Developers can install and configure Keycloak server for their own needs and capabilities.Application performance may depend on number of users and realms used in the solution. For more information about performance of Keycloak/SSO please refer to official documentation and blog.

Release notes

23. Overview

RainCatcher allows you to move from paper based forms and processes into complete mobile solution. RainCatcher connects a business back-office portal application with its fleet of mobilized employees via a mobile application. Both mobile and portal applications are fully customizable.

23.1. 1.1.0 Release

23.1.1. Starting the server application

In previous releases of raincatcher the 'npm run start' command ran the project using the TypeScript Node source code. With this release, that command now runs compiled JavaScript. If you want to run the project using TypeScript source code:

npm run start:ts.

23.1.2. File storage and Camera integration

RainCatcher steps can now capture and store photos using the underlying file storage server. For more information, see the File storage documentation.

23.2. 1.0.0 Release

RainCatcher 1.0.0 is a new product that was previously in tech preview. The Features are listed below.

23.2.1. Workflows

The ability to create customizable processes (called Workflows). Workflows are made up of Steps which can be the Packaged Steps or can be custom Steps developed for a particular use case.

23.2.2. Workorders

The ability to process instances called Workorders. Workorders are a instance of an individual workflow. Workorder can be assigned via the Portal Application to individual employees as a job for completion.

23.2.3. Step Generator

Generates a Step via a CLI, the step can be customized to meet a use case.

23.2.4. Packaged Step

Providing predefined signature Step that can be used for any business needs.

Contributing

24. Contributing Guide

Note	The instructions in this section are for developers who want to contribute to RainCatcher.

This procedure will install the latest master branch.

Prerequisites

Ensure you have:

Node and npm installed (tested on Node 6 LTS)
git
access to git@github.com:feedhenry-raincatcher/raincatcher-angularjs.git
MongoDB
Redis

Cloning the Git Repository

git clone git@github.com:feedhenry-raincatcher/raincatcher-angularjs.git

cd raincatcher-angularjs

Installing Repository Dependencies

npm install
npm run bootstrap

Installing Core Dependencies

cd ./core
npm install
npm run bootstrap

Note	The Core repository is automatically cloned by the command `npm run bootstrap`.

Starting MongoDB and Redis

Start MongoDB. For more information, see Start MongoDB Processes.
Start Redis. For more information, see Starting Redis.

Starting the Core Server

The following line runs the server application and the internal dependencies from their TypeScript sources:

npm run start:ts

To compile and run from JavaScript:

npm run build
npm run start

Note	The terminal is out of use while the Core Server is running.

Running the Mobile and Portal Applications

Open a new terminal and navigate to the folder containing raincatcher-angularjs, and execute:

npm run start

Both the Mobile and Portal applications open automatically in a browser.

Revised on 2017-12-04 11:35:18 GMT