Skip to content

Prepare Your Address Data for the Custom Address Field Type in Salesforce

Note: This article covers Salesforce's Address compound field type, which enforces the State and Country/Territory Picklists. It uses AddressTools standardisation to prepare existing text-field address data before a migration to that field type.

State and Country/Territory Picklists are enforced for all Salesforce Address compound fields, regardless of an org's existing settings. Picklists give a neat way of ensuring clean data at the point of entry, but bring integration, customisation and maintenance considerations to weigh up. Orgs that stay with text fields for country and state have no need to change; the standardisation approach below is still useful for keeping data in those text fields consistent.

Why Standardisation Matters First

Keeping data clean is the driving force behind Salesforce enforcing State and Country/Territory Picklists for the compound field type. Migrating from five custom text fields to a single address compound field requires that data to be standardised first.

This guide covers two approaches to standardising existing data using AddressTools:

  1. Create a standardisation trigger and run a mass update to execute the logic.
  2. Export a standardised list of address data ready for reimporting into Salesforce.

Both approaches share the same initial configuration steps.

The Use Case

The example used here is a custom object called Warehouse__c, holding five custom text fields that together form an address block: Street, City, State, Postal Code and Country. The fields are populated from web forms, integrations and user entries, so the data cannot be assumed to already be standardised.

Installing AddressTools

If AddressTools is not already installed, install it from AgentExchange (formerly AppExchange). This can be done in a sandbox to test the functionality before moving to production. AddressTools is a paid product with a free trial.

After installation, on the AddressTools Administration tab's Installation sub-tab:

  1. Under Installation, select Create Token.
  2. Under Data Installation, select Get Started.
  3. Optionally choose Only install sample data if storage is limited, noting that this does not populate the alternative country and state values that expand the acceptable standardisation data.
  4. Select Install, and confirm the storage warning.

Disabling the Out-of-the-Box Triggers

A trigger ships out of the box for Account, Contact, Contract and Lead. On a fresh install, disable these so existing business processes are not affected while functionality is being enabled:

  1. Select Settings from the left navigation.
  2. Scroll to Trigger Settings.
  3. Disable each trigger.
  4. Select Save.

If the address fields to standardise exist on one of these four objects, the trigger can be re-enabled later.

Configuring the Address Block

Configure AddressTools with each of the text fields, so it can standardise the custom country and state fields.

  1. On AddressTools Administration, select Address Blocks from the left navigation.
  2. Use Add in the top right.
  3. Select the object holding the address block, for example Warehouse__c.
  4. If record types are enabled on the object, leave None selected.
  5. Select Next.
  6. Under Postal Address Fields, select the relevant field for each of Country, State, City, ZIP/Postal Code and Street.
  7. Scroll to Global Settings.
  8. Select Standardize Country and Standardize State.
  9. Select Save.

Configuring Standardisation Values

Standardisation converts multiple acceptable values to a single value. For example, Egypt has these acceptable formats:

Format Value
Full name Egypt
ISO-2 EG
ISO-3 EGY
Local name (Latin characters) Mișr
Local name (Native characters) مِصر

Each is automatically accepted in text fields configured with AddressTools, and standardised to the chosen format when the trigger runs.

For names that fall outside those five fields, such as England, Scotland or Wales for the United Kingdom, AddressTools provides the Alternative Country Names object:

  1. On a country record, select Related.
  2. Select Alternative Country Names.
  3. Select New.
  4. Set Alternative Country Name to the value.
  5. Set Original Country to the country.
  6. Set Is Obsolete to unchecked.
  7. Select Save.

An Alternative State Names object is available on each country's related list in the same way, for common misspellings or abbreviations.

Defining the Standardised Formats

Set the state format on the Country record:

  1. Navigate to the Country record, for example United States.
  2. Select or clear Use Subcountry Code in State field to standardise the state to its ISO value (TX) or full name (Texas).

Set the country format for the org:

  1. Go to AddressTools Administration > Settings.
  2. Use the pencil icon next to Standardization Enabled.
  3. Select Standardization Enabled.
  4. Edit Country Standardization Format to the desired format.
  5. Select Save.

Both settings can be changed later. A mass update job is required to re-standardise existing data to a new format.

Standardising the Existing Data

Two options are available. Both first require the trigger to be enabled for the object being standardised.

If the object is Account, Contact, Contract or Lead:

  1. Go to AddressTools Administration > Settings.
  2. Scroll to Trigger Settings.
  3. Enable the trigger for the object.
  4. Select Save.

If the object is a custom object, create a trigger:

  1. Go to Setup > Object Manager.
  2. Locate the object and select Triggers > New.
  3. Replace the code with:
trigger ValidateOBJECTLABELCountryFields on OBJECTAPI (before insert, before update) {
    pw_ccpro.CountryValidator2.Validate(Trigger.new, Trigger.oldMap);
}
  1. Replace OBJECTLABEL with the object's label and OBJECTAPI with its API name.
  2. Select Save.

Then, in AddressTools Administration > Settings, under Feature Enablement, select Standardization Enabled and confirm Country Standardization Format is set as required.

To test, edit a record's country to a variant of its current value (for example USA instead of United States) and save it: the value should standardise to the configured format.

Option 1: Mass Update

Once the trigger is verified, invoke it against every existing record by running an update on the whole object. See How to Fire a Trigger for Existing Records in Salesforce Using Flows for one approach.

Values that do not match the installed data will need manual intervention: add the value to the Alternative Country or State Names objects and re-run the process to catch them.

Option 2: Export a Standardised File for Reimporting

For every record on the configured object that can be standardised, the export contains the record ID, the current text field values, and the standardised versions. Records already in the desired format, or containing an unrecognised value, are excluded.

  1. Go to AddressTools Administration > Settings.
  2. Under Feature Enablement, select Standardization Enabled.
  3. Confirm Country Standardization Format is set as required.
  4. Set Batch Verification Alerts Email Address to a monitored address.
  5. Select Save.

This process sends an email, so check Setup > Deliverability and set Access Level to All email if needed, noting the existing setting to revert to afterwards.

Run the export from the Developer Console:

  1. Select the cog, then Developer Console.
  2. Select Debug > Open Execute Anonymous Window.
  3. Enter:
pw_ccpro.BatchValidateAndGenerateCSV m = new pw_ccpro.BatchValidateAndGenerateCSV('OBJECTAPI');
Database.executeBatch(m);
  1. Replace OBJECTAPI with the object's API name.
  2. Select Execute.

On completion, an email arrives with a CSV attachment containing the standardised data, ready to import into the existing fields or to migrate into the new State and Country/Territory Picklist fields. Match records by the record ID in the file.

Note: Back up data before running a mass update operation in a production environment.