in implementation guides ~ read.
State Country Picklists Impl Guide

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
Country Picklists
Salesforce Spring

salesforcedocs
Last updated February

Copyright salesforcecom inc All rights reserved Salesforce is a registered trademark of salesforcecom inc

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

CONTENTS

Introducing State and Country Picklists
Configuring State and Country Picklists
Customizing States and Countries
Before You Scan Your Organization
Scanning Your Organization
Before You Convert State and Country Data
Converting State and Country Data
Enabling and Disabling State and Country Picklists
Using State and Country Picklists

INTRODUCING STATE AND COUNTRY PICKLISTS

State and country picklists let users select states and countries from predefined standardized lists instead of entering state and country
data into text fields State and country 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 country 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 and then choose from the options that automatically populate
the state or province picklist
You can use the state and country picklists in most places that state and country fields are available in Salesforce including
Record edit and detail pages
List views reports and dashboards
Filters functions rules and assignments
State and country 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 country picklists go to IdeaExchange

State and Country Picklist Limitations
State and country picklists include countries by default They also include the states and provinces of the United States Canada
Australia Brazil China India Ireland Italy and Mexico State and country picklists that contain more than states or countries can
cause degraded performance State and country picklists do not work with
Salesforce to Salesforce
Connect Offline
Change sets
If your org uses Datacom the Datacom records can contain states and countries not included in the standard state and country 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 country fields To display code value abbreviations wherever your
users see state or country names manually change your State Name or Country Name labels to your code values For editing instructions

Introducing State and Country Picklists

see Configure State and Country Picklists You can access your records state and country code values by using the StateCode and
CountryCode fields in Workbench or the Data Loader

How to Use This Guide
There are four steps involved in preparing and transitioning your organization to state and country picklists
Configure the states and countries that you want to use in your organization
Scan your organizations 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 might be an iterative process that you need to repeat several
times
Convert existing textbased state and country 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 country 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

CONFIGURING STATE AND COUNTRY PICKLISTS

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

Integration values for state and country 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 country picklists arent supported in Salesforce change sets or packages However you can move integration value

changes for state and country 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 country 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 Country Picklists in the Quick Find box then select State and Country Picklists
On the State and Country Picklists setup page click Configure states and countries
Select from the following options
Active

Makes the country available in the Metadata API so that records that contain the country can be imported However unless you

also set it as visible the country isnt available to users in Salesforce
Visible

Makes the country available to users in Salesforce A country has to 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 Country The Default Country automatically populates country picklists
for new records in your org but users can select a different country Default countries must be both active and visible
Click Save to save your configuration
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

CUSTOMIZING 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 Country Picklists
Click Configure states and countries
Click New Country to add a country or click Edit for a listed country
Under Country Information specify your options
Country Name

By default the ISOstandard name The name is what users see in the Salesforce user interface
Country 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 country codes of custom states and countries only before you enable those states and countries for your users
Integration Value

A customizable text value that is linked to a state or country code Integration values for standard states and countries default

to the full ISOstandard state and country 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 country 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 country code US to USA the workflow rule doesnt break when you enable state and country 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 country code column in sync You can change
your organizations integration values after you enable state and country picklists However when you update your picklists
state and country 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 or
countries 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 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 isnt available to users in Salesforce
Visible

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

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

Customizing States and Countries

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 and countries 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 and country 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 country picklists
Every orgs discovery process is unique For some orgs transitioning from state and country text fields to standardized picklists is
straightforward and manageable However if state and country 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 best practices 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 country 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 country fields use BEGINS CONTAINS ISCHANGED or REGEX use ISPICKVAL with state and country

code values in your comparison functions
Scanning doesnt find personal list views and reports that use state and country metadata Individual users must update those
customizations themselves
Converted leads arent scanned State and country values arent updated on converted lead records when you enable state and
country 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

SCANNING YOUR ORGANIZATION

Scanning an organization for textbased state and country values reveals where and how textbased state and country data appears in

existing records 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
List views
Reports
Validation rules
Custom buttons and links
Workflow rules
Email templates
Field sets
Apex classes and triggers
Visualforce pages
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 Country Picklists in the Quick Find box then select State and Country Picklists
On the State and Country Picklists setup page click Scan Now and then click Scan

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

Scanning Your Organization

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

BEFORE YOU CONVERT STATE AND COUNTRY DATA

Converting existing data allows you to keep working with the data after you switch to picklists 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 and country 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 or country values not in your picklists
Also reports become unreliable when records created before you enable state and country picklists contain different state and country
values than records created using picklists
When you convert data Salesforce starts with countries 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 country 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 you should configure the picklists for your organization as described in Configuring
State and Country Picklists on page That way when picklists are enabled all updated and new records will use your specified
integration value helping to ensure consistent and accurate data in your organization

CONVERTING STATE AND COUNTRY DATA

To convert textbased state and country 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 country values and up to state values However state and country picklists that contain more than
states or countries can degrade performance
From Setup enter State and Country Picklists in the Quick Find box then select State and Country Picklists
On the State and Country Picklists setup page click Convert now
Salesforce opens the Convert Countries page This page displays all the country 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 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 or country to a valid value before saving
Repeat Steps and for other country 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 associated with that state or province
On the Confirm Changes page click Finish to return to the setup overview page Or click Finish and Enable Picklists to convert
the values and turn on state and country picklists in your org

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 Countries page and change country mappings
You can convert state and country values even after clicking Finish After picklists are enabled however you can no longer edit your
conversion mappings

ENABLING AND DISABLING STATE AND COUNTRY PICKLISTS

When you enable state and country 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 country on a record before the code field is populated

they are prompted to select a code value
From Setup enter State and Country Picklists in the Quick Find box then select State and Country Picklists
On the State and Country Picklists setup page click Enable to turn on the picklists
Note You can also enable picklists when you finish converting existing textbased data to picklist values See Converting
State and Country Data on page
To turn off state and country picklists click Disable on the State and Country Picklists setup page
Important If you disable state and country picklists
For records that you havent saved since enabling picklists state and country values revert to their original text values
For records that you have saved since enabling picklists state and country integration values replace original text values
References to state and country 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

***