form-engine

AIS Form Engine.

Project location: GitHub

This project provides Form Generation and data migration using an integrated schematic mapping design with various Cloud Platform providers (Quick Base, ServiceNow, etc…) The premise is pretty basic. Convert a PDF/Word/Image file into image based “pages”. Use Cartesian coordinate system to place schematicly bound fields over the top. Provide PDF generation and persistance services.

Notes on Architecture

3 July 2019 - The project is distributed accross 5 primary nodes of interest with varying levels of involvement and complexity.

  1. Front end - A mostly monolithic AngularJS (v1.7) web application. The original tool was designed to be hosted explicitly on Quick Base. As of this note, the current intent is to dumb the front end down and re-distribute the business logic is hosts accordingly.
  2. Backend - An assembly of variously triggered Firebase Cloud Functions written in TypeScript. The eventual target for our migrated business logic. view the Functions ReadMe for more details on composition and organization.
  3. Firebase Hosts our Realtime Database (FE Metadata), Cloud Functions, Web application, and Cloud Storage. Firebase Docs
  4. Quick Base One of our supported provider end-points. The original Data/Schema source consumed for Form Engine operations.
  5. ServiceNow This Provider was added as a Platform Pivot.
  6. Salesforce This Provider was added as a Demo.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

At the least, you will need node, gulp, and firebase-tools installed. We also recommend installing nvm.

Installing

Here is a step by step series of examples that tell you how to get a development env running.

Install nvm

Install node

Here are the single-step install scripts for both macOS and Linux. You’ve got the option of cURL or Wget but both achieve the same result.

Note: If your Linux system doesn’t have either cURL or Wget, you can run sudo apt-get install curl and use the cURL method

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash

Verify it was installed correctly.

nvm --version
Missing the nvm command after running the install script?

If you’re using macOS, you may be missing a .bash_profile file - to troubleshoot this, you can run touch ~/.bash_profile in your command line and re-run the installer script.

If the problem persists after that, you can open the existing .bash_profile file (using your favorite text editor) and add the following line to it:

source ~/.bashrc

Install gulp

Easy enough.

  sudo npm install -g gulp

Install Firebase CLI

Note: The Firebase CLI requires Node.js v6.0.0 or later. Some Firebase services might require specific versions of Node.js, so check each Firebase service’s getting started page for any specific Node.js requirements.

  1. Install the Firebase CLI using npm by running:
npm install -g firebase-tools 13.13.0

This command installs the globally available firebase command. To update to the latest version of the Firebase CLI, re-run the same npm install command.

  1. Sign into Firebase using your Google account by running:
firebase login

This command connects your local machine to Firebase and grants you access to your Firebase projects.

  1. To test that authentication worked (and to list all of your Firebase projects), run the following command:
firebase list

The displayed list should be the same as the Firebase projects listed in the Firebase console.

Project initialization

You will need to initialize both /web and /functions packages

  1. For the Web client: 
      cd web
  npm install
  gulp init
  2. For Google Cloud Functions 
      cd functions
  npm install

Running Development Environment

Initiate env files

  cd web
  npm run gen-envs

To start a local development environment/server in a single terminal, with debugging enabled (VSCode).

Note: Enable Debug: Auto attach in VS Code

  cd web
  npm start

You can now view the project at http://localhost:3000.

Deployment (web)

Here are some quick notes on deploying the web client. See more available scripts at web/package.json: scripts

Hosting specific environment

  cd web
  npm run serve:dev     # For dev environment
  npm run serve:test    # For test environment
  npm run serve:prod    # For prod environment

Deploy (dev environment)

Note: When prompted with: “Would you like to proceed with deletion?”
Select “N” (No) to continue with the rest of the deployment.

  npm run deploy:dev

Deploy a specific function

  firebase deploy --only functions:onDOCreated

Manually run backend locally with debugger enabled (using emulator and VSCode) and watch file changes

cd functions
firebase use dev     # For dev environment
firebase use prod    # For prod environment
firebase use test    # For test environment
firebase use client  # For client environment
tsc-watch --project tsconfig.dev.json --onSuccess \"npm run emulate\"

Manually run frontend locally and watch file changes

cd web
# For dev environment
firebase use dev
npm run webenv:dev
# For prod environment
firebase use prod
npm run webenv:prod
# For test environment
firebase use test
npm run webenv:test
# For all environments
gulp local

Run debug file and attach debugger automatically

Note: Enable Debug: Auto attach in VS Code Note: Use DEBUG_CLASS env variable to run specific class in debug folder. ex: set DEBUG_CLASS=QbApi && npm run debug:test

cd functions
# For dev environment
npm run debug:dev
# For prod environment
npm run debug:prod
# For test environment
npm run debug:test
# For client environment
npm run debug:client

Troubleshooting

NET::ERR_CERT_AUTHORITY_INVALID

Email sent by Jake to a company’s IDT department. they were able to resolve the clients issue with this information:

Hey All,

I am writing on behalf of Derek, in order to assist with a problem he is having running our ”Form Engine” web app. I believe it is related to the Cisco Umbrella software in use on PSGDOVER’s network/machines.

The problem points to request to origin https://firebasestorage.googleapis.com, used by our app to upload and display PDFs and image files etc.
On Derek’s machine, the above origin causes NET::ERR_CERT_AUTHORITY_INVALID to be thrown in the Chrome browser console, preventing complete page load.

Here are the certificate security details we would expect to see on the request in question (from my machine):

image.png

I had Derek copy the suspect request url directly to his browser navbar in order to get details on the faulty Certificate Chain:

image.png

While Derek’s certification path on the main origin quickbase.formengine.com looks as we would expect
(Google Trust Services - Globalsign Root CA-R2 => GTS CA 101 =>, firebaseapp.com),
It seems that Cisco Umbrella may have intercepted the secondary request to https://firebasestorage.googleapis.com and issued its own certificates, of which the Root CA is potentially not installed on his machine:

image.png

Also, Derek ran the URL in question through the Cisco Umbrella URL analysis tool on his machine. We cannot see the results, but they are apparently located here for those with access:
https://diagnostic.opendns.com/d/5682039287185408

I will avoid being prescriptive as I am unfamiliar with Cisco Umbrella, but let me know if you would like further thoughts/ideas into this issue.
The above info may be enough for your team to find a resolution.

Here is a potentially helpful OpenDNS article regarding installation of Root CAs.

Built With

Versioning

We use SemVer for versioning.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the EULA License - see the Terms and Conditions for details