State Country Picklists Impl Guide

DOWNLOAD

First things first !
To download this implementation guide, click the download button below.
If you need more information about the implementation guide, you can read the Table of Contents below.

Download

Implementing State and
CountryTerritory Picklists
Salesforce Spring

salesforcedocs
Last updated November

names and marks Other marks appearing herein may be trademarks of their respective owners

Introducing State and CountryTerritory Picklists
Configure State and CountryTerritory Picklists
Customize States and Countries
Before You Scan Your Organization
Scan Your Organization
Prepare to Convert State and Country Data
Convert State and Country Data
Enable and Disable State and CountryTerritory Picklists
Using State and CountryTerritory Picklists

INTRODUCING STATE AND COUNTRYTERRITORY PICKLISTS

State and countryterritory picklists let users select states countries and territories from predefined standardized lists instead of entering
state and countryterritory data into text fields State and countryterritory picklists offer faster and easier data entry They help to ensure
cleaner data that can be harnessed for other usesin reports and dashboards for example They protect data integrity by preventing

typos alternate spellings and junk dataeven in records updated through the API

State and countryterritory picklists are available in the shipping billing mailing and other address fields in the account campaign
members contact contract lead order person accounts quotes and service contracts standard objects The picklists are also available
for managing users and companies in Setup To use the picklists first choose the country or territory and then choose from the options
that automatically populate the state or province picklist
You can use the state and countryterritory picklists in most places that state and countryterritory fields are available in Salesforce
including
State and countryterritory picklists can also be searched and theyre supported in Translation Workbench
The picklists are available in all editions except Databasecom
To provide feedback on state and countryterritory picklists go to IdeaExchange

State and CountryTerritory Picklist Limitations
State and countryterritory picklists include countries and territories by default They also include the states and provinces of the
United States Canada Australia Brazil China India Ireland Italy and Mexico State and countryterritory picklists that contain more than
states or countriesterritories can cause degraded performance State and countryterritory picklists dont work with
Salesforce to Salesforce
Connect Offline
Change sets
If your org uses Datacom the Datacom records can contain states countries and territories not included in the standard state and
countryterritory picklists If your org uses these states and countries add them to the picklist before Datacom users can add or clean
these records

American Samoa AS

Guam GU

Hong Kong HK

Marshall Islands MH

Netherlands Antilles AN

Northern Mariana Islands MP

Serbia and Montenegro CS

United States Minor Outlying Islands UM

Picklist labels not code values are displayed in reports on state and countryterritory fields To display code value abbreviations wherever
your users see state country and territory names manually change your State Name or CountryTerritory Name labels to your code
values You can access your records state and countryterritory code values by using the StateCode and CountryCode fields in
Translation Workbench or the Data Loader

Introducing State and CountryTerritory Picklists

How to Use This Guide
There are four steps involved in preparing and transitioning your organization to state and countryterritory picklists
Configure the states countries and territories that you want to use in your organization
Scan your Salesforce data and customizations to see how theyll be affected by the switch from text fields to picklists and then fix
anything that the switchover might break Scanning and fixing can be an iterative process that you repeat several times
Convert existing textbased state and countryterritory data to picklist values so you can keep using your old data with the new
fields
Turn on the picklists for your users
This guide walks you through these four steps of setting up state and countryterritory picklists for your organization Then it shows you
a little bit about how to work with the new fields so you can train your users
All of the setup tasks in this guide require the Modify All Data permission Scanning your organization also requires the Create
Documents permission

CONFIGURE STATE AND COUNTRYTERRITORY PICKLISTS

Configuring picklists isnt required for you to enable state and countryterritory picklists for users but its highly recommended Configuring
picklists helps ensure continuity and data integrity with existing state country and territory data and customizations
When configuring states countries and territories you start with countries and territories and then drill down to their states or provinces
State and countryterritory picklists include countries and territories by default They also include the states and provinces of the
United States Canada Australia Brazil China India Ireland Italy and Mexico State and countryterritory picklists that contain more than
states or countriesterritories can cause degraded performance For the complete list of default countries see Standard Countries
and Territories for Address Picklists
Note

