Address Lookup Frontend

This microservice provides a user interface for entering and editing addresses. Assistance is provided to the end-user for looking up their address from a database (via the backend service address-lookup).

Initially, the use-case covers only UK addresses. BFPO addresses might be added soon. The roadmap includes support for international addresses.

Functional Overview

Summary

During the utilization of address-lookup-frontend, four parties are involved:

A frontend service in the tax platform (the "calling service" here).
The user-agent (i.e. web browser) and the user who operates it (the "user" here).
The address-lookup-frontend (the "frontend" here).
The backend address-lookup, containing large national datasets of addresses (the "backend" here).

The integration process from the perspective of the calling service consists of the following steps:

Initialize a journey by issuing a request to POST /api/init where the message body is a journey configuration JSON message (see below). You should receive a 202 Accepted response with a Location header the value of which is the "on ramp" URL to which the "user" should be redirected.
Redirect the "user" to the "on ramp" URL.
The "user" completes the journey, following which they will be redirected to the "off ramp" URL (which is configured as part of the journey) with an appended id=:addressId URL parameter.
Using the value of the id parameter, you can retrieve the user's confirmed address as JSON by issuing a request to GET /api/confirmed?id=:addressId.

Initializing a Journey

The first action by any calling service must be to "initialize" an address lookup journey in order to obtain an "on ramp" URL to which the "user" is then redirected.

Initialization generates an ID which is utilized both to facilitate subsequent retrieval of the "user's" confirmed address and to prevent arbitrary access to and potential abuse of address-lookup-frontend by malicious "users".

An endpoint is provided for initialization:

URL:

/api/init
(/api/v2/init is also supported, but clients are encouraged to use the versionless endpoint.)

Methods:

POST

Message Body:

A journey configuration message in application/json format (see details of the JSON format below)

Status Codes:

202 Accepted: when initialization was successful
500 Internal Server Error: when, for any (hopefully transient) internal reason, the journey could not be initialized

Response:

No content
The Location header will specify an "on ramp" URL, appropriate for the journey, to which the user should be redirected. Currently, the journey has a TTL of 60 minutes.

Configuring a Journey

The address-lookup-frontend allows the "calling service" to customize many aspects of the "user's" journey and the appearance of the "frontend" user interface. Journey configuration is supplied as a JSON object in the body of the request to POST /api/init (see above).

It is not necessary to specify values for all configurable properties. Only supply a value for properties where it is either required or you need to override the default. Wherever possible, sensible defaults have been provided. The default values are indicated in the table detailing the options below.

Configuration JSON Format

Journey configuration is supplied as a JSON object in the body of the request to POST /api/init.

It is not necessary to specify values for all configurable properties. Only supply a value for properties where it is either required or you need to override the default. Wherever possible, sensible defaults have been provided. The default values are indicated in the table detailing the options below.

Welsh translations are enabled by default.

You can provide custom labels for the Welsh journey by adding a cy block to the config. If no custom content is provided, the default labels are used. Welsh content is displayed for users when the PLAY_LANG cookie is set to "cy". A language toggle to enable users to change their language will be displayed on all pages.

If your service doesn't have Welsh translations you can disable them setting the disableTranslations option to true. The language toggle will not be display and the PLAY_LANG cookie will be ignored.

