Time Zone Datatype Behavior

Because enterprise resources are frequently located in different time zones, you need to understand the restrictions of using time-related datatypes when developing mobile business objects (MBOs).

Zone-offset independent field based time

Unwired Platform date, time, and dateTime datatypes hold time zone independent field-based time, as defined in Incremental versus Field-Based Time, making zone offsets invalid. For example, if you specify a default value for a synchronization parameter, it is not valid to include the zone offset:

2009-08-28T00:00:01+08:00

If a device application needs an attribute to store zone offset or zone name data, then define another MBO attribute to contain it. When previewing or testing date, time, and dateTime datatypes, values related to zone-dependent fields in Web services undergo the conversions described in this document. You need to account for any adjustments in the expected results, and may need to adjust any MBO default values you set.

Receiving values from Web services

Zone-offset behavior of date, time, and datetime datatypes:

xsd:date – if Unwired Server receives a date value from a Web service that includes a zone offset (ending with "Z", "+XX:XX", or "-XX:XX"), Unwired Server ignores and drops the zone offset suffix. DATE values stored in the Unwired Server cache database (CDB), and sent to the client, do not include any zone offset. For example, if Unwired Server receives an xsd:date value:
```
2000-01-01+12:00
```
it converts that value to a DATE:
```
2000-01-01
```
xsd:time – if Unwired Server receives a time value from a Web service that includes a zone offset (ending with "Z", "+XX:XX", or "-XX:XX"), Unwired Server ignores and drops the zone offset suffix. TIME values stored in the CDB, and sent to the client, do not include any zone offset. For example, if Unwired Server receives an xsd:time value:
```
14:00:00+12:00
```
it converts that value to a TIME:
```
14:00:00
```
xsd:dateTime – if Unwired Server receives a dateTime value from a Web service that includes a zone offset (ending with "Z", "+XX:XX", or "-XX:XX"), Unwired Server adjusts the fields to convert the value to UTC (+00:00) and then drops the zone offset suffix. DATETIME values stored in the CDB, and sent to the client, do not include any zone offset. For example, if Unwired Server receives an xsd:dateTime:
```
2000-01-01T14:00:00+12:00
```
it converts that value to a DATETIME:
```
2000-01-01 02:00:00
```

If Unwired Server receives a value from a Web service that does not include a zone offset, then Unwired Server uses the unchanged value.

Sending values to Web services

By default, Unwired Server appends a "Z" to any date/time value that it sends to a Web service. If a Web service expects to receive zone-independent field based time, then use a derived simpleType with a pattern restriction in the XML schema description to indicate to the XML parser that only zoneless representation is accepted by the Web service. For example, you could define these simpleTypes:

<s:simpleType name="ZonelessDate"> 
        <s:restriction base="s:date"> 
                <s:pattern value="[0-9]{4}-[0-9]{2}-[0-9]{2}"/> 
        </s:restriction> 
</s:simpleType>

<s:simpleType name="ZonelessTime"> 
        <s:restriction base="s:time"> 
                <s:pattern value="^[0-2][0-9]:[0-5][0-9]:[0-5][0-9]
                (.([0-9]{3}))?$"/> 
        </s:restriction> 
</s:simpleType> 

<s:simpleType name="ZonelessDateTime"> 
        <s:restriction base="s:dateTime"> 
                <s:pattern value="^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-2]
                [0-9]):[0-5][0-9]:[0-5][0-9](.([0-9]{3}))?$"/> 
        </s:restriction> 
</s:simpleType>

Then use the corresponding derived simpleType instead of using "xsd:date", "xsd:time", or "xsd:dateTime" as an element's type. These patterns are only examples and not "prescriptive."

Special consideration for client applications

As an example, you are writing a device application, and know that the enterprise information system (EIS) Web service always expects to receive values with zone offset. You also know (from above) that Unwired Server always sends a value with a "Z" suffix to the Web service. How do you then pass the appropriate values (for MBO attributes and/or operation parameters) from the device application?

In this example, the client device is located in New Zealand (12 hours ahead of UTC), and an event occurs at device-local date/time "2010-05-12T11:24:00+12:00". Since the client using the Object API can only pass zoneless values to MBO attributes or operation parameters, the client application must convert the fields to UTC, for example, "2010-05-11T23:24:00+00:00", and drop the zone offset to pass "2010-05-11T23:24:00" into an MBO attribute or operation parameter. When the client uploads this value to Unwired Server, it appends "Z" which results in "2010-05-11T23:24:00Z", which is then sent to the EIS Web service. Since "2010-05-11T23:24:00Z" is an equivalent point in time to "2010-05-12T11:24:00+12:00", no information is lost.

In other words, if the EIS expects to receive values with zone offsets, the client application might need to do zone offset conversions to UTC. Conversely, if the EIS expects to receive zoneless values, then the client application does not need to perform any conversions from device-local time, other than dropping the zone offset.

Load parameters and timezone support for Web service MBOs

Avoid using date/datetime datatypes as load parameters, since you could get unexpected results. If want to use Web service MBO operations that have time zone offsets, convert the date/datetime value to UTC, before sending it to Unwired Server. When the date/datetime value is returned from Unwired Server, change it back. Other considerations to be aware of:

Date/Datetime datatype personalization keys for Web services should be avoided – if the client is in a different time zone, the same time change to UTC may be different, requiring a conversion to the personalization key when ever entering a different time zone.
Default values for Date/Datetime datatypes in Web service operations with time zone offset should be avoided – the default values are set in the MBO at design time, the developer cannot determine which time zone the client uses, so the UTC conversion is impossible.