getting-started.adoc

Getting Started with Raincatcher

Overview

Raincatcher is a set of templates and a field workforce management (WFM) application that connects a business' back-office with its fleet of mobilized employees. Raincatcher leverages mobile hardware, making use of each employee’s mobile phone.

Raincatcher consists of a set of reusable modules that can be included in your application using browserify.

Raincatcher modules make use of the mediator pattern to enable loose coupling between the Raincatcher modules and their consuming applications / modules as shown in the following diagram:

Raincatcher Structure

Raincatcher modules are packaged and distributed using npm and export as:

• Angular.js directives or services providing client-side functionality for both the mobile and portal clients.

• Express.js routes providing a REST API to be consumed by the client-side portions of the module.

• FeedHenry sync configurations which enable data synchronization of module data.

A demonstration is also provided as a project template that shows how the modules can be assembled into an application. See link:The Demo Solution Architecture for more information.

Running the Raincatcher Demo Solution

RHMAP provides a Raincatcher project template to help you run the demonstration.

1. Create a Raincatcher project as follows:

   1. Log in to the Studio and navigate to the Projects area.

   2. Click New Project.

   3. Select the WFM Demo Project template, available in the Tech Preview category.

   4. Enter a name for the project, for example wfm-demo.

   5. Click Create.

   6. Click Finish at the bottom of the page when the project is created.

2. Create an MBaaS Service using the WFM Auth Service template:

   1. Navigate to the Services & APIs area and click Provision MBaaS Service/API.

   2. Click Create New Service.

   3. Select the WFM Auth Service template, available in the Authentication category.

   4. Name the service, for example wfm-auth.

   5. Click Next.

   6. Click Finish at the bottom of the page when the service is created. The service details page is displayed.

   7. Select Deploy from the left menu.

   8. Select the target environment from the pulldown list on the right of the page.

   9. Click Deploy Cloud App.

3. Upgrade the database for the Cloud App and the WFM Auth Service:

   1. Select the Projects header menu item.

   2. Go to the Cloud App

   3. Select Data Browser from the left menu

   4. Click on the Upgrade Database button in the top right corner, and confirm by clicking Upgrade Now. Wait until the upgrade process finishes

   5. Navigate to the Services & APIs area

   6. Select the WFM Auth Service created

   7. Select Data Browser from the left menu

   8. Click on the Upgrade Database button in the top right corner, and confirm by clicking Upgrade Now. Wait until the upgrade process finishes

   9. Deploy WFM Auth Service

4. Create an auth policy using this new MBaaS service.

   1. Navigate to the Admin area and click Auth Policies.

   2. Click Create.

   3. Name the policy, for example wfm-policy.

   4. Select the MBaaS Service type.

   5. Select the wfm-auth service.

   6. Enter /api/wfm/user/auth as the endpoint.

   7. Select the target default environment. The Validate Settings section appears.

   8. Enter the Username trever and Password 123 and click Validate. The response JSON should have a status property and the property value of ok.

   9. Click Create Auth Policy.

5. Associate the WFM Auth Service with the WFM Demo Project.

   1. Navigate to the Services & APIs area and select the wfm-auth service created earlier.

   2. Enter the project name at the bottom of the Details page in the Access Control section under Service Settings:

      1. Enter the name of the project, for example,wfm-demo.

      2. Click the Save Service button.

   3. Set the FH_SERVICE_AUTHORISED_PROJECTS environment variable:

      1. From the left menu, select Environment Variables.

      2. Compare the value for FH_SERVICE_AUTHORISED_PROJECTS in the App section to the value in the System section. If the values are different, click the Push Environment Variables button.

   4. Set the WFM_AUTH_GUID environment variable using the project ID:

      1. From the left-hand side menu, select Details.

      2. Click the Copy button next to the Service ID field.

      3. Select the Projects header menu item.

      4. Select the wfm-demo project created earlier.

      5. Select the cloud app.

      6. From the left-hand side menu, select Environment Variables.

      7. Click Add Variable.

      8. Enter WFM_AUTH_GUID for the name, and paste in the Service ID copied above for the value.

      9. Click Push Environment Variables.

   5. Set the WFM_AUTH_POLICY_ID environment variable as the auth policy name.

      1. Select the Projects header menu item.

      2. Select the wfm-demo project.

      3. Select the cloud app.

      4. From the left-hand side menu, select Environment Variables.

      5. Click Add Variable.

      6. Enter WFM_AUTH_POLICY_ID for the name, and set the auth policy name created earlier as the value, for example, wfm-policy.

      7. Click Push Environment Variables.

6. Check that the auth service, the cloud app, and the portal app are all deployed and started.

   1. For each of the above mentioned apps, select Deploy from the left-hand side menu.

   2. Ensure that the most recent deployment has a result of Success.

   3. If it does not indicate success, click Deploy Cloud App and verify the deployment is successful.

The apps are now created, configured, and deployed.

To check the web app deployment in RHMAP:

1. Select the Projects header menu item.

2. Select the wfm-demo project.

3. Select the web app.

4. From the left-hand side menu, select Details.

5. Click Current Host.

6. Login with user trever and password 123.

Running the Raincatcher demo solution locally describes how to set up your local environment for Raincatcher development.

Module Integration explains how to introduce a new module to the solution providing extra functionality.