Time plays a crucial role in systems that handle critical operations, particularly when dealing with timezone-dependent processes. This becomes especially important when synchronizing data with third-party systems such as Customer Relationship Management (CRM) and Order Management Systems (OMS), or when processing orders through various stages.

A common challenge developers face is handling timezone configurations when the instance timezone differs from individual site timezones. This can lead to unintended delays or incorrect scheduling of tasks.

Understanding how your servers and sites are configured in the Salesforce Commerce Cloud Business Manager is essential for smooth operations.

In this article, we’ll explore a scenario where an instance is located in India and hosts multiple sites across different regions including India, UAE, and Singapore. We’ll examine how to properly manage timezone configurations to ensure accurate data processing and job scheduling.

My preferred approach is to use UTC as the server time while adjusting the frontend time based on the user’s or site’s timezone. Storing all dates in UTC makes it easier to calculate and display the correct time for the end user according to their respective timezone settings.

Table of Contents

• Understanding Timezones in SFCC
  • Site Timezone
  • Instance Timezone
• Configuration in Business Manager
  • Configuring the Site Timezone
  • Configuring the Instance Timezone
• Coding with Timezones
  • Retrieving Timezone Information
  • Handling Dates in Orders
• Managing Timezones in Jobs
  • The Challenge with Scheduled Jobs
  • Critical Points for Job Scheduling
  • Key Takeaways for Job Timezones
• Conclusion
• Related Links

Understanding Timezones in SFCC

In a Salesforce Commerce Cloud (SFCC) instance, two types of time zones are configured:

1. Site Timezone
2. Instance Timezone

To find the configured time zones for your instance, log in to Business Manager on any accessible instance. On the Welcome page, or any other page, examine the footer. It displays the time zone information for both the instance and the currently selected site.

Timezone in Business Manager footer (Image by Author)

Site Timezone

A Salesforce Commerce Cloud instance can host multiple sites. For this example, we have three sites representing India, UAE, and Singapore. When a team is working on a specific country site, aligning the site’s time zone with the country’s local time zone simplifies the interpretation of time-sensitive data, such as order timestamps. This alignment is particularly beneficial for customer service teams, enabling them to more easily communicate with customers and troubleshoot queries when site data reflects the relevant local time.

Orders Listing in Business Manager (Image by Author)

Instance Timezone

Given that an instance hosts multiple sites from different countries with varying time zones, the question arises: why is an instance time zone necessary? The instance time zone is crucial for managing scheduled jobs that send and synchronize data between the SFCC server and external systems. Additionally, instance logs, essential for troubleshooting, are managed and executed based on the instance’s time zone. Therefore, the instance time zone governs the execution of server-level processes and log management.

Configuration in Business Manager

Configuring the Site Timezone

Let us proceed with configuring the time zone within Business Manager for each site.

1. Log in to Business Manager.
2. Go to Administration > Sites > Manage Sites.
3. Choose the site you want to configure.
4. Click on the General tab.
5. Find the Time Zone field.
6. Change the value to the desired time zone.

Site Timezone setting in Business Manager (Image by Author)

Configuring the Instance Timezone

Let us proceed with configuring the time zone within Business Manager for the instance.

1. Log in to Business Manager.
2. Go to Administration > Global Preferences > Instance Time Zone.
3. Select the desired Geographical Area.
4. Choose the appropriate Instance Time Zone.

Instance Time Zone settings in Business Manager (Image by Author)

To confirm the successful implementation of the new time zone settings, save your changes and then log out and back into Business Manager. Review the footer to verify the updated time zones.

For production instances, time zone configurations are editable exclusively during the initial 60 days post-go-live. Beyond this timeframe, the ability to alter these settings is restricted.

Coding with Timezones

To illustrate the impact of time zone settings, let’s examine code examples that demonstrate key results, specifically for a site configured with the Asia/Kolkata time zone (India).

Retrieving Timezone Information

Retrieve the site’s time zone

var Site = require('dw/system/Site');
Site.getCurrent().getCalendar().getTimeZone();

// Output: Asia/Kolkata

Retrieve the current time for the site

var Site = require('dw/system/Site');
Site.getCurrent().getCalendar().getTime();

// Output: 2024-02-22T11:48:13.924Z

The result, displayed in UTC, not IST, reveals that dates are inherently treated as UTC at the system’s base level.

Time Zone Offset

var Site = require('dw/system/Site');

Site.getCurrent().getTimezoneOffset();
// Output: 19800000 milliseconds -> 5.5 hours
// This represents the offset for the Asia/Kolkata time zone (IST).
// Calculation: 19800000 milliseconds / (60 * 60 * 1000) = 5.5 hours

Converting UTC Time to IST Time

var Site = require('dw/system/Site');
var Calendar = require('dw/util/Calendar');

function getLocalizedTime(utcDate) {
  // Retrieve the site's time zone offset in milliseconds.
  let timezoneOffset = Site.getCurrent().getTimezoneOffset();

  // Calculate the offset in hours and minutes.
  let offsetHours = Math.floor(timezoneOffset / (1000 * 60 * 60));
  let offsetMinutes = (timezoneOffset % (1000 * 60 * 60)) / (1000 * 60);

  // Create a Calendar object based on the UTC date.
  let calendar = new Calendar(utcDate);
  
  // Apply the time zone offset by adding hours and minutes.
  calendar.add(Calendar.HOUR, offsetHours);
  calendar.add(Calendar.MINUTE, offsetMinutes);

  // Return the localized time.
  return calendar.getTime();
}

