
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
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
1.3.3. Identifying RainCatcher Repositories
RainCatcher is available in three github repositories:
Repository | Description |
---|---|
Contains the Mobile application. |
|
Contains the Portal application. |
|
Contains the Server application. |
|
Repository contains RainCatcher documentation |
|
Contains the contribution repository of the supported modules and server. |
|
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.
Log in to the Portal and Mobile applications with the following credentials to access the sample content:
Application | Username | Password |
---|---|---|
Portal |
|
|
Mobile |
|
|
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
-
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
-
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
-
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
-
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
Login using the following credentials:
Application | Username | Password |
---|---|---|
Mobile |
|
|
Portal |
|
|
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:
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.
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.
Module | Description |
---|---|
The RainCatcher Security Interface is used to apply authentication and authorization, used in conjunction with a security provider chosen by you. |
|
The RainCatcher implementation of Passport.js which is the default security module for Mobile and Portal applications. |
|
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. |
|
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. |
|
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. |
|
The RainCatcher Work Flow Management API module exposes express API endpoints for Work Flow Management Objects. |
|
The RainCatcher Aggregates all user operations for RainCatcher modules. |
|
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
or
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
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. |
|
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. |
|
Has a small AngularJS controller for displaying a template before data is loaded from the backend server. |
|
Contains app-wide [Sass](http://sass-lang.com/) files that are compiled by the build pipeline. |
|
Contains configuration values and initial bootstrapping code for the AngularJS application. |
|
Contains resource files (mostly bitmaps) that are used by the UI. These are also included in the various resolutions expected by the native apps. |
|
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
or
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
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. |
|
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. |
|
Has a small AngularJS controller for displaying a temporary template before data is loaded from the backend server. |
|
Contains app-wide [Sass](http://sass-lang.com/) files that are compiled by the build pipeline. |
|
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.
NoteYou 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
andconfig-{env}.json
file -
redis installed and running on port 6379 | URL controlled by
process.env.REDIS_CONNECTION_URL
andconfig-{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
-
Login as the admin user using the following 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
Production
/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 }
NoteEnsure 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')()
NoteEnsure 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
ImportantThe 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.
ImportantThe 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
NotePassport.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
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:
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:
Angular Directive | Description |
---|---|
|
A Data directive used to implement static fields that display data. |
|
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
19.3.1. Customizing PassportAuth 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.
Module | Description |
---|---|
The RainCatcher client-side authentication module for use with a KeyCloak back-end. |
|
The RainCatcher client-side authentication module for use with a ExpressJS + passport.js. |
|
User Interface module for use with the authentication packages linked above. |
|
Data access module based on AngularJS’s $http module. |
|
The RainCatcher User Interface package for rendering Work Flows |
|
The RainCatcher User Interface package for rendering Work Orders |
|
Extra AngularJS directives to attach and display extra data in Work Orders. |
|
Example RainCatcher Step for an accidental crash with a motor vehicle scenario. |
|
Example RainCatcher Step for a vehicle inspection scenario. |
|
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
-
id
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