API Versions for Apex Classes, Apex Triggers, and Visualforce Pages

Salesforce added the ICU locale formats in Spring ’19, which corresponded to API version 45.0. When the ICU locale formats are enabled, all Salesforce delivered functionality uses the ICU formats. However, Apex classes, Apex triggers, and Visualforce pages only use the ICU locale formats when ICU is enabled, and the API version of the Apex or Visualforce page is 45.0 or later.

Custom code and components that use API version 44.0 or earlier can’t reference the ICU locale formats because they don’t exist in that API version. In that case, the custom code and components return the JDK locale formats, even if ICU locales are enabled in the org.

Each Visualforce page, Apex class, and Apex trigger has an API version. The initial API version is always the API version of your Salesforce org when the component is created.

A new API version is available with each Salesforce release. However, Salesforce doesn’t update the API version of your Apex classes, Apex triggers, and Visualforce pages because we can’t test them for any potential issues. Ideally, you update the API version for your components and validate the code with each release, but sometimes that doesn’t happen. Therefore, for example, it’s possible for an Apex class to use API version 41.0 in an org on API version 63.0.

Salesforce Partners and independent software vendors (ISV) also use Apex classes, Apex triggers, and Visualforce pages to deliver functionality within their packages. ISVs are responsible for updating the API versions of their package components.

Example Scenario and Potential Errors

What’s the expected impact for an org has ICU locale formats enabled, and Apex Classes, Apex Triggers and Visualforce Pages that don’t meet the minimum required API version 45.0?

Let's look at Spanish (United States) [es_US] locale as an example. The JDK and ICU short date formats differ in the order that the month and day are listed.

• JDK short date format for es_US: MM/dd/yyyy (example: 2/11/2021)
• ICU short date format for es_US: dd/MM/yyyy (example: 11/2/2021)

For an org with ICU locale formats enabled, all standard and custom UI components regardless of API version will display dates in the ICU format as dd/MM/yyyy. Custom components that use version 44.0 or lower will display the incorrect date. For example, the JDK date February 11, 2021 (2/11/2021) will display in the ICU locale format as November 2, 2021 (2/11/2021).

In other scenarios, this month and day mismatch leads to an invalid date. For example, a JDK date of 11/28/2021 (MM/dd/yyyy) results in a ParseException "Invalid Date and Time" error when the ICU locale format tries to display it as (dd/MM/yyyy). The error occurs because there isn’t a 28th month.

Custom datetime fields edited in Salesforce Classic and inline edits on Visualforce pages always use the current Salesforce API version. Because of that behavior, when ICU is enabled, these custom fields and inline edits always use the ICU locale formats, regardless of the Visualforce page's API version. Your users can experience a ParseException error in two situations:

• The user makes an inline edit on a Visualforce page on API version 44.0 or earlier and saves their changes with invalid date in the ICU locale format (for example, 11/28/2021 in the es_US locale).
• The user enters a date/time in a custom field in Salesforce Classic.

To avoid these issues when ICU is enabled, ensure that your Apex classes, Apex triggers, and custom Visualforce pages use API version 45.0 or later.

Components in Managed Packages

There are two sources for Apex classes, Apex triggers, and Visualforce pages in your org. Either someone built them directly in your org, or they were included in a managed package that was installed.

Only package owners can edit the components included in a managed package. You can see items installed by a managed package in your lists, but you can’t edit them. To get updates to those items, you must install a new version of the package that contains the updates.

If you’re a package owner, update your package to use the latest API version in Apex classes, Apex triggers, and Visualforce pages that reference dates, times, integers, and currencies.