Update Your Integrations for New Locale Formats
If you integrate data from external systems into Salesforce or if you send Salesforce data to external third parties, use locale-neutral formats whenever possible in the related code. When locale formats change, review the code that handles the affected formats.
Required Editions
| Available in: both Salesforce Classic and Lightning Experience |
| Available in: all editions |
Integration points can take many forms, including API calls to and from Salesforce. Also review processes that include exporting data into files, such as comma-separated values (CSV) files, and importing data from files into Salesforce.
Address, currency, date, datetime, integer, Name, and time formats can change when a user changes locales. Whenever possible, use standard locale-neutral methods to handle these types of data. In the absence of a standard method, update the code to accommodate the new formats.
Specific to migrating from Oracle’s Java Development Kit (JDK) formats to International Components for Unicode (ICU) locale formats, verify integrations that handle currency, date, datetime, integer, or time data.
If a third party calls into Salesforce programmatically, work with that party to test and update the process as needed when locale formats change. To search your Salesforce code, download the metadata. Then use a command-line interface such as Salesforce CLI.
Integration Example: Importing Dates
Let’s look at a simple example of how a change in a locale format can affect integrations.
In this example, we have a custom object, Conference, with two additional fields: start_date_time and end_date_time. To populate the Conference object, an Apex class fetches data
using an external API. The class could also fetch the data from a CSV file, but in this
example, we use an external API call.
The external API call returns a JSON object that contains this information. The datetime data is formatted using the JDK format for the English (United States) [en_US] locale.
{
"conferences": [{
"name": "conference1",
"start_date_time": "10/20/2021 10:00 AM",
"end_date_time": "10/22/2021 05:00 PM"
}, {
"name": "conference2",
"start_date_time": "11/21/2021 11:00 AM",
"end_date_time": "11/24/2021 05:00 PM"
}]
}This Apex code inserts the conference records.
// Mocking the sample response of API call
String jsonResponse = '{"conferences": [{"name":"conference1", "start_date_time":"10/20/2021 10:00 AM", "end_date_time":"10/22/2021 5:00 PM"}, {"name":"conference2", "start_date_time":"11/21/2021 11:00 AM", "end_date_time":"11/24/2021 05:00 PM"}]}';
Map<String, Object> results = (Map<String, Object>) JSON.deserializeUntyped(jsonResponse);
List<Object> conferences = (List<Object>) results.get('conferences');
for(Object conference: conferences) {
Map<String, Object> conferenceDetails = (Map<String, Object>)conference;
//Initialize object
Conference__c confObject = new Conference__c (
name = String.valueof(conferenceDetails.get('name')),
start_date_time__c = datetime.parse(String.valueof(conferenceDetails.get('start_date_time'))),
end_date_time__c = datetime.parse(String.valueof(conferenceDetails.get('end_date_time')))
);
//insert object
insert confObject;
}The datetime.parse() method uses the datetime format of the
personal locale of the user that executes the code.
Let’s assume that the user’s personal locale is English (United States) [en_US]. The JDK and ICU datetime formats for that locale differ.
- JDK short datetime format for en_US: 10/20/2021 10:00 AM
- ICU short datetime format for en_US: 10/20/2021, 10:00 AM
When the org uses JDK locale formats, this code runs successfully. When ICU locale formats are
enabled, this code throws a parse error because the start_date_time and end_date_time values are
missing the expected comma after the year.
This issue can also occur when data stored in Salesforce is passed to an external system using a locale-specific format, for example, when using a POST call. As with the example above, the personal locale of the user that executes the code determines the format of the data.
Remediate Issues
To avoid these issues, use locale-neutral formats when receiving, passing, and processing data.
If you find an issue with data received from an external system, contact the sender to update the format of the source data. If you can’t contact the sender, update your code to convert the received data into a locale-neutral format before processing it.
