Enable Address Search on Portals

Overview

Many forms in Thentia Cloud Portals feature address fields to collect residential, business or mailing addresses from licensees and other members of the public. However, address fields can be prone to input errors, such as mistyped digits or spelling mistakes, which can make accurate address capture challenging.

To help prevent these issues, Thentia Cloud Portals have a built-in Address Search feature. This optional feature allows Portal users to simply search for their address in a database to automatically fill out all of the address fields correctly.

Address Search not only helps to reduce manual input errors that can result in invalid addresses being captured, but also provides a better user experience for your Portal users by making address input much easier and faster.

In this guide, you’ll learn:

• How the Address Search feature works in your Portals
• How to turn on Address Search in your Portals
• How to configure Address Search to only suggest addresses from specified countries
• How to optionally set Autoaddress as your address database provider

How it works

When Address Search is enabled, it turns the first field of any set of address fields in your Portals into a search box. Whenever a user types into this field, Address Search will query the address database (powered by Radar) for matching addresses, and will present the results as autocomplete-style suggestions:

When a user clicks on any of the suggestions, the selected address is automatically entered into the appropriate address fields:

The address fields remain editable after selecting a suggestion, so the user can make adjustments if needed (for example, if the ZIP code is incorrect).

By default, Address Search will suggest addresses from all countries. However, you can optionally configure it to only suggest addresses from specified countries, which can help to provide more relevant results for your users.

Before you begin

• To follow the instructions in this article, you must have access to:
  • The Workbench for the Thentia realm in which you want to work.
  • The Config module within that realm.
• If you want to use the Autoaddress option, you must also have:
  • An active Autoaddress subscription.
  • An Autoaddress API key (see this article for instructions on how to obtain your Autoaddress API key).

Turn on Address Search for all Portals

Address Search is an optional feature: it is disabled by default, but you can turn it on at any time.

When turned on, Address Search will be applied to all instances of standard address input fields across all Portals. Address Search can also be applied to address input fields that appear on custom pages, but this requires additional configuration — see the Additional notes about Address Search section for details.

To turn on Address Search for all of your Portals, follow these steps:

1. Log in to Workbench and open the Config module ( Modules button > Config).
2. Click on the  Menu button, then click on Portal Configuration.

3. On the Customer Site page, double-click on the Thentia Cloud Portals record (this should be the only record shown) to open it:
   

4. In the Thentia Cloud Portals tab, click on This Record > General Settings in the navigation sidebar:
   

5. Find the setting called Enable Address Search and set it to Yes:
   

6. Click the  Save this record button in the menu bar to save the change.

7. The change will take effect immediately, and all address fields in your Portals will now use Address Search.

While you are in the General Settings menu, you can also configure Address Search to only return address suggestions from specific countries. See the next section, Limit Address Search suggestions to specific countries for instructions.

Limit Address Search suggestions to specific countries

You can optionally configure Address Search to only suggest addresses located in specific countries of your choice. For example, if the address “123 Main Street” exists in the US, Canada, and Australia, but you have limited Address Search suggestions to only the United States, then Portal users who enter “123 Main Street” into an address field will not see the Canadian and Australian addresses as suggestions.

To limit Address Search suggestions to specific countries, follow these steps:

1. Open the Thentia Cloud Portals record:
   • If you are continuing directly from the previous section of this guide, you should already have this record open.
   • To open the record, go to Workbench > Configuration module. Then, click  Menu button > Portal Configuration and double-click on Thentia Cloud Portals.
2. In the Thentia Cloud Portals tab, click on This Record > General Settings in the navigation sidebar.

3. Find the setting called Address Search Country Codes (comma separated):
   

4. Enter the country code for each of the countries that you want to include in Address Search suggestions into the Address Search Country Codes (comma separated) field:

   • Enter one or more countries to limit Address Search suggestions to only addresses in the specified countries.
   • Specify a country using its two-character ISO 3166 country code. You can find all country codes on the ISO website (use the country codes in the column labelled “Alpha-2 code”), e.g. US for the United States, CA for Canada, or AU for Australia.
   • To specify multiple countries, enter country codes in any order and separate each with a comma and no space, e.g. US,CA,AU.

   • If you leave this field blank, Address Search will include addresses from all countries in address suggestions.
     

5. Click the  Save this record button in the menu bar to save the change, which will take effect immediately.

Configure Address Search to use Autoaddress

