Licensify - supporting licensing - GOV.UK Developer Documentation

Last updated: 21 Nov 2024

GOV.UK runs a Scala application (Licensify) which allows users to apply and pay for licences from local authorities and other competent authorities.

Overview

There is a PDF user manual available which includes a lot of detail about the backend (administration) facilities available through the GOV.UK Licensing service.

Applications

The Licensing service consists of three applications deployed together:

licensify-frontend: the interface used by citizens and businesses who want to apply for a license. Allows them to download the relevant forms, submit them once completed, and also handles redirection to the relevant payment service if a fee is required.
licensify-admin: administrative interface for LAs to allow them to view and download applications from users. Also provides the ability for LA admin users to set up customisations (the specifics of the licence types) for their LA, and for GDS admins to control which licence types are available for each LA, and configuration like which payment provider the LA uses.
licensify-feed: backend (asynchronous) processing of application uploads and processing (via Apto), email notifications (via GOV.UK Notify), and expiry and purging of old applications. Also provides an interface for some debugging-type reporting.

Finding a licence

Users use Find a Licence to locate licences on the GOV.UK frontend, but from a technical perspective this is separate from Licensify.

Find a Licence sends users to a “Licence” page served by Frontend. Users enter their postcode and Frontend uses Locations API to find their local authority. Frontend makes a request to a Licensify API to find out whether the licence is available on GOV.UK.

Applying for a licence

Licence applications handled by Licensify are processed as follows:

User downloads a PDF application form and completes it either in Adobe Reader or by hand.
User uploads the completed application form to Licensify, and provides their email address and consents to a legal declaration.
User is provided with receipt of application by email, and an email is sent to the relevant authority to inform them that an application is available for viewing.
Licensing authorities check Licensify’s admin interface for new applications, then process them and either confirm or deny the application.

Testing

There is an example licence that you can use to test Licensify. Note that the following instructions are safe to run any number of times in production:

Go to https://www.gov.uk/apply-for-a-licence/test-licence/gds-test/apply-1
Download the PDF application form
Click ‘Submit application’
Enter your email address, upload the application form you just downloaded and tick the checkbox to accept the declaration
Click ‘Continue to pay fee’
Click ‘Continue to WorldPay website’
Enter a test card number
Make payment
You should see a confirmation page and receive an email with same details
Login to Licensify’s admin interface to verify that your application is visible

You can give the application reference to Kibana in the relevant environment to see the logs and any error messages. The application should speak to both the frontend and backend app servers at least once during the transaction. It may take up to five minutes to process the licence application, so it might be worth waiting for a few minutes before checking Kibana.

Debugging

The Feeds application has a UI, but that isn’t exposed publicly, so you need proxy to the service:

kubectl -n licensify port-forward svc/licensify-feed 9400:80

Once the tunnel above has been set up, the following pages are available:

Email

Mail from Licensify is handled by GOV.UK Notify using the HTTP API. Authentication is via an API key that is set via AWS Secret Manager and templated External Secret.

Apto Solutions

Apto Solutions is a third-party organisation who take the completed application forms uploaded as PDFs and convert the input into a format which can be read by the Licensify Admin application.

In order for this to work, the PDF forms are sent away from GOV.UK to Apto’s infrastructure. This means that Apto must have a firewall rule in place to allow connections from the outbound (NAT Gateway) GOV.UK IP address.

Data

Licensing data is stored in MongoDB and synced from production to staging. We don’t sync the data to integration automatically because it contains personally-identifiable information.

You can manually copy data from staging to integration. These collections do not contain personal information so they’re safe to copy:

for c in counters eula; do mongodump -d licensify -c $c -o ~/licensifydump; done
for c in authorities authorityLicenceInteraction customisations departments elmsLicences settings; do mongodump -d licensify-refdata -c $c -o ~/licensifydump; done
tar cvzf licensifydump.tar.gz licensifydump/

You can then copy this file onto an integration machine (possibly via your local machine) and restore the data:

tar xvzf licensifydump.tar.gz
mongorestore licensifydump/

Confusingly, some collections exist in both the licensify and the licensify-refdata database. If db.collectionName.count() == 0 in one database, and db.collectionName.count() != 0 in the other, then you should assume that the one with objects is the source of truth.

Application Files

All newly-uploaded documents are stored within an S3 bucket; the credentials for this are provided to the application as environment variables. This feature was enabled on 2016-10-18; any documents uploaded before then are stored in GridFS (Mongo).

Anti-virus scans of uploaded documents

All documents uploaded as part of the application process are scanned using ClamAV. The process to re-check any previously uploaded files against the latest definitions is currently disabled. The risks disabling this poses are mitigated due to the fact that we are purging all applications after 90+7 days.

Licensify - supporting licensing