Skip to main content
  1. Home
  2. Applications
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 6 May 2021

Create a Local Transaction

This document describes the steps required to create a postcode-based local transaction similar to Apply for a Test and Trace Support Payment and Find a rapid lateral flow test site in your area.

Outline

[1]: These steps are manual and can be very time consuming. It is recommended they are started as early as possible to reduce delay.

[2]: This step requires a PR that can be created and deployed (once approved) at any point prior to publishing the service.

[3]: This step requires a PR that can be created and deployed (once approved) at any point.

Get details of or create the service in the Electronic Service Delivery (ESD)

Newly created services are automatically imported into Local Links Manager (LLM) from Electronic Service Delivery (ESD) via a nightly import process. So, if you know the ID of the service you want to use, check if it exists in ESD and LLM.

If the service exists in ESD but not LLM, and it is not possible to wait overnight, you can run this rake task to import them on demand.

On occasion the service you are looking to use does not exist in ESD and LLM. If this is the case, it may be possible to obtain a new service from…

Nicki Gill (ESD Project Manager)
Tel: +44 20 8570 5086
Bon Marché Centre, 241–251 Ferndale Road, London SW9 8BJ
nicki.gill@esd.org.uk | esd.org.uk

While it is not essential that the service exists in ESD or LLM before starting this process, it is preferable. However, if you are unable to create the service within a suitable timeframe, it is possible to carry on with the process as it will create the service in LLM for you anyway.

Once you’ve found the service, gather the following information:

Get a list of local authority slugs and URLs

We need to create a CSV file containing the name, slug and an empty space for a url for all available local authorities currently in LLM.

The service product owner (your PM or DM should be able to identify them for you) can then add the specific URLs for each local authority that offers the service and return the finished file to us for import. This is used to associate the URL with the service and the local authority in LLM.

Log into the LLM console…

$ gds govuk connect app-console -e integration local-links-manager

Connecting to the app console for local-links-manager, in the integration environment
The relevant hosting provider is aws
The relevant node class is backend
There are 2 machines of this class
Connecting to a random machine (number 1) #=> Make a note of this MACHINE_NO

Then in the rails console…

lgsl_code = 1234

file = "#{Rails.root}/tmp/#{lgsl_code}.csv"

# Make a note of this REMOTE_FILE_PATH...
=> "/data/vhost/local-links-manager/releases/20210507085218/tmp/1234.csv"

Generate the CSV file and exit out of the rails console.

CSV.open(file, 'w') do |csv|
  csv << ["name", "slug", "url"]
  LocalAuthority.order(name: :asc).each do |la|
    csv << [la.name, la.slug, nil]
  end
end

Download the CSV file just you just created to your local machine…

$ gds govuk connect scp-pull -e integration backend:MACHINE_NO REMOTE_FILE_PATH ~/Downloads

Substituting the MACHINE_NO and REMOTE_FILE_PATH from the earlier rails console session. For example:

$ gds govuk connect scp-pull -e integration backend:1 /data/vhost/local-links-manager/releases/20210507085218/tmp/1234.csv ~/Downloads

Hand this over to the service product owner.

The name is only present in the CSV file to assist the product owner complete the URLs as differences between the local authority name and slug can make it tricky to match the local authority correctly. It is not used when importing the links into LLM.

Add the service to Publisher

Create a PR that adds the following to the bottom of this file:

LGSL Description Providing Tier
LGSL_CODE SERVICE_DESCRIPTION PROVIDING_TIER

Where SERVICE_DESCRIPTION is the service description, and PROVIDING_TIER is the service providing tier(s).

Once your PR is merged and deployed, run this rake task in Publisher…

bundle exec rails local_transactions:fetch_and_clean

Make the service unavailable for a nation in Frontend

Note: This is an optional step that can be done when the new service is live.

If the service is unavailable in one or more devolved nation, create a PR to add the service to the Frontend local transaction configuration file.

This can be configured with or without button_text and button_link. Seek content advice with the content.

For example (given an LGSL code of 1234):

