Intro

Starting from version 1.114, the SAPUI5 applications in SAP Fiori launchpad (FLP) support time zone configuration from the FLP. The configured time zone affects all applications and therefore using a time zone that is different from the user’s browser time zone can break these applications. The same is valid when using a variant that is saved in a different time zone.

In this article I give recommendations and best practices for application developers who are using smart controls with time zone that differs from user’s browser time zone. To provide a comprehensive understanding, I will also inform you about the recent changes in smart controls, and what is the rationale behind these changes. Additionally, in this article I also list the configurations that do not support the time zone setting.

Action Items and Key Takeaways

If there’s one crucial point to take away from this article, it is as follows:

Action for Application Developers: It is essential to review and modify your application code if you intend to utilize a configured time zone that differs from user’s browser time zone. This article describes what needs to be changed for smart controls. For more general information, a good starting point is the Dates, Times, Timestamps, and Time Zones article.

Action for End Users: If you plan to use a configured time zone that is different from the time zone in which your variants were saved, take the time to review these variants, and ensure that they are saved in the new time zone. If necessary, contact a person who is authorized to adjust these variants for you. 

Key terminology with examples – date, time, and timestamps 

Let’s begin with a brief introduction to some key terminology taken from our Dates, Times, Timestamps, and Time Zones Demo Kit article. Understanding these terms will provide a solid foundation for the rest of this blog post:

When talking about dates, times, or timestamps, we will use the following definitions:

A date represents a specific day within a year independent of any time zone. For example, New Year’s Eve 2022 is on 2022/12/31, regardless of the time zone in which the user is in. The time zone is irrelevant for dates.

A time is a representation of a specific hour/minute/second within a day that is independent of any time zone. For example, if all shops of a brand open at 9:00 AM, they will open at 9:00 AM in whichever time zone the shop is in. The time zone is irrelevant for times.

A timestamp represents a point in time that can be displayed or edited in specific time zones. For example, if a meeting starts at a specific date and a specific time in a specific time zone, its timestamp may be displayed as 27.11.2022, 14:00:00 Honolulu or as 28.11.2022, 11:00:00 Australia/Canberra, depending on the user’s time zone.

Here are some examples of these terms based on XML metadata:

A date: An example of a date is an Edm.DateTime field with the sap:display-format=”Date” annotation. This represents a specific date without including the time component. It is commonly used to display or manipulate dates without considering the time of day.

A time: An example of a time is an Edm.Time field. This represents a specific time of day, including the hours, minutes, and seconds. It is used to indicate a particular point in time without considering the date component. 

A timestamp: An example of a timestamp is an Edm.DateTimeOffset field. This represents a precise point in time, including both the date and the time, along with the time zone offset information. The timestamp is typically kept in UTC format. It captures the exact moment when an event occurred, considering both the date and time components. 

To provide clear and consistent examples, let’s assume that you are running the application in Berlin (GMT+1) and using the following sample data: 

• For a date field: 1st of February 2023
  This example represents a date field, and we will refer to it as default date for our illustrations. 
• For a time field: 13:30 PM
  This example represents a time field and signifies the default time. 
• For a timestamp field: 1st of February 13:30 UTC
  This example represents a timestamp field, specifically capturing the date and time in UTC format. We will use this timestamp as a reference point for our discussions. 

By using consistent sample data, we can effectively demonstrate the behavior and implications of time-zone adjustments in relation to different field types within the smart controls.  

Now, with a solid understanding of the key terminology, let us delve deeper into three of the most used smart controls: SmartFilterBar, SmartTable, and SmartChart. 

SmartFilterBar

Note: Changing the user’s time zone in FLP affects only date and time fields. Timestamps are not affected since they are saved in the VariantManagement in a suitable format.

Note: As described in the Demo Kit documentation (Dates, Times, Timestamps, and Time Zones section), аlways use UI5Date.getInstance to create new date instances.

The SmartFilterBar offers two primary entry points that app developers can utilize to set default data. These entry points are:

• setUiState: When using the setUiState method, the default date remains unchanged regardless of any modifications made to the time zone settings. This means that the values set using setUiState will remain consistent and independent of any time zone adjustments – no changes are needed
• setFilterData: This method expects changes based on the time zone configuration. If the time zone is altered, the data set using this method may require adjustment to align with the new time zone. In the following paragraphs, we will further elaborate on the implications and considerations related to using the setFilterData method.

Let us explore the impact of time zone changes on the setFilterData method in more details.

setFilterData with a Date object

Previously, application developers had the option to set default data for date fields by calling the setFilterData method with a JavaScript Date object. An example of this usage is as follows:

oSmartFilterBar.setFilterData({ 
     fieldName: new Date(2023, 1, 1) // 1st of February 2023 
}) 

Recommendation:
This approach will continue to function as expected if the Fiori Launchpad (FLP) configured time zone matches the browser time zone. However, if you intend to support different FLP configured time zones, the code snippet should be modified as follows:

oSmartFilterBar.setFilterData({ 
     fieldName: UI5Date.getInstance(2023, 1, 1) // 1st of February 2023 
}) 

