AddressComplete component

[Abi-Nada]

User story

As a form builder / program administrator, I want to get complete and accurate addresses, So that what I collect is legitimate and what I send as correspondence gets to the right destination.

As a form filler / member of the public, I want my address to be filled in the right format, So that I can fill out the form and get access to programs and services more easily, quickly, predictably, and efficiently.

Context

AddressComplete is an address finder component developed by Canada Post, that includes real-time verification of addresses. This helps ensure the accuracy of data submitted in a form and helps people filling out a form save time.

AddressComplete takes a master international data set and supplements it with address data from some of the world’s major postal service providers to fully validate data.

This component enables a rapid searching functionality that works as you type. It includes validation for 240 countries using the official federal registry. Custom addresses can still be added if the address is not found while filling out the form.

There is a cost per API call based on a set limit of credits. As such, we will group all the fields as one block or entity to make one call per submission rather than multiple for each field.

As part of the integration and implementation we will re-use the combo-box to have the component function similarly to our type-ahead searchable list.

There is a "find" API and a "retrieve" API. Need to sort out what the costing model is and if billing for lookup calls (10c?) is only for calls to the retrieve or also the find API? How will it work with credit balances and top ups?

Links

• GC Forms Discovery work
• GC Forms AddressComplete Figma
• COVID Alert Address Autocomplete
• MOU outline
• Fields
• AddressComplete Terms and Conditions

What's involved

• [x] Integration / API
• [x] Design / content
• [x] Translation / review and edit
• [x] Review / share
• [ ] Policy / Security
  • [x] Risk discussion with Policy, Product, Dev, and Design and document risks in the risk register
  • [ ] There is a process to identify suspected spam or calls to the API
  • [ ] There is a process to temporarily or permanently stop a form's usage of AddressComplete (This could include temporarily closing the form)
• [ ] A11y considerations
• [ ] Error handling
• [ ] Deployment / release
• [ ] Measurement / tracking
  • [ ] Ideal: See costs per form, which can be aggregated by department for both testing and live forms.
  • [ ] Minimum: Validation costs can be seen at the department level and total cost.

[samsadasivan]

Started here!

[anikbrazeau]

https://docs.google.com/document/d/1ugZCOjXXLwH6Jt2zP2m8_9fzrohdvnB1ATscGznZ6C0/edit#heading=h.218poww6tt5w

[samsadasivan]

Finished up discovery/exploration work! > On to proposal mock ups > putting together a report for findings

[anikbrazeau]

Notes from meeting with Sam

• Will work like searchable list component in terms of styling and interaction
• Check component for WCAG 2.1 AA --> cannot tab into the dropdown list currently
• Works okay for international addresses, 95% accuracy for Canadian addresses
• Constraint: all address fields have to be together --> then can deconstruct, but one call to API
• AddressComplete branding from Canada post --> how to manage external component
• No decomissioning or conversion of current address form element without validation
• Consider how to scale necessary changes throughout the app
• Should the content be editable?

https://www.figma.com/design/5PqqBQR0s0Q8wkvB75pq2C/Address-complete?node-id=1-36&m=dev

[anikbrazeau]

Latest explorations: https://www.figma.com/design/5PqqBQR0s0Q8wkvB75pq2C/Address-complete?node-id=4353-6756&t=WMNIKwpE9X5mfoal-4

[anikbrazeau]

Takeaways from meeting with @hegazynourhan :

• Need flow for address that is not findable, or address that is not accurate --> think through scenarios for frustration
• Address lookup is not failsafe, must be path to customize, edit or enter manually --> how do components work together
• Find out how information is used, how it's shared with third-parties beyond intent --> potential change to T&Cs accordingly
• Potential for mention in service-level agreement if influences level of service --> risk of dependency

Also found these relevant policy docs:

• https://www.canadapost-postescanada.ca/ac/wp-content/uploads/2021/01/address-complete-eula-customer-guide.pdf
• https://www.canadapost-postescanada.ca/cpc/en/our-company/transparency-and-trust/privacy-centre/privacy-policy.page

[anikbrazeau]

Latest mock-up: https://www.figma.com/design/5PqqBQR0s0Q8wkvB75pq2C/Address-complete?node-id=4444-1575&t=JZwaQ3lF3U2wnx2p-4

[anikbrazeau]

I reached out to Canada Post and learned:

• They cannot guarantee a percentage accuracy
• All Canadian addresses in AddressComplete are supplied by the Canada Post address databases, which is the most complete and accurate source of valid mailing addresses.
• AddressComplete is one of the few solutions that offers a truly international address validation solution.
• The Canada address data is updated on the weekly and monthly basis.
• The U.S. and international addresses are updated monthly.
• The UK addresses are updated daily.

[anikbrazeau]

Latest design wireframes: https://www.figma.com/design/5PqqBQR0s0Q8wkvB75pq2C/Address-complete?node-id=4458-2427&t=szxmGV34mZlke074-4

Simplifying the address data:

"Id", "StreetAddress" {"StreetNumber",
"StreetName",
"StreetType", "StreetNumberSuffix",} "City", "ProvinceName" {"ProvinceCode",} "CountryName", {"CountryCode",} "PostalCode" "Zip", {"PostalCodePrefix", "PostalCodeSuffix",}