Integration values for state and countryterritory picklists can also be configured through the Metadata API For more information

read about the AddressSettings component in the Metadata API Developer Guide

State and countryterritory picklists arent supported in Salesforce change sets or packages However you can move integration

value changes for state and countryterritory picklists between sandbox and production orgs by using the Metadata API To

edit the existing states and countries in a picklist configure your state and countryterritory picklists in your sandbox org Then

use the Metadata API to retrieve the sandbox configurations and deploy them to your production org You cant deploy new

ISO codes or update ISO code values using any API

From Setup enter State and CountryTerritory Picklists in the Quick Find box then select State and
CountryTerritory Picklists
On the State and CountryTerritory Picklists page click Configure States Countries and Territories
On the Configure States Countries and Territories page select from the following options
Active

Makes the country or territory available in the Metadata API so that records that contain the country or territory can be imported

However unless you also set it as visible the country or territory isnt available to users in Salesforce
Visible

Makes the country or territory available to users in Salesforce A country or territory must be active before you can make it visible

Click Edit to view and edit details for the country including to configure its states or provinces
Optional Under Picklist Settings select a Default CountryTerritory The Default CountryTerritory automatically
populates countryterritory picklists for new records in your org but users can select a different country or territory Default countries
and territories must be both active and visible
To save your configuration click Save
Note Active states and countries not marked Visible are still valid filter lookup values You can use invisible states and
countries when creating filters in reports list views workflows and so on

CUSTOMIZE STATES AND COUNTRIES

To add or edit a state or province navigate to its detail page through the detail page of its associated country
From Setup enter State in the Quick Find box then select State and CountryTerritory Picklists
Click Configure States Countries and Territories
To add a country click New CountryTerritory To edit an existing country click Edit
Under CountryTerritory Information specify your options
CountryTerritory
Name

By default the ISOstandard name The name is what users see in the Salesforce user interface

CountryTerritory
Code

By default the twoletter ISOstandard code If you change an ISO code the new value must be

unique Codes are case insensitive and must contain only ASCII characters and numbers You cant

edit the ISO codes of standard states or countries You can edit the countryterritory codes of custom

states countries and territories only before you enable those states countries and territories for
your users

Integration Value

A customizable text value that is linked to a state or countryterritory code Integration values for

standard states countries and territories default to the full ISOstandard state country and territory

names Integration values function similarly to the API names of custom fields and objects

Configuring integration values allows integrations that you set up before enabling state and
countryterritory picklists to continue to work
You can edit integration values to match values that you use elsewhere in your organization For

example lets say that you have a workflow rule that uses USA instead of the default United

States as the country name If you manually set the integration value for countryterritory code

US to USA the workflow rule doesnt break when you enable state and countryterritory picklists

When you update a code value on a record that records StateProvince text only
or Country text only column is populated with the corresponding integration value
Likewise when you update a state or country text only column with a valid integration
value we keep the corresponding state or countryterritory code column in sync You can change
your organizations integration values after you enable state and countryterritory picklists However
when you update your picklists state and countryterritory integration values the integration values
on your records arent updated Name values arent stored on records Instead theyre retrieved
from Salesforce based on a records State Code or Country Code value If the states
countries or territories in your picklists have different field values for Name and Integration
Value make sure your report or list view filters use the correct values Use names in State and
Country filters and use integration values in State text only and Country
text only filters Otherwise your reports can fail to capture all relevant records

Active

Makes the country or territory available in the Metadata API so that records can be imported that

contain the country However unless you also set it as visible the country or territory isnt available
to users in Salesforce

Visible

Makes the country or territory available to users in Salesforce A country or territory must be active

before you can make it visible

Customize States and Countries

If youre adding a country click Add
If youre editing a country specify the options for States
Active

Makes the state available in the Metadata API so that records can be imported that contain the

state However unless you also set it as visible the state isnt available to users in Salesforce

Visible

Makes the state available to users in Salesforce A state must be active before you can make it visible

