Skip to content

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.

Server 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

  • Converting Incoming values based on the annotated time zone variant before binding the values to the database statements. Mainly there are two types of values that are available
  • Values passed in the Request Body
  • Values passed as URL parameters
  • 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.

Values Allowed

server

Specifies that all timestamps that belong to the entity should be associated with the server’s time zone.

entityname Voucher;
component  ACCRUL;

basedOn  Voucher;
codegenproperties {
    TimestampTZRef "server";
}

site(SiteReference)

Specifies that all timestamps should be associated with the time zone of the site that's associated to the entity instance.

When annotating an entity with a Timestamp Key, ensure that the attribute containing the site ID is always included as part of the key.

SiteReference

'SiteReference' should either be an attribute of the entity or it could be a function call, Entity_API.Get_Contract(entity_attribute). Note that you should pass the DB Column name as the parameter to the function call.

entityname Voucher;
component  ACCRUL;

basedOn  Voucher;
codegenproperties {
    TimestampTZRef "site(Contract)";
}

attributes {
   key          KeyAttr          NUMBER               KMI-L;
   public       Contract         TEXT(5)/UPPERCASE    A-I-L;
}

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.

@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.

Values Allowed

The same values allowed for entities are allowed here.

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.

Values Allowed

server

Specifies that all the primitive timestamp parameters and return types of the function/action should be associated with the server’s time zone.

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.

site(SiteReference)

Specifies that all the primitive timestamp parameters and return types of the function/action should be associated with the site's time zone that's passed in as a parameter.

SiteReference

'SiteReference' should be a parameter of the action/function. Function calls aren't allowed here.

function GetPrimitiveList List<Timestamp> {
   timestamptzref = "site(Contract)";
   parameter Param Timestamp;
   parameter Contract Text;
}

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

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 parameters and not the complex parameters which may hold timestamps.

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.

Values Allowed

server

Specifies that all timestamps that belong to the entity should be associated with the server’s time zone.

structure CStructure {
   timestamptzref = "server";
   attribute ToContract Text;
   attribute Prop1 Timestamp;
   attribute Prop2 Timestamp;
}

site(SiteReference)

Specifies that all timestamps should be associated with the time zone that's specific to the object in concern.

SiteReference

'SiteReference' should be an attribute of the structure. Function calls aren't allowed here.

structure CStructure {
   timestamptzref = "site(ToContract)";
   attribute ToContract Text;
   attribute Prop1 Timestamp;
   attribute Prop2 Timestamp;
}

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.

Legacy Data Support

When performing data upgrades on a table by converting a column's data to another time zone in order to get time zone support using the timestampTZRef property, the entity should be annotated with the TimestampTZLegacyDataSupport property set to false. Since all entities support legacy data by default, this annotation is only required when the data has been upgraded.

entityname CustomerOrder;
component  CUST;

codegenproperties {
   TimestampTZLegacyDataSupport "false";
}

Any actions or functions that read from or write to this table should also be annotated to ensure they properly handle the upgraded data.

action ActionNoLegacy Timestamp {
   initialcheck none;
   timestamptzref = "site(Contract)";
   timestamptzlegacydatasupport = [false];
   parameter Contract Text;
   parameter Param Timestamp;
}

If structures are used to read from or write to these tables, they must also be properly annotated using the timestamptzlegacydatasupport property.

``` structure CStructureNoLegacy { timestamptzref = "site(ToContract)"; timestamptzlegacydatasupport = [false];

attribute ToContract Text; attribute Prop1 Timestamp; attribute Prop2 Timestamp; }