By default, Address Search uses the address database provided by Radar. If you prefer, you can optionally configure Address Search to use the address database provided by the Autoadress service instead.

When Address Search is configured to use Autoaddress, the behavior of the feature differs slightly from the default version.

In the Autoaddress version, an additional search box is displayed above all address fields in Portals (instead of the first address field acting as the search box):

Aside from this difference, the Autoaddress version of Address Search works just like the default version. Portal users can begin typing their address into the search box, and Autoaddress will provide suggestions of matching addresses:

And the user can click on any suggestion to populate the address fields:

To configure Address Search to use Autoaddress, follow these steps:

1. Turn on the Address Search feature, as described in the section Turn on Address Search for all Portals.
2. Log in to your Autoaddress account and create a new integration for your Thentia Cloud Portals to get the Autoaddress API key:
   • See this article from Autoaddress for instructions on how to create a new integration and get an Autoaddress API key.
   • During the Autoaddress integration setup, select the JavaScript Integration option.
   • When you get the API key, copy it (or keep the Autoaddress site with the API key open in a separate tab or window), as you will need to enter it in Thentia Cloud in a moment.
3. Log in to Workbench and go to any module.

4. Click on the Profile menu (your initials) in the menu bar, then click on System Settings:
   

5. In the System Settings menu, click on Configuration:
   
   

6. In the table, find the Key called thentiacloud.address.search.vendor and double-click it to open it in a new tab:
   

7. Type autoaddress into the Value field:
   

8. Click on  Save this record in the menu bar to save the change, then close the tab and return to the System Settings menu.

9. In the table, find the Key called thentiacloud.address.search.vendor.apikey and double-click it to open it in a new tab:
   

10. Copy your API key from your Autoaddress account and paste it into the Value field:
    

     Note

    The API key should be a series of letters and numbers that begins with pub_.

11. Click on  Save this record in the menu bar to save the change, then close the tab and return to the System Settings menu.

12. Beside the two Keys you edited, check that the values autoaddress and your API key are listed in the Value column of the table:
    

13. The change will take effect immediately. Open any form in your Portals that features address fields, and you should now see the Autoaddress search box:
    

Additional notes about Address Search

• The Autoaddress version of Address Search does not support the setting to limit the countries from which addresses will be suggested, as described in the section Limit Address Search suggestions to specific countries. However, Autoaddress does support “biasing” the search results it returns in various ways, and can be configured to preferentially suggest addresses in specific geographical areas. For more information on how to configure this (and the various other features available with Autoaddress), refer to the Autoaddress documentation.
• In Thentia Cloud Portals, the address field for the “subdivision” level (e.g. state, province, territory, county, etc.) can be displayed as either a dropdown field with a fixed set of selections, or as a text box that can accept any value. When Address Search is enabled, this works as follows:
  • By default, the dropdown is used if the selected country for the address is set to United States or Canada, and selecting a suggestion from Address Search will select the appropriate state or province from the dropdown.
  • For all other countries, the text box is used. If this is the case, selecting a suggestion from Address Search will enter the following into the text box:
    • If Radar is used: The full name of the subdivision, e.g. New South Wales (Australia) or Donegal (Ireland).
    • If Autoaddress is used: The ISO 3166 code for the subdivision, e.g. NSW for New South Wales, or DL for Donegal.
  • It is possible to configure any other country to use the dropdown by adding records representing that country’s subdivisions to the Province/Territory/State entity (reg_stateorprovince). In this case, when an Address Search suggestion is selected, the system will try to choose the corresponding subdivision dropdown menu option by looking for a matching record in the Province/Territory/State entity:
    • If Radar is used: The system will check the Name attribute for records that match the full subdivision name (e.g. New South Wales) provided by Radar.
    • If Autoaddress is used: The system will check the ISO attribute for records that match the ISO 3166 subdivision code (e.g. NSW) provided by Autoaddress.
    • For both Radar and Autoaddress, if no record with a matching value in the respective attribute is found, the dropdown field is left empty (no value selected).
  • Therefore, if you use Address Search and you want the subdivisions of a given country to be displayed in a dropdown menu on the address forms in your Portals, you should ensure that:
    • You have created a record for every subdivision of that country in the Province/Territory/State entity, and
    • Every record has a value in either the Name attribute (Radar) or ISO attribute (Autoaddress) that corresponds to the subdivision values returned by the selected address database service.