{
  "version": 2,
  "options": {
    "continueUrl": "...",
    "homeNavHref": "..",
    "signOutHref": "..",
    "accessibilityFooterUrl": "...",
    "phaseFeedbackLink": "/help/alpha",
    "deskProServiceName": "",
    "showPhaseBanner": false,
    "alphaPhase": false,
    "disableTranslations": true,
    "showBackButtons": false,
    "includeHMRCBranding": true,
    "allowedCountryCodes": [
      "GB",
      "FR"
    ],
    "ukMode": false,
    "selectPageConfig": {
      "proposalListLimit": 30,
      "showSearchLinkAgain": true
    },
    "confirmPageConfig": {
      "showChangeLink": false,
      "showSubHeadingAndInfo": false,
      "showSearchAgainLink": false,
      "showConfirmChangeText": true
    },
    "timeoutConfig": {
      "timeoutAmount": 900,
      "timeoutUrl": "/timeout-uri",
      "timeoutKeepAliveUrl": "/keep-alive-uri"
    },
    "pageHeadingStyle": "govuk-heading-xl"
  },
  "labels": {
    "en": {
      "appLevelLabels": {
        "navTitle": "",
        "phaseBannerHtml": ""
      },
      "countryPickerLabels": {
        "title": "Custom title",
        "heading": "Custom heading",
        "countryLabel": "Custom country label",
        "submitLabel": "Custom submit label"
      },
      "selectPageLabels": {
        "title": "Choose address",
        "heading": "Choose address",
        "headingWithPostcode": "foo",
        "proposalListLabel": "Please select one of the following addresses",
        "submitLabel": "Continue",
        "searchAgainLinkText": "Search again",
        "editAddressLinkText": "Enter address manually"
      },
      "lookupPageLabels": {
        "title": "Find address",
        "heading": "Find address",
        "afterHeadingText": "We will use this address to send letters",
        "filterLabel": "Property name or number (optional)",
        "postcodeLabel": "Postcode",
        "submitLabel": "Find address",
        "noResultsFoundMessage": "Sorry, we couldn't find anything for that postcode.",
        "resultLimitExceededMessage": "There were too many results. Please add additional details to limit the number of results.",
        "manualAddressLinkText": "Enter the address manually"
      },
      "confirmPageLabels": {
        "title": "Confirm address",
        "heading": "Review and confirm",
        "infoSubheading": "Your selected address",
        "infoMessage": "This is how your address will look. Please double-check it and, if accurate, click on the <kbd>Confirm</kbd> button.",
        "submitLabel": "Confirm Address",
        "searchAgainLinkText": "Search again",
        "changeLinkText": "Edit address",
        "confirmChangeText": "By confirming this change, you agree that the information you have given is complete and correct."
      },
      "editPageLabels": {
        "title": "Enter address",
        "heading": "Enter address",
        "organisationLabel": "Organisation (optional)",
        "line1Label": "Address line 1",
        "line2Label": "Address line 2 (optional)",
        "line3Label": "Address line 3 (optional)",
        "townLabel": "Town/City",
        "postcodeLabel": "Postcode (optional)",
        "countryLabel": "Country",
        "submitLabel": "Continue"
      }
    },
    "cy": {
      "appLevelLabels": {
        "navTitle": "",
        "phaseBannerHtml": ""
      },
      "countryPickerLabels": {
        "title": "Custom title - Welsh",
        "heading": "Custom heading - Welsh",
        "countryLabel": "Custom country label - Welsh",
        "submitLabel": "Custom submit label - Welsh"
      },
      "selectPageLabels": {
        "title": "Choose address welsh",
        "heading": "Choose address welsh",
        "headingWithPostcode": "foo",
        "proposalListLabel": "Please select one of the following addresses welsh",
        "submitLabel": "Continue welsh",
        "searchAgainLinkText": "Search again welsh",
        "editAddressLinkText": "Enter address manually welsh"
      },
      "lookupPageLabels": {
        "title": "Find address welsh",
        "heading": "Find address welsh",
        "afterHeadingText": "We will use this address to send letters welsh",
        "filterLabel": "Property name or number welsh (optional)",
        "postcodeLabel": "Postcode welsh",
        "submitLabel": "Find address welsh",
        "noResultsFoundMessage": "Sorry, we couldn't find anything for that postcode. welsh",
        "resultLimitExceededMessage": "There were too many results. Please add additional details to limit the number of results. welsh",
        "manualAddressLinkText": "Enter the address manually welsh"
      },
      "confirmPageLabels": {
        "title": "Confirm address welsh",
        "heading": "Review and confirm welsh",
        "infoSubheading": "Your selected address welsh",
        "infoMessage": "This is how your address will look. Please double-check it and, if accurate, click on the <kbd>Confirm</kbd> button. welsh",
        "submitLabel": "Confirm Address welsh",
        "searchAgainLinkText": "Search again welsh",
        "changeLinkText": "Edit address welsh",
        "confirmChangeText": "By confirming this change, you agree that the information you have given is complete and correct. welsh"
      },
      "editPageLabels": {
        "title": "Enter address welsh",
        "heading": "Enter address welsh",
        "organisationLabel": "Organisation (optional) welsh",
        "line1Label": "Address line 1 welsh",
        "line2Label": "Address line 2 (optional) welsh",
        "line3Label": "Address line 3 (optional) welsh",
        "townLabel": "Town/City welsh",
        "postcodeLabel": "Postcode (optional) welsh",
        "countryLabel": "Country welsh",
        "submitLabel": "Continue welsh"
      }
    }
  }
}