// Get the current time in UTC for the site.
let currentSiteTime = Site.getCurrent().getCalendar().getTime(); 
// Example UTC Output: 2024-02-22T11:48:13.924Z

// Convert the UTC time to the site's local time (IST).
let localizedTime = getLocalizedTime(currentSiteTime);
// Example IST Output: 2024-02-22T17:18:13.924Z

The function utilizes the site’s time zone offset to adjust a given UTC time. By adding the calculated hours and minutes to the UTC time, the function effectively converts it to the local time of the site.

Handling Dates in Orders

We shall now analyze the date handling mechanisms within the order system objects. As previously observed, order dates displayed in Business Manager are presented in IST (India Standard Time) format.

Extracting the order’s creation date and time

var order = require('dw/order/OrderMgr').getOrder('00001');
var creationDate = order.getCreationDate();
// Output: 2024-11-19T04:42:15Z

Orders Listing in Business Manager (Image by Author)

As you may observe, the order date displayed in Business Manager is 11/19/2024 10:12:15 AM Asia/Kolkata. However, the order creation date returned programmatically is in UTC.

Exporting the order using BM’s import/export

<orders xmlns="http://www.demandware.com/xml/impex/order/2006-10-31">
   <order order-no="000001">
       <order-date>2024-11-19T04:42:15.000Z</order-date>
   </order>
</orders>

When you export the order through Business Manager’s import/export, the downloaded file will display the order’s creation date within the ‘order-date’ column. As expected, the exported date is consistently in UTC format.

Use code to update the order

var order = require('dw/order/OrderMgr').getOrder('0000001');
var Transaction = require('dw/system/Transaction');
var Site = require('dw/system/Site');

Transaction.wrap(function () {
   order.custom.cAttribute = Site.getCalendar().getTime();
});

order.custom.cAttribute // Output: 2025-02-22T17:48:13.924Z

I am utilizing a custom attribute (‘cAttribute’) to save a date through code. Notably, the date is stored in UTC, which is the expected behavior of Site.getCalendar().getTime().

The key takeaway is that SFCC consistently saves date attributes in UTC. As a best practice, ensure that you always save date attributes using UTC time within the system.

Managing Timezones in Jobs

When dealing with eCommerce, an important aspect is providing users with a fully integrated system view that ensures seamless service and high satisfaction. This extends beyond your site’s storefront to include background jobs that play a crucial role. These jobs range from fetching inventory to sending reports at specific times on a regular basis. Understanding timezone configuration becomes particularly important when you need to execute operations at certain specific times.

Consider these scenarios:

• An inventory import scheduled for 6:00 AM local time, allowing sufficient time for upstream systems, such as the Order Management System (OMS), to complete nightly data processing.
• A daily report detailing customer registrations, set to be generated and emailed at 12:00 AM, providing a summary of the day’s activity.

However, some jobs, such as synchronizing order status from a payment gateway, require more frequent execution, for example, every 15 minutes. For these types of jobs, the instance or site time zone is irrelevant, as they are designed to run continuously at fixed intervals.

The Challenge with Scheduled Jobs

Although it may appear simple, developers commonly make mistakes with time settings in jobs.

Job Schedule in Business Manager (Image by Author)

Consider the scenario of scheduling a daily report to be sent at 12:00 AM UAE time. Because jobs execute based on the instance time zone, directly setting 12:00 AM in the job’s ‘From’ field would result in the job running at 12:00 AM IST (as IST is the instance time zone).

To achieve the desired UAE time execution, you must first convert 12:00 AM UAE time to its equivalent IST time.

Time conversion example (Image by Author)

Therefore, you need to configure the job to run at 1:30 AM IST. This ensures that when it is 12:00 AM in the UAE, it will be 1:30 AM in India, and the production instance will execute the job accordingly.

Critical Points for Job Scheduling

In this scenario, three distinct time zones are relevant:

1. Instance Time Zone (IST): This handles the job’s execution time.
2. Site Time Zone (Asia/Dubai, UAE): This defines the data export window, from February 22nd, 00:00:00 AM to February 22nd, 23:59:59.
3. UTC Time: This is the internal storage format for all date attributes within the site.

You must wait until February 22nd 23:59:59 Asia/Dubai time passes for data export. This means the job should run at or after 12 AM UAE time on the next day.

Here’s the important detail: the date saved in the site system object is in UTC time. Therefore, you need to convert the UAE dates to UTC time:

• Start time: Feb 22nd 00:00:00 UAE = Feb 21st 20:00:00 UTC
• End time: Feb 22nd 23:59:59 UAE = Feb 22nd 19:59:59 UTC

In practical terms, this requires the job to execute a query that uses the converted UTC time frame to select the appropriate data for export.

Key Takeaways for Job Timezones

• For configuring recurring job schedules, it is essential to translate the desired local site time into the instance time zone.
• To ensure accurate data retrieval within jobs, convert the local site time to UTC before executing any time-based queries.

Conclusion

Mastering timezone management in Salesforce Commerce Cloud is essential for any developer or administrator aiming for robust and reliable e-commerce operations. By understanding the distinction between instance and site timezones, and by adhering to the best practice of storing all date-time values in UTC, you can avoid common pitfalls related to job scheduling and data synchronization. Proper configuration ensures that your system behaves predictably across different regions, providing a seamless experience for both your internal teams and your customers.

Related Links

• Supported Time Zones
• Calendar Class
• Date Class
• B2C Commerce Currency and Timezone Settings
• Site Time Zone for B2C Commerce