Date and time format in the Commerce Engine and Business Tools

Abstract

Understand how the Commerce Engine handles the date and time to be consumed by the Business Tools.

It is important to understand how the Commerce Engine handles date and time, particularly when it comes to time sensitive business operations like promotions, for example.

The Commerce Engine always uses the UTC time standard both in processes, and when storing date and time in the database. This is not configurable.

When the XC Business Tools application renders date and time information via Angular, it uses the raw value, and converts it to the business user's time zone, as communicated through the browser and the OS.

<! -- Schema: {{ value_expression | date [ : format [ : timezone [ : locale ] ] ] }}-->

Business Tools code sample (in HTML)

<div *ngIf="property.UiType !== 'FullDateTime'">
        {{property.Value | date:'shortDate':'':bizFxContext.language}}

    </div>
  </div>

Response from the Commerce Engine (JSON)

Name":"ValidFrom","Policies":[
      ],"DisplayName":"Valid From","Value":"2020-11-05T08:32:27.8320000+00:00","IsHidden":false,"OriginalType":"System.DateTimeOffset","IsReadOnly":true,"UiType":"","IsRequired":true
    },
]

The following scenarios show you two examples of how date and time information is handled in the Business Tools and the Commerce Engine, where business users in located in different time zones interact with the same promotion in the business tools.

Scenario 1: business user 1 in UTC-05:00 time zone sets a promotion's validity dates

Business user 1 creates a 24-hour promotion with validity dates (MM/DD/YY) based on their time zone.

Dates entered in the Business Tools (UTC-05:00)

Dates converted and stored in Commerce Engine (UTC+00:00)

  • Valid from: 12/26/22 00:01

  • Valid to: 12/26/22 23:59

  • Valid from: 12/26/22 05:01

  • Valid to: 12/26/22 04:59

Scenario 2: business user 2 in UTC-08:00 time zone views the promotion's validity dates

Business user 2 views the validity dates of the promotion that Business User 1 created.

The Business Tools application converts the raw values of validity dates stored in the Commerce Engine (UTC+00:00) and displays them in the time zone of business user 2 (UTC-08:00), based on the user's information (browser and OS).

Dates displayed in the Business Tools (UTC-08:00)

Dates stored in Commerce Engine (UTC+00:00)

  • Valid from: 12/25/22 21:01

  • Valid to: 12/26/22 20:59

  • Valid from: 12/25/22 05:01

  • Valid to: 12/26/22 04:59

Promotion evaluation and promotion validity dates

During the promotion evaluation process, the Commerce Engine uses the promotion validity dates stored in the Commerce Engine in UTC format to determine whether or not the promotion applies.

On a storefront, the promotion might apply at different times based on the shopper's time zone, but these different representations of date and time are interpretations of the same moment that is stored in Commerce Engine in UTC.