Form Dispatcher

This application de-couples web form submission from backend application logic that dicates what happens with the submitted data. It acts as a dispatch service that passes the form parameters to other microservices to do things like send an email to an employee, create a GitHub issue, or perform server-side validation.

How is it used?

The service receives a POST request containing the user input and a hidden destination param which tells the dispatcher where to send the request. All forms, regardless of what happens to the data in the backend, are submitted to the same URL.

Supporting Services

This service is built to pass submitted form data to other microservices. Below is the list of microservices currently supported by the dispatcher.

Form-to-email
Deliver a web form submission to a specified email address

Form-to-github-issue
Create a GitHub issue in a specified repository

Required Parameters

Forms submitted to this service must include the following parameters:

• destination param tells the dispatcher which service to pass the submission along to

In addition to required params for the dispatcher, the supporting services may also have parameter requirements of their own. Refer to their repositories for reference.

Quick Start

1. Clone the repo

   $ git clone https://github.com/cityofaustin/form-dispatcher.git
   

2. Install dependencies

   $ cd form-dispatcher/
   $ bundle install
   

3. Start the server

   $ rails s
   

4. Start Postgres and set up the database

   $ postgres -D /usr/local/var/postgres
   
   # In another shell:
   $ rake db:create
   $ rake db:migrate
   

5. Go to http://localhost:3000 and confirm that the Rails welcome screen appears ("Yay! You're on Rails!")

Configuring the client

1. Set the form action to POST to the dispatcher

   <form action="URL-FOR-DISPATCHER" method="POST">
   </form>
   

   See the environments section below for the dispatcher URLs for each environment

2. Add a parameter to specify where to dispatch the submission

   <form action="https://coa-test-form-api.herokuapp.com" method="POST">
   	<input type="hidden" name="destination" value="TBD" />
   </form>
   

   The current options for destination are email and githubIssue

3. Add any additional parameters required for the dispatched service

   <form action="https://coa-test-form-api.herokuapp.com" method="POST">
   	<input type="hidden" name="destination" value="TBD" />
   
   	<!-- for Form-to-email: -->
   	<input type="hidden" name="deliver_to" value="TBD" />
   	
   	<!-- for Form-to-github-issue: -->
   	<input type="hidden" name="repository" value="TBD" />
   	<input type="text" name="title" value="TBD" />
   	<textarea name="description" value="TBD"></textarea>
   </form>
   

4. Add any other form fields

   <form action="https://coa-test-form-api.herokuapp.com" method="POST">
   	<input type="hidden" name="destination" value="TBD" />
   	<!-- for email: -->
   	<input type="hidden" name="deliver_to" value="TBD" />
   	
   	<!-- for githubIssue: -->
   	<input type="hidden" name="repository" value="TBD" />
   	<input type="text" name="title" value="TBD" />
   	<textarea name="description" value="TBD"></textarea>
   	
   	<!-- Custom fields -->
   	<input type="text" name="field1" />
   	<input type="text" name="field2" />
   </form>
   

5. Consume JSON response
   The current implementation assumes the form will be submitted by AJAX, and that the client will await a JSON response from the server once the request has been fully processed. The response consists of 2 keys:

   • status
     Either success or error
   • body
     A custom string generated by the dispatcher or the dispatched service

CORS

The rack-cors gem provides support for Cross-Origin Resource Sharing, so that forms can be submitted from domains other than where the application is accessed. Domains must be manually white-listed in config/initializers/cors.rb.

Environments

Production

• URL: https://coa-test-form-api.herokuapp.com/
• GitHub: master
• Deployment: Updates to master automatically trigger a deployment to Heroku. There are no CI/CD tests involved at this time.

Local

• URL: https://localhost:3000/

Data retention

The dispatcher maintains a database of all submissions in order to provide some manner of records in accordance with data retention policies at the city.