BOPS

Back Office Planning System (BOPS)

Getting started

Using Docker

First build and launch the images:

docker-compose up

Once your containers are running, you can use the Makefile to get a prompt and setup your database:

make prompt

root@232515c34d14:/app# bin/rails db:setup

Locally

Install the project's dependencies:

$ bundle install
$ yarn install

Create the databases

$ rails db:setup

Start the server:

$ rails server

Subdomains

Because of the local authority being inferred on the request's subdomain, your options to get work locally include using Docker or using the bops-care.link domain which points back to your localhost:

http://southwark.bops-care.link:3000/
http://lambeth.bops-care.link:3000/
http://buckinghamshire.bops-care.link:3000/

Otherwise you can use localhost though you'll have to double the subdomain since localhost is missing the second component found in normal-domains.com.

http://southwark.southwark.localhost:3000/
http://lambeth.lambeth.localhost:3000/
http://buckinghamshire.buckinghamshire.localhost:3000/

GOV.UK Notify

You should ask for an account to be set up for you on GOV.UK Notify

2FA

To enable 2FA in development, you must set the env variable 2FA_ENABLED to true and set the keys for OTP_SECRET_ENCRYPTION_KEY and NOTIFY_API_KEY. You may find this in 1password and within your GOV.UK Notify notify account

These keys are set within github actions for our testing and CI builds

OS maps

To utilise all the map functionality, you will need to set an OS_VECTOR_TILES_API_KEY in .env You can find this value from the parameter store on AWS

BOPS applicants

BOPS allows planning officers to request changes to an application; these requests are presented to applicants through a separate app called BOPS-applicants. Applicants receive an email containing a special URL that will be opened in BOPS applicants and contain the right parameters for it to query back at BOPS.

If you're using Docker, bops-applicants is already part of the Compose group and should be running on port 3001. If you're not, you'll have to clone/setup/boot the app manually and point BOPS to it through the environment variable APPLICANTS_APP_HOST. See ./env.example.

Another benefit of using Docker is being able to run some end-to-end tests that integrate both BOPS and BOPS applicants:

make e2e   # actually runs the Cucumber tests tagged with `@e2e`

Note that because of the limitations of Docker network aliases (which can't accept wildcards, we will add a small DNS service eventually), BOPS applicants has to operate against the Southwark local authority (i.e southwark.localhost) for now.

API

API documentation is available at /api-docs/index.html.

Creating data through the API

Once you have the application running, you can submit planning application through the API. You can do this through the provided swagger documentation at /api-docs/index.html

• Click Authorize and fill in the API key ('123' if not otherwise specified at db:seed)
• POST /api​/v1​/planning_applications > Try it out > Choose 'Full' example > Click Execute.

Working with api documentation: aggregate swagger files

We need a single openapi file to exist, but to keep the code easier to maintain we have multiple files that are then compiled into this single file:

public/api-docs/v1/_build/swagger_doc.yaml

So to create a new api endpoint, create your yaml doc inside public/api-docs/v1 and reference it in

public/api-docs/v1/swagger_doc.yaml

like so:

  $ref: "./your_new_file_name.yaml"

Make changes to your new file, and when you're happy aggregate them into our single file by installing this package in your machine:

npm install -g swagger-cli

and running:

swagger-cli bundle public/api-docs/v1/swagger_doc.yaml --outfile public/api-docs/v1/_build/swagger_doc.yaml --type yaml

Javascript

We are using Stimulus to handle our minimal JavaScript requirements.

After adding a new Stimulus controller run ./bin/rails stimulus:manifest:update. Alternatively you can create the controller with ./bin/rails generate stimulus controllerName.

Front end components

As much as possible, we follow the GOV.UK Design System. You will find most of the HTML components you need here. For help with forms we use the GOV.UK Ruby on Rails Form Builder gem. See here for a simple example of implementation.