Test Endpoint for journey setup

/lookup-address/test-only/v2/test-setup (GET)

Top-level configuration JSON object

Field name	Description	Optional/Required	Type	Default value
`continueUrl`	the "off ramp" URL for a user journey	Required	String	N/A
`homeNavHref`	value of the link href attribute for the GDS "home" link	Optional	String	`"http://www.hmrc.gov.uk/"`
`signOutHref`	value of the link href attribute for the Sign out link	Optional	String	`None`
`accessibilityFooterUrl`	value of the link href attribute for the "Accessibility Statement" link in the footer	Optional	String	`None`
`phaseFeedbackLink`	link to provide a user feedback link for phase banner	Optional	String	`"/help/alpha"`
`deskProServiceName`	name of your service in DeskPro. Used when constructing the "report a problem" link. Defaults to None.	Optional	String	`None`
`showPhaseBanner`	whether or not to show a phase banner (if `showPhaseBanner == true && alphaPhase == false`, shows "beta")	Optional	Boolean	`false`
`alphaPhase`	if `showPhaseBanner = true && alphaPhase == true`, will show "alpha" phase banner	Optional	Boolean	`false`
`showBackButtons`	whether or not to show back buttons on user journey wizard forms	Optional	Boolean	`false`
`includeHMRCBranding`	whether or not to use HMRC branding	Optional	Boolean	`true`
`allowedCountryCodes`	country codes list allowed in manual edit dropdown	Optional	List of Strings	All countries
`ukMode`	enable uk only Lookup and Edit mode	Optional	Boolean	`None`
`pageHeadingStyle`	specify an alternative css class for page headings, e.g `govuk-heading-xl`	Optional	String	`govuk-heading-xl`

Select page configuration JSON object

Configuration of the "select" page, in which user chooses an address from a list of search results. The select page configuration is a nested JSON object inside the journey configuration under the selectPage property.

Field name	Description	Optional/Required	Type	Default value
`proposalListLimit`	maximum number of results to display (when exceeded, will return user to "lookup" page)	Optional	Integer	`nothing`
`showSearchAgainLink`	Whether or not to show "search again" link back to lookup page	Optional	Boolean	`false`

Confirm page configuration JSON object

Configuration of the "confirm" page, in which the user is requested to confirm a "finalized" form for their address. The confirm page configuration is a nested JSON object inside the journey configuration under the confirmPage property.

Field name	Description	Optional/Required	Type	Default value
`infoSubheading`	a subheading to display above the "finalized" address	Optional	String	`"Your selected address"`
`showSearchAgainLink`	Whether or not to show "search again" link back to lookup page	Optional	Boolean	`false`
`showChangeLink`	Whether or not to show "Edit address" link back to Edit page	Optional	Boolean	`true`
`showConfirmChangeText`	Whether or not to show "confirmChangeText" displayed above the submit button	Optional	Boolean	`false`

Timeout Configuration JSON object (Optional)

Configuration of the timeout popup in which user is shown a popup allowing them to extend their session before it times out. The timeout configuration is a nested JSON object inside the journey configuration under the timeout property.

Field name	Description	Optional/Required	Type	Default value
`timeoutAmount`	the duration of session timeout in seconds (between 120 and 999999999 seconds)	Required	Int	N/A
`timeoutUrl`	the url to be redirected to on session timeout (This must be a relative URL, or a URL on the allow list.)	Required	String	N/A
`timeoutKeepAliveUrl`	keep alive url to keep the session alive on calling service (This must be a relative URL, or a URL on the allow list.)	Optional	String	N/A

