The following list shows some sample phone number formats that are currently tested and supported by the Local Time Application.

The following table shows the correct and minimum required values that the Local Time Application needs for the Country, and State fields in Salesforce. If the table consists of blank cells for State for some countries, it means that a value for State is not needed for the application for these countries.

For the country field, you can use the full country name or the country code shown in the table below.
For the state field, you can use the full state name or the state code shown in the table below.

Note 1: The country names should follow the ISO 3166-1 standard: http://en.wikipedia.org/wiki/ISO_3166-1.

Note 2: The 2 or 3 letter country codes should follow the ISO 3166-1 standard:
http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

The upgrade procedure is similar to the installation procedure. Get the latest version of the App from AppExchange or use the installation link that we have sent you.
Simply follow Step 1 to Step 6 as described in 4. Installation & Setup. It is important that you click the Save button in the Local Time Config tab after the upgrade. This will ensure that all the latest data and options are applied from the upgraded version.

Following the aforementioned step, the upgrade process is now successfully completed, ensuring the App is up-to-date and ready for optimal performance.
 

The Local Time Application is dependent on certain fields in the Accounts, Contacts, and Leads pages to compute the correct time for the destination location.

The following are the default fields where correct data is needed. Please refer to Appendix A – Supported Country List to identify the correct values for each country.

Account: Billing Country, Billing State/Province

Contact: Mailing Country, Mailing State/Province

Lead: Country, State/Province

In cases when the Local Time Application could not calculate the time based on the above fields (because the address data is incomplete or inaccurate), it attempts to calculate the time based on the phone field instead.

The following are the default fields where correct data is needed. Please refer to Appendix B – Supported Phone Formats to identify which phone formats are currently supported by the Application.

Account: Phone

Contact: Phone

Lead: Phone

NOTE 1: If the data in the above fields is incomplete or inaccurate, the local time field shows the value Unknown.

NOTE 2: From the Local Time Config tab, you can customize the App to use different address and phone fields instead of the above default fields.

Salesforce developers can also access timezone information by making calls to the Local Time API from Apex. Following are the available API methods.

1. tz.LocalTimeV2.getTimezones

Returns a JSON array containing a list of items of custom apex subclass type TimezoneResponse. For each item in the request, you will get a corresponding item in the response.

Signature

global static String tz.LocalTimeV2.getTimezones(String request)

Parameters

request
Type: A JSON array containing a list of items of custom apex subclass type TimezoneRequest.

Return Value

Type: String

Example

public class LocalTimeAPITest {

    // sub class to store the timezone request information
    public with sharing class TimezoneRequest {
        public String id; // record id or some unique key
        public String country;
        public String state;
        public String city;
        public String postalcode;
        public String phone;
        public Boolean adjust_dst; // set it to true if data needs to be adjusted for DST
        public Boolean broad_match; // set it to true if result does not need to be very clear-cut or definitive
    }

    // sub class to store timezone response
    public with sharing class TimezoneResponse {
        public String id; // record id or some unique key
        public Decimal offset;
        public Decimal dst_offset;
        public String abbreviation;
        public String dst_abbreviation;
        public String tz_name;
        public String dst_tz_name;
        public String tz_iana; // timezone by iana org
        public String tz_sfdc; // salesforce timezone
        public String dst_setting; // Id of the DST_Setting__c record
        public String system_country; // country name in the database
        public String system_state; // state name in the database
    }