Click either of the following if desired
New State to add a custom state or province On the New State page specify a State Name State Code and
Integration Value and select whether the new state is Active or Visible To save the new state click Add
Edit to view and edit state or province details including the State Name State Code and Integration Value
Click Save

BEFORE YOU SCAN YOUR ORGANIZATION

After you configure the states countries and territories that you want to use in picklists its time to scan your organization to see how
it will be affected by the change
This discovery process shows you where and how state country and territory data appears in your org The process also shows where
this data is used in customizations such as list views and reports After youve analyzed the scan results you can plan to convert your
data update your customizations and turn on state and countryterritory picklists
Every orgs discovery process is unique For some orgs transitioning from state and countryterritory text fields to standardized picklists
is straightforward and manageable However if state and countryterritory metadata is used extensively throughout an org the transition
can be a complicated and timeconsuming process Salesforce recommends that you scan your org early and often so that you can
transition smoothly to the new lists Keep these recommendations and considerations in mind
Scanning doesnt convert data or fix your customizations Convert your data separately and update your customizations individually
You can continue to work normally in your org during the scan
The scanning process identifies affected managed packages but doesnt provide a mechanism for addressing packaging issues
Scanning doesnt find formulas that include state and countryterritory metadata
You cant use display values in validation rules or workflow rules that use comparison formula functions If your validation or workflow

rules on state or countryterritory fields use BEGINS CONTAINS ISCHANGED or REGEX use ISPICKVAL with state and

countryterritory code values in your comparison functions
Scanning doesnt find personal list views and reports that use state and countryterritory metadata Individual users must update
those customizations themselves
Converted leads arent scanned State country and territory values arent updated on converted lead records when you enable state
and countryterritory picklists
Scan your org multiple times After you update a customization rescan to make sure that your changes fixed the problem and didnt
create new ones

SCAN YOUR ORGANIZATION

For example you can see all the ways United States is saved as a text value such as US US America Estados Unidos and even misspelled

entries like Untied States In addition scanning shows you where state and country data is used in customizations including
When the scan is complete you receive emails with links to detailed reports one on address data and one on customizations After
analyzing the reports begin the tasks of converting existing data to picklist values and updating customizations so that they work with
the new picklist fields
From Setup enter State and CountryTerritory Picklists in the Quick Find box then select State and
CountryTerritory Picklists
On the State and CountryTerritory Picklists setup page click Scan for state and countryterritory data
On the Scan for Affected Data and Customizations page click Scan for State and CountryTerritory Data
Wait for an email that contains the results
Depending on the size and complexity of your organization the results take anywhere between a few minutes and a few hours to
generate
Note The emails are sent from noreplysalesforcecom They have the subject line Salesforce Address Data Scan or
Salesforce Address Customization Scan If you dont receive the emails make sure that they werent caught in a spam filter
Click the link in each email to go to a document that contains the report of affected data or customizations
On the Document detail page click View file
You can use the reports to understand and plan how to update your customizations so that you minimize disruptions to your users
productivity when picklists are enabled

PREPARE TO CONVERT STATE AND COUNTRY DATA

Converting existing data allows you to keep working with the data after you switch to picklists
For example say you have a report that culls all your sales reps leads in Washington state The report is generated from state picklist

value Washington To ensure that records with textbased state values such as Wash WA and Washington are included in the report

convert textbased state data to standardized picklist values
Converting existing state country and territory text data into standardized picklist values helps ensure data integrity after you enable
picklists in your organization Your users encounter validation errors when saving records that contain state country or territory values
that arent in your picklists Also reports become unreliable when records created before you enable state and countryterritory picklists
contain different state country and territory values than records created using picklists
When you convert data Salesforce starts with countries and territories then goes on to states As you go through the conversion process
here are a few things to keep in mind
Save frequently You can exit the conversion tool and return to it at any time
You can continue to work normally in your organization while converting data
You cant convert data while youre scanning for affected data and customizations or while state or countryterritory picklists are
being deployed
Steps can be repeated and undone at any time until you enable the picklists for users After the picklists are enabled you cant undo
the conversion
If you use Datacom Clean we recommend that you suspend Clean jobs until the conversion is finished
Finally before you convert state and country values configure the picklists for your organization as described in Configure State and
CountryTerritory Picklists on page That way when picklists are enabled all updated and new records use your specified integration
value helping to ensure consistent and accurate data in your organization