1234:
  unavailable_in:
    Scotland:
      title: "This service is not available in Scotland"
      body: "We do not know if they offer this service. Search the Scottish Government website to see if they do, or what else they offer."
      button_text: "Find information for Scotland"
      button_link: "https://www.mygov.scot"
    Northern Ireland:
      title: "This service is not available in Northern Ireland"
      body: "This service is not available in Northern Ireland. You can find other services on your council website"

Run this rake task in LLM. This creates the following internal model instances and associations:

bundle exec rails service:enable[LGSL_CODE,LGIL_CODE,SERVICE_NAME,SERVICE_SLUG]

Where SERVICE_NAME is the service name, and SERVICE_SLUG is the service slug.

Then run this rake task in Local Links Manager to add (empty) links for all available local authorities…

bundle exec rails import:missing_links

Upload the completed CSV file that was sent to the product owner in this step…

$ gds govuk connect scp-push -e integration backend LOCAL_FILE_PATH REMOTE_FILE_PATH

Run this rake task to import the links from the CSV file.

bundle exec rails import:service_links[LGSL_CODE,LGIL_CODE,REMOTE_FILE_PATH]

Note: If you intend to run the import:service_links rake task via Jenkins, you will need run scp-push against all of the backend machines. For example:

# To find out how many machines you'll need to copy the file to...
$ gds govuk connect ssh -e integration backend
There are 2 machines of this class  #=> Make a note of the number of machines
Connecting to a random machine (number 1)
$ exit

# Copy the file...
$ gds govuk connect scp-push -e integration backend:1 LOCAL_FILE_PATH REMOTE_FILE_PATH
$ gds govuk connect scp-push -e integration backend:2 LOCAL_FILE_PATH REMOTE_FILE_PATH
# ...
$ gds govuk connect scp-push -e integration backend:n LOCAL_FILE_PATH REMOTE_FILE_PATH

Add content and publish the service in Publisher

Once all of the above steps are complete, ask a content designer to create a new local transaction page in Publisher using the LGSL code and LGIL code.

Glossary

Electronic Service Delivery (ESD)

Behind each local transaction is a public service, overseen and delivered by the Local Government Association (LGA), that all local authorities should (in principle) offer and supply. These services are listed on the Electronic Service Delivery (ESD) website.

The ESD defines services as…

“…a set of actions or activities undertaken by a council (or other public sector body) to deliver a product or conclusion.”

LGSL code

A Local Government Services List (LGSL) is a number that LLM uses to uniquely identify a service. They originate in ESD where it is used as the service ID.

LGIL code

Along with services, ESD has the concept of an Interaction. Functionally, the relationship between service and interaction is many-to-many.

An interaction describes the reason, use, or purpose of the service.

Like an LGSL code, LLM uses the interaction ID from ESD to uniquely identify an interaction. In LLM this is called the Local Government Interaction List (LGIL) code.

One thing to note is that ESD has deprecated the use of interactions. LLM has not however been updated to accommodate the replacement concept in ESD. This means that services in LLM still need a relationship with one-or-more interaction in order to function correctly. If you are unsure which interaction(s) it is that you need, it is recommended that the Providing information (LGIL code 8) interaction be used as this ist generic in nature.

Seek content advice

For service details such as: name, description and slug - you must get a content designer to create them. It is highly unlikely that the details from ESD will work and the slug will be used for the URL of the service on GOV.UK.

For unavailability elements such as title and body standard text is available here.

Providing tier

A providing tier is way of identifying the levels at which a service is implemented by a local authority. A tier can be either:

  • county/unitary
  • district/unitary
  • all

In LLM each tier has a nominal level indicator that makes them hierarchical in nature.

  1. County
  2. District
  3. Unitary

This is important as, in order to present the most appropriate URL for a service to the user, the tiers are checked for a match starting at the lowest level (3) working up to the highest level (1). This way http://www.coventry.gov.uk/a-specific-serivce would be presented before http://www.coventry.gov.uk for example.

If the providing tier for a service is unknown, using all is recommended as this offers the best chance of finding the most appropriate URL.

More in the Applications section

Learn

How to...