    // Get the timezones for a given request
    // if the request is ambiguous, all available timezones are returned
    // if the request is unambiguous, exact timezone is returned
    public static void testgetTimezones() {
        List<TimezoneRequest> tz_reqs = new List<TimezoneRequest>();

        TimezoneRequest tz_req = new TimezoneRequest();
        tz_req.id = '100';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.adjust_dst = true;
        tz_req.broad_match = true;
        tz_reqs.add(tz_req); // ambiguous and broad match is set to true, so we expect to get two records for this request as Texas observes two timezones

        tz_req = new TimezoneRequest();
        tz_req.id = '200';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // ambiguous but broad match is false, so we expect to get one record with the widely used timezone in Texas

        tz_req = new TimezoneRequest();
        tz_req.id = '300';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.postalcode = '79910';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one record for this request
        // it does not matter if you set broad_match to true or false

        tz_req = new TimezoneRequest();
        tz_req.id = '400';
        tz_req.country = 'Germany';
        tz_req.adjust_dst = false;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one record for this request
        // it does not matter if you set broad_match to true or false

        tz_req = new TimezoneRequest();
        tz_req.id = '500';
        tz_req.country = 'USA';
        tz_req.phone = '+1 212 1234'; // New York
        tz_req.adjust_dst = false;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one timezone record based on phone area code as New York observes one timezone

        tz_req = new TimezoneRequest();
        tz_req.id = '600';
        tz_req.country = 'USA';
        tz_req.state = 'CA';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one timezone record as California observes one timezone

        String request = JSON.serialize(tz_reqs);
        String resp = tz.LocalTimeV2.getTimezones(request); // make the API call

        Map<String, List<TimezoneResponse>> map_tzones = (Map<String, List<TimezoneResponse>>)JSON.deserialize(resp,Map<String, List<TimezoneResponse>>.class);

        List<TimezoneResponse> tzones = map_tzones.get('100');
        system.debug(tzones);
        // Expected response - two records
        /* (TimezoneResponse:[abbreviation=CDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=100, offset=-5, system_country=USA, system_state=TX, tz_iana=America/Chicago, tz_name=Central Daylight Time, tz_sfdc=America/Chicago],
            TimezoneResponse:[abbreviation=MDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=100, offset=-6, system_country=USA, system_state=TX, tz_iana=America/Denver, tz_name=Mountain Daylight Time, tz_sfdc=America/Denver])
        */

        tzones = map_tzones.get('200');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=CDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=200, offset=-5, system_country=USA, system_state=TX, tz_iana=America/Chicago, tz_name=Central Daylight Time, tz_sfdc=America/Chicago])
        */

        tzones = map_tzones.get('300');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=MDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=300, offset=-6, system_country=USA, system_state=TX, tz_iana=America/Denver, tz_name=Mountain Daylight Time, tz_sfdc=America/Denver])
        */

        tzones = map_tzones.get('400');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=CET, dst_abbreviation=CEST, dst_offset=2, dst_setting=a013N000002oBMIQA2, dst_tz_name=Central European Summer Time, id=400, offset=1, system_country=GERMANY, system_state=null, tz_iana=Europe/Berlin, tz_name=Central European Time, tz_sfdc=Europe/Berlin])
        */

        tzones = map_tzones.get('500');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=EST, dst_abbreviation=EDT, dst_offset=-4, dst_setting=a013N000002oBORQA2, dst_tz_name=Eastern Daylight Time, id=500, offset=-5, system_country=USA, system_state=null, tz_iana=America/New_York, tz_name=Eastern Standard Time, tz_sfdc=America/New_York])
        */

        tzones = map_tzones.get('600');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=PDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=600, offset=-7, system_country=USA, system_state=CA, tz_iana=America/Los_Angeles, tz_name=Pacific Daylight Time, tz_sfdc=America/Los_Angeles])
        */

    }
} // class LocalTimeAPITest

2. tz.LocalTimeV2.getUTCOffset

Returns the UTC Offset of the specified datetime value in the specified time zone.

Signature

global static Decimal tz.LocalTimeV2.getUTCOffset(Datetime dt, String timeZoneIdString)

Parameters

dt
Type: Datetime

timeZoneIdString
Type: String
The time zone values should use only the values supported by Salesforce.

Return Value

Type: Decimal

Example

// Get the UTC Offset for a specific time zone like Europe/Berlin
Datetime dt = Datetime.newInstance(2022, 11, 7, 14, 0, 0); // Nov 07, 2022
system.debug(tz.LocalTimeV2.getUTCOffset(dt, 'Europe/Berlin')); // returns 1.0 as DST is off

dt = Datetime.newInstance(2023, 4, 5, 14, 0, 0); // April 05, 2023
system.debug(tz.LocalTimeV2.getUTCOffset(dt, 'Europe/Berlin')); // returns 2.0 as DST is on at this time

system.debug(tz.LocalTimeV2.getUTCOffset(dt, null)); // returns the offset based on the time zone of the running user who called the method.