CONVERT STATE AND COUNTRY DATA

To convert textbased state and countryterritory data to picklistcompatible values select specific text values and choose the standard
values you want to map them to

For example you can select all occurrences of USA and change them to United States

Convert countries first and then states and provinces
You can convert up to countryterritory values and up to state values However state and countryterritory picklists that
contain more than states or countries can degrade performance
From Setup enter State and CountryTerritory Picklists in the Quick Find box then select State and
CountryTerritory Picklists
On the State and CountryTerritory Picklists page click Convert identified data
Salesforce opens the Convert States Countries and Territories page This page displays all the country and territory text values that
appear in your org and the number of times each value is used
Select Change for one or more values you want to convert For example select Change for all the iterations of United States
In the Change To area choose the country or territory that you want to convert the text values to and click Save to Changelist
Note If you map states or countries to Unknown value users see states and countries in their records However your
users encounter errors when they save records unless they change each state country and territory to a valid value before
saving
Repeat Steps and for other country and territory values such as for Canada
Salesforce tracks planned changes in the Changelist area
When all the countries are mapped click Next to convert state values
Use the Country of Origin column to identify the country or territory associated with that state or province
To convert the values and turn on state and countryterritory picklists in your org click Finish and Enable Picklists on the Confirm
Changes page Or to return to the State and CountryTerritory Picklists page click Finish

A few words about undo

On the Convert Countries or Convert States page click Undo at any time to revert values in the changelist
On the Convert States page click Previous to return to the Convert States Countries and Territories page and change country and
territory mappings
You can convert state country and territory values even after clicking Finish After picklists are enabled however you can no longer
edit your conversion mappings

ENABLE AND DISABLE STATE AND COUNTRYTERRITORY

PICKLISTS

When you enable state and countryterritory picklists the picklists are immediately available to users

However it can take some time for Salesforce to populate the ISO code fields on existing records If users try to edit the state or

countryterritory on a record before the code field is populated theyre prompted to select a code value
From Setup enter State and CountryTerritory Picklists in the Quick Find box then select State and
CountryTerritory Picklists
On the State and CountryTerritory Picklists setup page click Enable Picklists for Address Fields to turn on the picklists
Note You can also enable picklists when you finish converting existing textbased data to picklist values See Convert State
and Country Data on page
To turn off state and countryterritory picklists click Disable on the State and CountryTerritory Picklists setup page
Important If you disable state and countryterritory picklists
For records that you havent saved since enabling picklists state and countryterritory values revert to their original text
values
For records that you have saved since enabling picklists state country and territory integration values replace original
text values
References to state and countryterritory picklists in customizationssuch as workflow field updates email templates
and Visualforce pagesbecome invalid
Columns and filters that refer to picklist fields in reports and list views disappear

USING STATE AND COUNTRYTERRITORY PICKLISTS

After you set up and enable state and countryterritory picklists users work with them in much the same way as they currently work
with other address fields and picklists in Salesforce standard objects They can add or edit their values in records use them to create list
views and reports search on them and more In most cases using state and countryterritory picklists dont present a steep learning
curve
Note After enabling state and countryterritory picklists users can see state and countryterritory field names appended with
text only This means that
The field contains old state and countryterritory text values that you specified before picklists were enabled Or
The field contains the integration value that you specified as a picklist value
Choose picklist fields instead of textonly fields in reports list views and so on to ensure more consistent display of your state
and countryterritory data

Creating Records Using State and CountryTerritory Picklists
You can use state and countryterritory picklists on all standard objects that have address fields This means you can use them in records
for accounts campaign members contacts contracts leads person accounts quotes and service contacts First you select the country
then the state or province
Click the tab for a standard object such as Accounts
Click New
For Billing Country choose United States

For Billing State choose a state