By using the `UI5Date.getInstance` method instead of the JavaScript Date object, you ensure that the default date is correctly adjusted, based on the configured time zone in the FLP. This modification ensures consistent behavior and accurate default date presentation across different time zone settings.

It is highly recommended to use the UI5Date.getInstance for setting default data, regardless of the FLP configured time zone. This approach ensures more robust and reliable code, offering better consistency and compatibility across various scenarios.

setFilterData with a String

Note: Setting data to date/time fields with ISO string is also valid for applyVariant method because it calls setFilterData with a string.

Previously, application developers had the option to set default data for date fields by calling the setFilterData method with an ISO string. An example of this usage is as follows:

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-01-31T23:00:00.000Z' // 1st of February 2023 if string is generated in GMT+1 
});

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-02-01T10:00:00.000Z' // 1st of February 2023 if string is generated in GMT-10 
}) 

Based on the above samples you may have identified a crucial issue with UTC ISO strings that we have used up until now. The problem arises from the fact that these strings do not include the specific time zone information in which they were saved. As a result, when attempting to restore a variant that was saved in one time zone to a different time zone, the lack of essential information about the original time zone can lead to unreliable restoration.

Considering the challenges associated with storing and restoring variants in different time zones, it was necessary to adjust the expected format for date and time fields (excluding timestamps). The new format could be easily restored in different time zones and is used by setFilterData method as well.

Recommendation:
Based on the above examples, the new code should look like this:

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-02-01T00:00:00.000' // 1st of February 2023 if string is generated in GMT+1 
});

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-02-01T00:00:00.000' // 1st of February 2023 if string is generated in GMT-10
}) 

In that way we guarantee that in whatever time zone this string is used we will always restore 1st of February.

Note: For timestamp fields, the approach for setting them remains unchanged. Referring to our example- 1st of February 13:30 UTC, you would still set the field in the same manner as before. The call would be:

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-02-01T13:30:00.000Z' // 1st of February 2023 13:30 UTC if string is generated in GMT+1 
});

oSmartFilterBar.setFilterData({ 
     fieldName: '2023-02-01T13:30:00.000Z' // 1st of February 2023 13:30 UTC if string is generated in GMT-10
}) 

SmartTable/SmartChart

For SmartTable and SmartChart we have again two main points to set Personalization filters – setUiState and applyVariant. In contrast to SmartFilterBar, both methods need adaptation.

Usage of setUiState

To address the limitations and inconsistencies associated with the previous format used in the setUiState for storing dates and timestamps, a change has been made to adopt a standardized format that ensures accurate restoration across different time zones.

Previously, dates in the UiState were stored in a format like:
‘Wed Feb 01 2023 00:00:00 GMT+0100 (Central European Standard Time)‘ for Berlin
‘Wed Feb 01 2023 00:00:00 GMT-1000 (Hawaii-Aleutian Standard Time)‘ for Honolulu.

However, this format poses challenges when restoring the date in a different time zone, potentially leading to incorrect results.

Recommendation:
To overcome this issue, the format has been modified to align with the setFilterData format used in the SmartFilterBar:

For date fields:
The new format for dates in the uiState is:
‘2023-02-01T00:00:00.000‘, representing the 1st of February 2023.

This format is time zone-agnostic, ensuring consistent behavior regardless of the time zone in which it is restored.

For timestamp fields:
The format for timestamps in the uiState has been changed from
‘Wed Feb 01 2023 14:30:00 GMT+0100 (Central European Standard Time)‘
‘Wed Feb 01 2023 03:30:00 GMT-1000 (Hawaii-Aleutian Standard Time)‘

to

‘2023-02-01T13:30:00.000Z‘

This format follows the ISO 8601 standard and includes the ‘Z’ suffix to indicate that the timestamp is in UTC format.

By adopting these standardized formats, you can ensure accurate restoration and consistent behavior of dates and timestamps across different time zones, eliminating the ambiguity and issues associated with the previous format.

Usage of applyVariant

For applyVariant the same things apply as to the setFilterData method of the SmartFilterBar:

• If a JavaScript Date object is passed, it should be changed to UI5Date.getInstance
• If a String is passed, it should be changed to:
  – for dates: ‘2023-02–01T00:00:00.000′ 
  –  for timestamps ‘2023-02–01T13:13:30.000Z’

Configurations that do not support the time zone setting 

For some configurations time zone setting will not be supported. We encourage you to check your application and if these configurations are in use to consider removing/changing them, because they are error-prone:

1. Edm.DateTime fields without sap:display-format=”Date”. Here we recommend using Edm.DateTimeOffset fields instead.
2. Edm.DateTimeOffset field with sap:display-format=”Date”. Here we recommend using Edm.DateTime with sap:display-format=”Date” instead. 
3. To the SmartFilterBar, SmartChart and SmartTable can provide a configuration option to switch mode to UTC: false. This mode will not support time zones. 

Conclusion

• If а JavaScript Date object is used for setting default date in SmartFilterBar It is highly recommended to replace it with UI5Date.getInstance. This approach ensures more robust and reliable code, offering better consistency and compatibility across various scenarios.
• If a String is used for setting default date in SmartFilterBar:
  – For timestamp fields – nothing changes
  – For date fields – the date should be passed in the following format: ‘2023-02-01T00:00:00.000’