forms-runner

Citizen-facing forms using a config driven Node application.

This repository is forked from the old Defra digital form builder. These projects has been adapted to run several configurations on a single instance.

DEFRA's digital form builder is a metadata-driven framework that builds on our robust, enterprise backend tech stack and the new gov.uk frontend Design System and allows form based gov.uk sites to be easily built using a graphical design tool.

The designer is no longer a plugin and is responsible for running itself on default port 3000.

• Requirements
  • Node.js
• Local development
  • Setup
  • Development
  • Local JSON API
  • Production
  • npm scripts
• Docker
  • Development Image
  • Production Image
• Licence
  • About the licence

Requirements

Node.js

Please install Node.js >= v20. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

$ cd forms-runner
$ nvm use

Local development

for local developers

Setup

Install application dependencies:

$ npm ci

Development

To run the application in development mode run:

$ npm run dev

Production

To mimic the application running in production mode locally run:

$ npm run start

npm scripts

All available npm scripts can be seen in package.json To view them in your command line run:

$ npm run

Docker

Development image

Build:

$ docker build --target development --no-cache --tag forms-runner:development .

Run:

$ docker run -p 3000:3000 forms-runner:development

Production image

Build:

docker build --no-cache --tag forms-runner .

Run:

$ docker run -p 3000:3000 forms-runner

Environment variables

If there is a .env file present, these will be loaded in.

⚠️ See config for default values for each environment

Please use a config file instead. This will give you more control over each environment. The defaults can be found in config. Place your config files in runner/config See https://github.com/node-config/node-config#readme for more info.

name	description	required	default	valid	notes
NODE_ENV	Node environment	no		development,test,production
PORT	Port number	no	3009
OS_KEY	Ordnance Survey	no			For address lookup by postcode
PAY_API_KEY	Pay api key	yes
PAY_RETURN_URL	Pay return url	yes			For GOV.UK Pay to redirect back to our service
PAY_API_URL	Pay api url	yes
NOTIFY_TEMPLATE_ID	Notify api key	yes			Template ID required to send form payloads via GOV.UK Notify email service.
NOTIFY_API_KEY	Notify api key	yes			API KEY required to send form payloads via GOV.UK Notify email service.
GTM_ID_1	Google Tag Manager ID 1	no
GTM_ID_2	Google Tag Manager ID 2	no
MATOMO_URL	URL of Matomo	no
MATOMO_ID	ID of Matomo site	no
SSL_KEY	SSL Key	no
SSL_CERT	SSL Certificate	no
PREVIEW_MODE	Preview mode	no	false		This should only be used in a dev or testing environment. Setting true will allow POST requests from the designer to add or mutate forms.
LOG_LEVEL	Log level	no	debug	trace,debug,info,error
PRIVACY_POLICY_URL	The url used in footer's privacy link	no	help/privacy
API_ENV	Switch for API keys	no		test,production	If the JSON file supplies test and live API keys, this is used to switch between which key which needs to be used
PHASE_TAG	Tag to use for phase banner	no	beta	alpha, beta, empty string
AUTH_ENABLED	Enable auth for all form pages	no	false
AUTH_CLIENT_ID	oAuth client ID	If AUTH_ENABLED is true
AUTH_CLIENT_SECRET	oAuth client secret	If AUTH_ENABLED is true
AUTH_CLIENT_AUTH_URL	oAuth client authorise endpoint	If AUTH_ENABLED is true
AUTH_CLIENT_TOKEN_URL	oAuth client token endpoint	If AUTH_ENABLED is true
AUTH_CLIENT_PROFILE_URL	oAuth client user profile endpoint	If AUTH_ENABLED is true

Testing

Tests are found inside test/cases. For test scripts, name them ${NAME}.test.js.

Outputs

At the end of a form, there are multiple output types. The schemas for the right json format can be found in the engine repo. Additional steps are required for the different output types.

• Notify
  • A GOV.UK notify is required
  • For each notification you wish to send, a template must be set up. If there are 'personalisations' they must match the configuration
• Sheets
  • This is currently a Google Sheets integration
  • For each sheet you wish to add data to, you must have have the spreadsheet id
  • You must have a Google Cloud Platform (GCP) account
  • create a project in GCP and note down the project id.
  • enable Google Sheets API for this project
  • Create a service account in this project. (You only need to follow the 'Creating a service account' steps on this page)
    • Once it is created, download the credentials (this will include the private_key and client_email)
• Webhook
  • The webhook must accept a POST request
  • It should also return with a JSON with the key 'reference' in the body

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.