Implementing State and Country/Territory Picklists Salesforce, Winter ’22 @salesforcedocs Last updated: July 21, 2021 © Copyright 2000–2021 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners. CONTENTS Introducing State and Country/Territory Picklists . 1 Configure State and Country/Territory Picklists . 3 Customize States and Countries . 4 Before You Scan Your Organization . 6 Scan Your Organization . 7 Prepare to Convert State and Country Data . 8 Convert State and Country Data . 9 Enable and Disable State and Country/Territory Picklists . 10 Using State and Country/Territory Picklists . 11 INTRODUCING STATE AND COUNTRY/TERRITORY PICKLISTS State and country/territory picklists let users select states, countries and territories from predefined, standardized lists, instead of entering state and country/territory data into text fields. State and country/territory picklists offer faster and easier data entry. They help to ensure cleaner data that can be harnessed for other uses—in reports and dashboards, for example. They protect data integrity by preventing typos, alternate spellings, and junk data—even in records updated through the API. State and country/territory 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 country/territory picklists in most places that state and country/territory fields are available in Salesforce, including: • Record edit and detail pages • List views, reports, and dashboards • Filters, functions, rules, and assignments State and country/territory picklists can also be searched, and they’re supported in Translation Workbench. The picklists are available in all editions except Database.com. To provide feedback on state and country/territory picklists, go to IdeaExchange. State and Country/Territory Picklist Limitations State and country/territory picklists include 239 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 country/territory picklists that contain more than 1,000 states or countries/territories can cause degraded performance. State and country/territory picklists don’t work with: • Salesforce to Salesforce • Connect Offline • Change sets If your org uses Data.com, the Data.com records can contain states, countries, and territories not included in the standard state and country/territory picklists. If your org uses these states and countries, add them to the picklist before Data.com 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) 1 Introducing State and Country/Territory Picklists Picklist labels, not code values, are displayed in reports on state and country/territory fields. To display code value abbreviations wherever your users see state, country, and territory names, manually change your State Name or Country/Territory Name labels to your code values. (For editing instructions, see Configure State and Country/Territory Picklists.) You can access your records’ state and country/territory 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/territory picklists: 1. Configure the states, countries, and territories that you want to use in your organization. 2. Scan your Salesforce data and customizations to see how they’ll be affected by the switch from text fields to picklists, and then fix anything that the switch-over might break. Scanning and fixing can be an iterative process that you repeat several times. 3. Convert existing, text-based state and country/territory data to picklist values so you can keep using your old data with the new fields. 4. Turn on the picklists for your users. This guide walks you through these four steps of setting up state and country/territory 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. 2 CONFIGURE STATE AND COUNTRY/TERRITORY PICKLISTS Configuring picklists isn’t required for you to enable state and country/territory picklists for users, but it’s 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 country/territory picklists include 239 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 country/territory picklists that contain more than 1,000 states or countries/territories 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 country/territory 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/territory picklists aren’t supported in Salesforce change sets or packages. However, you can move integration value changes for state and country/territory 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/territory picklists in your sandbox org. Then, use the Metadata API to retrieve the sandbox configurations, and deploy them to your production org. You can’t deploy new ISO codes or update ISO code values using any API. 1. From Setup, enter State and Country/Territory Picklists in the Quick Find box, then select State and Country/Territory Picklists. 2. On the State and Country/Territory Picklists page, click Configure States, Countries, and Territories. 3. 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 isn’t 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. 4. Click Edit to view and edit details for the country, including to configure its states or provinces. 5. (Optional) Under Picklist Settings, select a Default Country/Territory. The Default Country/Territory automatically populates country/territory 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. 6. 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. 3 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. 1. From Setup, enter State in the Quick Find box, then select State and Country/Territory Picklists. 2. Click Configure States, Countries, and Territories. 3. To add a country, click New Country/Territory. To edit an existing country, click Edit. 4. Under Country/Territory Information, specify your options. Country/Territory Name By default, the ISO-standard name. The name is what users see in the Salesforce user interface. Country/Territory Code By default, the two-letter ISO-standard 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 can’t edit the ISO codes of standard states or countries. You can edit the country/territory 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 country/territory code. Integration values for standard states, countries, and territories default to the full ISO-standard 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 country/territory picklists to continue to work. You can edit integration values to match values that you use elsewhere in your organization. For example, let’s say that