Top-level label JSON object

Field name	Description	Optional/Required	Type	Default value
`navTitle`	the main masthead heading text	Optional	String	`"Address Lookup"`
`phaseBannerHtml`	text (allows HTML tags) for phase banner	Optional	String	`"This is a new service – your <a href='/help/alpha'>feedback</a> will help us to improve it."`"

Lookup page label JSON object

Labels for the "lookup" page.

Field name	Description	Optional/Required	Type	Default value
`title`	the `html->head->title` text	Optional	String	`"Find the address"`
`heading`	the heading to display above the lookup form	Optional	String	`"Find the address"`
`afterHeadingText`	text that can appear after the heading	Optional	String	`nothing`
`filterLabel`	the input label for the "filter" field	Optional	String	`"Property name or number (optional)"`
`postcodeLabel`	the input label for the "postcode" field	Optional	String	`"UK postcode"`
`submitLabel`	the submit button text (proceeds to the "select" page)	Optional	String	`"Find address"`
`noResultsFoundMessage`	message to display in infobox above lookup form when no results were found	Optional	String	`"Sorry, we couldn't find anything for that postcode."`
`resultLimitExceededMessage`	message to display in infobox above lookup form when too many results were found (see selectPage.proposalListLimit)	Optional	String	`"There were too many results. Please add additional details to limit the number of results."`
`manualAddressLinkText`	Text to use for link to manual address entry form	Optional	String	`"Enter the address manually"`

Select page label JSON object

Labels for the "select" page.

Field name	Description	Optional/Required	Type	Default value
`title`	the `html->head->title` text	Optional	String	`"Choose address"`
`heading`	the heading to display above the list of results	Optional	String	`"Choose address"`
`headingWithPostCode`	the heading to display above the list of results when a postcode is provided	Optional	String	`"Showing all results for [postcode]"`
`proposalListLabel`	the radio group label for the list of results	Optional	String	`"Please select one of the following addresses"`
`submitLabel`	the submit button text (proceeds to the "confirm" page)	Optional	String	`"Continue"`
`proposalListLimit`	maximum number of results to display (when exceeded, will return user to "lookup" page)	Optional	Integer	`nothing`
`searchAgainLinkText`	Link text to use when 'showSearchAgainLink' is true	Optional	String	`"Search again"`
`editAddressLinkText`	Link text to use for the "edit address" link	Optional	String	`"Enter the address manually"`

Confirm page label JSON object

Labels for the "confirm" page.

