Licensify - supporting licensing
GOV.UK runs a Scala application (Licensify) which allows users to apply and pay for licences from local authorities and other competent authorities.
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.
The Licensing service consists of three separately deployed applications:
licensing_frontendmachine): 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.
licensing_backendmachine): 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.
licensing_backendmachine): 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 Licence Finder to locate licences on the GOV.UK frontend, but from a technical perspective this is separate from Licensify.
Licence Finder 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.
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.
The Feeds application has a UI that runs on port
9400, but that isn’t exposed publicly, so you need to tunnel to it. For example, the following will tunnel to the production instance of the Feeds admin and make it available via
gds govuk connect -e production ssh licensing_backend # Look at the output and grab the IP address, e.g. # Running command: ssh -J firstname.lastname@example.org email@example.com # now exit the machine and run this command locally, replacing the IP ssh firstname.lastname@example.org -J email@example.com -L 9400:localhost:9400 -N
Once the tunnel above has been set up, the following pages are available:
- Unprocessed applications
- Collected applications, ready to be purged
- Uncollected applications, ready to expire
- Uncollected applications, ready to purge
- Submitted applications report
Mail from Licensify is handled by GOV.UK Notify using the HTTP API. Authentication is via an API key, which is provided as a configuration parameter to the backend app servers by Puppet.
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 (SNAT) GOV.UK IP address.
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.
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. There is also a nightly process that runs on a cron to re-check any previously uploaded files against the latest definitions, but this process is currently disabled. The risks disabling this poses are mitigated due to the fact that we are purging all applications after 90+7 days.