Homeschool-PEBT

Table of Contents

• Form Flow Starter Application
• Table of Contents
• Static Pages
• Example Actions and Conditions
  • Actions
  • Conditions
• Development setup
  • System dependencies
    • Java Development Kit
    • Set up jenv to manage your jdk versions
    • Gradle
    • Start the local databases
    • Setup Environment
    • Setup Application
    • Contributing Live Templates to your App
    • Using a local version of the Form-Flow Library (For Form-Flow Library Developers)
• Using this as a template repository
  • AWS Setup
  • Cloud Deployment
    • Aptible Setup

This is a standard Spring Boot application that uses the form-flows Java package as a library. It can be customized to meet the needs of a web app, and is meant to be built upon. It's a plain, boring (but modern) Spring app that uses common, frequently-used libraries throughout.

It contains example code for a simple, generic application for public benefits. An applicant can fill out screens with their basic info, upload supporting documents, then submit it all. Upon submission, they receive a simple SMS confirmation and a receipt email with a filled-in application PDF. The entire experience is in both English and Spanish.

To power the form flow logic, this app depends on the form-flows Java library. That library is included in build.gradle along with all other dependencies. The codebase for the form-flows package is open source.

A detailed explanation of form flow concepts can be found on in the form flow library's readme.

Static Pages

Unlike Screens, Static Pages are HTML content and are not part of a flow. Detailed information about static pages can be found in the form-flow library documentation.

This application has three static pages served up by the StaticPageController class:

• index.html
• faq.html
• privacy.html

Example Actions and Conditions

Actions can be run at specific points in a form submission's life cycle.

Actions

There are for types of actions that one can use.

• beforeSaveAction
• onPostAction
• crossFieldValidationAction
• beforeDisplayAction

You can find more detailed information about each type of action in the Form Flow library's readme.

ClearIncomeAmountsBeforeSaving

This action is a beforeSaveAction and is run after validation but before the data is stored in the database. The UpdateIncomeAmountsBeforeSaving will clear out any unused Income types, if they were updated. For example, a user fills out the income type page and submits values for their chosen input types. If they then decide to go back and change a value or add a new income type, this action will ensure that any previous values entered that the user then cleared out are cleared out in the stored data as well.

UpdatePersonalInfoDates

This is an onPostAction and is run just after the data is sent to the server, before any validation is done on it. The UpdatePersonalInfoDates action will do the following for both the birth and movedToUSA fields on the Personal Info page. It will take the three separate date fields associated with them (day, month, and year) and put an aggregated date string into a general date field (birthDate and movedToUSADate, respectively).

ValidateMovedToUSADate

This is a crossFieldValidationAction and is run just after field level validation has occurred, but before the data is stored in the database. ValidateMovedToUSADate will check to see if the client has indicated that they moved to the USA in the last year. If they have, then this action will check to see that they've entered values for movedToUSA day, month and year, as well as check to see that the resulting date is actually valid.

Conditions

Setup instructions

System dependencies

Note: these instructions are specific to macOS, but the same dependencies do need to be installed on Windows as well.

Java Development Kit

If you do not already have Java 17 installed, we recommend doing this:

brew tap homebrew/cask-versions
brew install --cask temurin17

Set up jenv to manage your jdk versions

First run brew install jenv.

Add the following to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"

For m1 macs, if the above snippet doesn't work, try:

export PATH="$HOME/.jenv/bin:$PATH"
export JENV_ROOT="/opt/homebrew/Cellar/jenv/"
eval "$(/opt/homebrew/bin/brew shellenv)"
eval "$(jenv init -)"

Reload your terminal, then finally run this from the repo's root directory:

jenv add /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

Gradle

brew install gradle

Start the local databases

• Install PostgreSQL 14 via an official download

  • Or on macOS, through homebrew: brew install postgresql@14

• Create two databases using the command line:

  • Local instance:
    • $ createdb starter-app
    • $ createuser -s starter-app
  • Tests:
    • $ createdb starter-app-test
    • $ createuser -s starter-app-test

Setup Environment

Note that you'll need to provide some environment variables specified in sample.env to your IDE/shell to run the application. We use IntelliJ and have provided setup instructions for convenience.

IntelliJ

• cp sample.env .env (.env is marked as ignored by git)
• Download the EnvFile plugin and follow the setup instructionshere to setup Run Configurations with EnvFile.

Setup Application

• Use instructions from the form-flow library here.
• Run the application using the StarterApplication configuration (found in org.homeschoolpebt.app)

Contributing Live Templates to your App

If you have created live templates with fragments which are specific to your application based on a starter app template, you can commit them to your repository. You will follow a similar pattern to create templates to what is outlined in the form-flow library here.

An example template which was set up using this process, starting from an html snippet is available in this repository's IntelliJ settings folder.

Using a local version of the Form-Flow Library (For Form-Flow Library Developers)

To use a local version of the form-flow library you can do the following:

1. Clone the form-flow repo in the same directory as the starter app.
2. Build the form-flow library jar.
3. In this app, set the SPRING_PROFILES_ACTIVE to dev in the .env file.
4. Start the form-flow-starter-app.

Changing the SPRING_PROFILES_ACTIVE to dev will cause the starter app's build.gradle to pull in the local library, via this line:

implementation fileTree(dir: "$rootDir/../form-flow/lib/build/libs", include: '*.jar')

Using this as a template repository

AWS Setup

1. Provision a new AWS bucket.
   1. We use two buckets: one for demo purposes and another for production.
2. Replace the bucket names with your newly created buckets in the main application configuration and the demo application configuration.

Cloud deployment

Aptible Setup

For Aptible configuration information, please see their documentation.

The Aptible CLI documentation is particularly helpful.

Here are the general steps to setup a new application in Aptible:

1. Create a new environment and application in Aptible, or create a new application in an existing environment.
2. Setup Aptible permissions to enable deploying your application, if they do not already exist.
3. Provision a database for your application in Aptible.
4. Add repository secrets for the deploy github action.

Development Setup

1. Create a new repository from the form-flow-starter-app template .
2. Once the repository is created, clone it on your local machine.
3. Create a new database and user for your project. Please use descriptive names which are unique to your project to avoid conflicts locally. For example, for childcare-illinois-model-app we used childcare-illinois for both the database name and username. Following this example, create the new database and user with the following commands:

• $ createdb childcare-illinois
• $ createuser -s childcare-illinois. This assumes that you have installed postgres locally, if that is not the case please refer back to this section.

4. Edit the main application configuration as well as the demo application configuration to reflect your new database configuration. Replace the database name and username with the ones you created in the last step in the datasources section of the document. For example, the datasource section of your application configuration would initially contain the details for the starter-app database as follows:

datasource:
   url: jdbc:postgresql://localhost:5432/starter-app
   username: starter-app

and should be updated to this

datasource:
   url: jdbc:postgresql://localhost:5432/childcare-illinois
   username: childcare-illinois

5. To load the .env file in IntelliJ, you'll need to enable the EnvFile Plugin. Then enable it for your project.