Field name	Description	Optional/Required	Type	Default value
`title`	the html->head->title text	Optional	String	`"Confirm the address"`
`heading`	the main heading to display on the page	Optional	String	`"Review and confirm"`
`infoSubheading`	a subheading to display above the "finalized" address	Optional	String	`"Your selected address"`
`infoMessage`	an explanatory message to display below the subheading to clarify what we are asking of the user (accepts HTML)	Optional	String	`"This is how your address will look. Please double-check it and, if accurate, click on the <kbd>Confirm</kbd> button."`
`submitLabel`	the submit button text (will result in them being redirected to the "off ramp" URL (see continueUrl)	Optional	String	`"Confirm Address"`
`searchAgainLinkText`	Link text to use when 'showSearchAgainLink' is true	Optional	String	`"Search again"`
`changeLinkText`	Link text to use for the "edit adddress" link	Optional	String	`"Change address"`
`showConfirmChangeText`	Whether or not to show "confirmChangeText" displayed above the submit button	Optional	Boolean	`false`
`confirmChangeText`	Text displayed above the submit button when 'showConfirmChangeText' is true	Optional	String	`"By confirming this change, you agree that the information you have given is complete and correct."`

Edit page label JSON object

Labels for the "edit" page.

Field name	Description	Optional/Required	Type	Default value
`title`	the html->head->title text	Optional	String	`"Enter the address"`
`heading`	the heading to display above the edit form	Optional	String	`"Enter the address"`
`organisationLabel`	the input label for the "organisation" field	Optional	String	`"Organisation (optional)"`
`line1Label`	the input label for the "line1" field (commonly expected to be street number and name); a REQUIRED field	Optional	String	`"Address line 1"`
`line2Label`	the input label for the "line2" field; an optional field	Optional	String	`"Address line 2 (optional)"`
`line3Label`	the input label for the "line3" field; an optional field	Optional	String	`"Address line 3 (optional)"`
`townLabel`	the input label for the "town" field; a REQUIRED field	Optional	String	`"Town/City"`
`postcodeLabel`	the input label for the "postcode" field; a REQUIRED field	Optional	String	`"Postal code (optional)"`
`countryLabel`	the input label for the "country" drop-down; an optional field (defaults to UK)	Optional	String	`"Country"`
`submitLabel`	the submit button text (proceeds to the "confirm" page)	Optional	String	`"Continue"`

Additional configuration options may be introduced in future; for instance to prohibit "edit", to bypass "lookup", or to modify validation procedures for international or BFPO addresses. However, the design intent is that all configuration options should always have a default value. Consequently, "calling services" should only ever need to provide overrides to specific keys, rather than re-configuring or duplicating the entire journey for each scenario.

ukMode (Optional)

When enabled:

Lookup returns Only UK Addresses; 1 link on Lookup Page is overridden; Edit Address Mode removes option to change country (Defaults to United Kingdom) and omits postcode field.

Obtaining the Confirmed Address

Once the user has completed the address lookup journey, they will be redirected to the off ramp URL specified in the journey configuration. An id parameter will be appended to the off ramp URL. Calling services may use the value of this parameter to obtain the user's confirmed address.

URL:

/api/confirmed

Example URLs:

/api/confirmed?id=ID_VALUE_FROM_APPENDED_OFF_RAMP_URL_ID_PARAMETER_HERE

Methods:

GET

Message Body:

None

Status Codes:

200 Ok: when a confirmed address was successfully obtained for the given ID
404 Not Found: when no confirmed address was found for the given ID
500 Internal Server Error: when, for any (hopefully transient) internal reason, the journey data corresponding to the ID could not be obtained

Response:

An application/json message which describes a confirmed address (see below)

Confirmed Address example JSON Format

{
    "auditRef" : "bed4bd24-72da-42a7-9338-f43431b7ed72",
    "id" : "GB990091234524",
    "address" : {
        "lines" : [ "10 Other Place", "Some District", "Anytown" ],
        "postcode" : "ZZ1 1ZZ",
        "country" : {
            "code" : "GB",
            "name" : "United Kingdom"
        }
    }
}

Note that the id attribute will not be present if the selected address was entered manually, or was an edited search result.

Mocking ALF for your journey tests

When creating your journey tests we suggest that you mock out ALF, this has the following benefits:

Your tests will complete much faster since you will bypass all the ALF screens.
Your tests will not fail when we change the ALF UI (this happens more than you may think).

Here is an example showing how to mock out ALF using mock-server (https://www.mock-server.com/), the principle is the same with any mocking library.

val mockServer: ClientAndServer = ClientAndServer.startClientAndServer(6001)
val journeyId = "some-guid" //You can randomise this if you want to run tests in parallel
val alfStubbedUrl = s"http://localhost:9028/lookup-address/$journeyId/lookup"
val urlAlfReturnsUserTo = "http://your.service/some/path"
 
// Mock the init call that is made to ALF
mockServer.when(
  HttpRequest.request()
    .withMethod("POST")
    .withPath("/api/v2/init")
).respond(
  HttpResponse.response()
    .withHeader("Location", "alfStubbedUrl")
    .withStatusCode(200)
)
 
// Create a mock that will emulate the handover from your service -> ALF, and then ALF -> your service
mockServer.when(
  HttpRequest.request()
    .withMethod("GET")
    .withPath(alfStubbedUrl)
).respond(
  HttpResponse.response()
    .withHeader("Location", urlAlfReturnsUserTo)
    .withStatusCode(303)
)
 
// Create your expected ALF address response using the models defined in ALF
// You will need to add the following to your dependencies to pull in these models
// "uk.gov.hmrc" %% "address-lookup-frontend" % "2.+" % Test
val expectedAlfResponse = Json.toJson(
  ConfirmedResponseAddress(
    auditRef = "some-ref",
    id = Some("123456789"),
    address = ConfirmedResponseAddressDetails(
      organisation = Some("organistation"),
      lines = Some(List("1 test Street")),
      postcode = Some("TE5 5TD"),
      country = Some(Country("UK", "United Kingdom")),
      poBox = None
    )
  )
)
 
//Mock the request that collects the data that the user has entered in ALF using the above expected response
mockServer.when(
  HttpRequest.request()
    .withMethod("GET")
    .withPath(s"/v2/confirmed?id=$journeyId")
).respond(
  HttpResponse.response()
    .withHeader("Content-Type", "application/json")
    .withBody(expectedAlfResponse.toString())
    .withStatusCode(200)
)

When you start your service up in service manager you will need to configure it to point the request to ALF into the mock you have configured above (you will obviously need to update the configuration keys and relevant ports in the below config). When mocking out services it is best to use ports 6001 - 6010 so that your service can interact with the mock when running on Jenkins, see here for more information.

sm --start YOUR_SERVICE -r --appendArgs '{                                                                                                             
  "YOUR_SERVICE": [
    "-J-Dmicroservice.services.adress-lookup-frontend-api.port=6001",
    "-J-Dmicroservice.services.addres-lookup-frontend-web.port=6001",
  ]
}'

Running the Application

Ensure that mongo is running. If you don't have mongodb installed locally you can run it in docker using the following command:

docker run -d --rm --name mongodb -p 27017-27019:27017-27019 mongo:4

Start the required services using the following SM profile:

sm --start ADDRESS_LOOKUP_SERVICES; sm --stop ADDRESS_LOOKUP_FRONTEND

run with sbt "run 9028 -Dapplication.router=testOnlyDoNotUseInAppConf.Routes" (when in the address-lookup-frontend folder)

go to localhost:9028/lookup-address/test-only/v2/test-setup if not running from another service

License

This code is open source software licensed under the Apache 2.0 License

Name		Name	Last commit message	Last commit date
Latest commit History 780 Commits
app		app
conf		conf
docs		docs
it/test		it/test
project		project
public		public
test		test
.gitignore		.gitignore
DEPRECATED.md		DEPRECATED.md
LICENSE		LICENSE
README.md		README.md
build.sbt		build.sbt
repository.yaml		repository.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Address Lookup Frontend

Functional Overview

Summary

Initializing a Journey

Configuring a Journey

Configuration JSON Format

Test Endpoint for journey setup

Top-level configuration JSON object

Select page configuration JSON object

Confirm page configuration JSON object

Timeout Configuration JSON object (Optional)

Top-level label JSON object

Lookup page label JSON object

Select page label JSON object

Confirm page label JSON object

Edit page label JSON object

ukMode (Optional)

Obtaining the Confirmed Address

Confirmed Address example JSON Format

Mocking ALF for your journey tests

Running the Application

License

About

Releases 301

Packages

Contributors 45

Languages

License

hmrc/address-lookup-frontend

Folders and files

Latest commit

History

Repository files navigation

Address Lookup Frontend

Functional Overview

Summary

Initializing a Journey

Configuring a Journey

Configuration JSON Format

Test Endpoint for journey setup

Top-level configuration JSON object

Select page configuration JSON object

Confirm page configuration JSON object

Timeout Configuration JSON object (Optional)

Top-level label JSON object

Lookup page label JSON object

Select page label JSON object

Confirm page label JSON object

Edit page label JSON object

ukMode (Optional)

Obtaining the Confirmed Address

Confirmed Address example JSON Format

Mocking ALF for your journey tests

Running the Application

License

About

Resources

License

Stars

Watchers

Forks

Releases 301

Packages 0

Contributors 45

Languages

Packages