Time Zone Aware Development

IFS Cloud recognizes the importance of accommodating our expanding global customer base by being time zone aware. It is crucial for customers worldwide to have the ability to access information relevant to their local time. To address this, Framework (FW) support has been implemented, ensuring that timestamp values now carry the correct time zone information. This enhancement streamlines processes for product teams and end-users, contributing to a more seamless experience. This documentation serves as a comprehensive guide for developing time zone-aware business processes, empowering users to navigate and utilize our system more effectively in diverse global contexts.

Read how to Upgrade Data from TimestampUtc to Timestamp.

Enabling Time Zone Awareness

By using the TimestampTZRef property for entities and timestampTZRef property on Projection actions, functions, queries, entities, or virtual entities, time zone awareness can be achieved. When an object is annotated with this property, it means that all its associated timestamp attributes follow the time zone referenced by the timestampTZRef value. The documentation below illustrates the application of the timestampTZRef property in various scenarios, including Projection actions, functions, entities, and virtual entities. If an object is not annotated, the TimestampTZRef/timestampTZRef property is considered null, indicating that the object is not time zone aware. In such cases, the time zone aware behavior will not be applied.

Values Allowed

Server

specifies that all timestamps should be associated with the server’s time zone.

From a technical perspective, mainly, there are two things that the server framework is responsible for, in order to make API requests Time Zone aware

1. Converting Incoming values into the server time zone before binding the values to the database statements. Mainly there are two types of values that are available,
2. Values passed in the Request Body
3. Values passed as URL parameters
4. Appending the time zone offset to all values which are retrieved from the database

Time Zone Aware Entities

To make an entity time zone aware, a new codegen property called TimestampTZRef has been introduced. This allows for the specification of the time zone in which timestamps associated with specific entities should be saved on the server.

Example

entityname Voucher;
component  ACCRUL;

basedOn  Voucher;
codegenproperties {
    TimestampTZRef "server";
}

In this example, the TimestampTZRef annotation explicitly instructs that the timestamp attributes associated with the entity voucher should be stored in the server's timezone. Setting the value of TimestampTZRef to "server" signifies that timestamps related to a particular entity should be stored in the server's timezone.

Time Zone Aware Projection Entities

The behavior described in the base entity can be overridden in projections using the timestampTZRef property. Even if the base entity is not explicitly annotated as time zone aware, this property allows for the overriding of time zone behavior in projections.

Example

@Override
entity Voucher {
   timestamptzref = "server";
}

As seen in the above example, by setting the timestampTZRef property when overriding the entity in the projection, specific entities can have their timestamp time zone behavior adjusted as needed. This provides flexibility in tailoring time zone considerations without the need for direct entity annotations. In this specific example, it means that all the timestamp attribues will be converted to the server’s time zone before being saved in the database.

Time Zone Aware Actions and Functions

The Known Server Time Zone feature extends its capabilities to include operations, allowing projection actions and functions to be time zone aware. This enhancement enables the specification of time zones for parameters and return types within these operations.

Parameters

Primitive Parameters

If an operation is annotated with the timestampTZRef property, all of its primitive timestamp parameters will be converted to the referenced time zone specified in the timestampTZRef property's value before being passed on to the PL/SQL function or action. Note that this annotation is only applied to the top level primitive attributes and not the complex attributes which may hold timestamps.

function GetPrimitiveList List<Timestamp> {
   timestamptzref = "server";
   parameter Param Timestamp;
}

In the above example, the value passed for Param will undergo conversion to the server's time zone before being bound to the function as a parameter.

Complex parameters

The behavior of complex paramters don't depend on the operation's annotation. It depends on the structure itself. Read more here

Return Types

Primitive Timestamp Return Types

When an operation is annotated with the timestampTZRef property and returns either a primitive timestamp value or a list of primitive timestamp values, all these values will be converted to Coordinated Universal Time (UTC), assuming that the original values were in the time zone referenced in the timestampTZRef property's value.

Complex Return Types

The behavior of complex return types don't depend on the operation's annotation. It depends on the structure itself. Read more here

function GetPrimitiveList List<Timestamp> {
   timestamptzref = "server";
   parameter Param Timestamp;
}

In the above example, all values within the returned list will undergo conversion to UTC, assuming they were initially in the server's time zone.

Structure parameters/return types

In order to support the known time zone functionality for timestamps defined in structures, a specific annotation approach is required. Simply annotating the operation where the timestamp is used is not sufficient. The structure itself needs to be annotated.

1. Structure Annotation

If a structure is annotated with the timestampTZRef property, the following behavior is applied:

• Parameter Conversion:
• All primitive timestamp attributes within the structure will be converted to the referenced time zone specified in the timestampTZRef property's value
• This conversion occurs before passing the values to the PL/SQL function or action.

• If a structure contains a structure type attribute, it too has to be annotated.

• Return Type Conversion:

• For return types containing timestamp attributes, the values will be converted to Coordinated Universal Time (UTC).
• This assumes that the original values were in the time zone referenced in the timestampTZRef property's value.

2. Structures associated with Operations

If an operation includes structure parameters or has a structure return type with timestamp attributes, it must be annotated. Similarly, if a structure is annotated, and it contains timestamp attributes in its parameters or return type, it cannot be left unannotated.