[srtalbot]

Basic implementation that works. Moving on to:

• integration with the form builder on a published form
• Risk analysis
• Customizability

[anikbrazeau]

Notes from risk discussion:

https://docs.google.com/document/d/1JmWpX6RaSTnl1uY-e0X4je2XPrJKeucQm8w_tBLI7TM/edit

Learnings from contacting Canada Post:

• No API for Metrics or Dashboard
• Limited number of wrong addresses that can use the “find endpoint”
• No charge for "find endpoint"

[srtalbot]

Staging env has a trial API key (for 2 more months) for AddressComplete. It pulls the information when users select fields.

Working on the review page, response and downloads, and caching.

[ShadeWyrm]

Todo: -> Bug fix for clicking Split vs Full Address needing to be selected twice. -> Response and Download Page -> Caching -> Implement "Partial Address Lookup" API call. (Ocassionally the API will return a "Send this w/ Key" to pull more results. Like Pagination but different. -> Disable Option for AdressComplete (total) and per Form

[Abi-Nada]

To do: -> Implement "Partial Address Lookup" API call. (Ocassionally the API will return a "Send this w/ Key" to pull more results. Like Pagination but different. -> Figuring out what dollar amount we want to limit to per day -> Testing

[Abi-Nada]

@anikbrazeau and @ShadeWyrm to connect on UX issue

[Abi-Nada]

Flag to @srtalbot for QA testing once this is resolved ^

[Abi-Nada]

To Do:

• [ ] Component/Cypress Testing
• [ ] Tweaking strings for implementation, UX follow up

[anikbrazeau]

QA Testing link: https://whs5lohqxjml4lvkpfz2enucau0tzxym.lambda-url.ca-central-1.on.aws/

[anikbrazeau]

For a future iteration:

• Assess current usage and user needs (what's working, missing, confusing, complicating, etc)?
• Investigate opportunities for other location collection patterns such as maps or current location?
• Combine 'address' and 'verified address' as one form element type with different variants or validation/completion attributes?
• Explore conditional address based prompts (ex: IF this province, THEN route to this part of the form ....)
• Find other opportunities to increase validation/accuracy using official data sources (ex: phone number, email, etc.)

[srtalbot]

QA Testing

OS & Browser Mac Chrome

1. Are we able to update the component preview to show a the single address complete field, rather than multiple address fields?

   

2. An addresses that is selected still shows the auto-complete entry. It is only removed on another click away.

   

Is that expected, or can we make it so that once it's selected (clicked) it just shows the entry.

3. A split address that has a custom entered address provides and error.

Steps to recreate:

• Select an AddressComplete component
• Select the "Split" option
• Publish form
• enter an address that doesn't autocomplete via copy and paste (90 Elgin St, Ottawa, On K1P 5E9 was not showing up for some reason)

4. Split address does not show up on the review page.

Steps to recreate:

• Publish a form with a "split address"
• Complete the form and go to the review page

5. Test and live responses did not have the data input and submitted in CSV, JSON, or HTML formats.

6. More of a question than a bug - where is the option to shut off address complete for a single form?

7. Tried to delete the form, but it gave me an error. (Form submissions have been downloaded and confirmed.) Also, clicking the "x" on the error notification would not close the toast message and it persisted when I navigated to other pages.

A refresh cleared the message and showed the form as deleted.

[ShadeWyrm]

1. Yes we can, but did we want to have the default have all fields selected? What makes the most sense?
2. Will fix.
3. We may need to decide how a split address should work if an address isn't found. As is the component would only allow you to do so with all fields selected. I'm not sure how this should work UX wise.
4. Unusual, I'll try and duplicate - responses should of come back correctly.
5. Related to above.
6. Not yet Implemented, as. it's not a function that exists in the application yet anywhere else and the PR is growing quite large.
7. Interesting. Not sure what caused that. I'll investigate. 8.^

[anikbrazeau]

Note:

• MOU not yet signed, cannot go live til then.
• Feature flag can hide it.
• Ship with feature flag off? (temporary key)
• Updated release with actual production API key, feature flag on

Next steps:

• Getting rid of old address field (when feature flag is off -- connected)
• QA testing
• Review bugs flagged
• Wait for MOU signing

[dsamojlenko]

Re: discussion during standup about managed data components (ie, Departments) and the possibility of creating one for Countries.

Here is the directory where we provide the managed Departments list: https://github.com/cds-snc/platform-forms-client/tree/develop/lib/managedData

The intention was that the data directory could contain multiple managed raw data sources in JSON format, and the index file would serve as the gateway to them, calling back to a mapping file that is responsible for parsing the raw json and if necessary filtering and providing the data in a format that the Combobox can use.

The JSON can come from wherever- in the case of Departments we pulled it from a CDS repo on github.

I misremembered during the meeting that I thought we had a mechanism to automatically update the Departments list from the source, but looks like we didn't get that far. That should be a consideration at some point as the source data can change over time.

This managed data is used along with a "Form Builder Template" to create the Departments component: https://github.com/cds-snc/platform-forms-client/blob/develop/form-builder-templates/departments.json

This was built as part of the Managed Data / Combobox features PR: https://github.com/cds-snc/platform-forms-client/pull/3139