Dates and Times

The Date, Time, Datetime, and Datetimetz types are represented using a XMLGregorianCalendar object within the Script Engine. This provides methods to manipulate the date/time type variables and attributes.

The date/time attributes and fields can be initialized in scripts using methods on the DateTimeUtil factory, as shown below.

DateTimeUtil Factory Methods
Factory Method BOM Type Comment
createDate() Date This type is used to hold a Date, for example, 1st January 2011.
createTime() Time This type is used to hold a time, for example 4:25 P.M.
createDatetime() Datetime This type is used to hold a date and time, with an optional timezone offset.
createDatetimetz() Datetimetz This type is used to hold a date and time, with a mandatory timezone offset.

With no parameters these methods create an object representing the current date or time, or alternatively, they can be given a string or other parameter types to construct the appropriate object with the required value. One thing to be aware of if using String values to create date/time objects is that all the relevant fields need to be specified or an exception will be thrown. Specifically, the seconds need to be specified for all types except the Date type. The following are some examples of date/time types. 

time = DateTimeUtil.createTime("17:30:00");
time = DateTimeUtil.createTime(17,30,0,0);	// equivelant to “17:30:00”
date = DateTimeUtil.createDate("2010-12-25");
date = DateTimeUtil.createDate(2010, 12, 25);	// equivelant to “2010-12-25”
datetime = DateTimeUtil.createDatetime("2010-12-25T15:00:00");
datetime = DateTimeUtil.createDatetime("2010-12-25T15:00:00Z");
datetime = DateTimeUtil.createDatetime("2010-12-25T15:00:00+05:00");
datetimetz = DateTimeUtil.createDatetimetz("2010-12-25T15:00:00Z");
datetimetz = DateTimeUtil.createDatetimetz("2010-12-25T15:00:00+05:00");

When initializing the datetime, the timezone is optional, but when initializing the datetimetz, the timezone is required. The timezone can be designated using one of the following formats:

  • Z for Zulu, or Zero, timezone offset (GMT or UTC time).
  • +HH:MM for timezones that are ahead of UTC time, e.g. Berlin timezone is +01:00.
  • -HH:MM for timezones that are behind UTC time, e.g. USA Pacific Time has a timezone of -08:00.
Note: When working with global data, you should use Datetimetz to represent any timezone-dependent Datetime values entered from a form. This is because global data automatically sets any Datetime/Datetimetz values to UTC, meaning that dates in forms may not be the same ones you originally created (they could be one day different due to timezone differences).

See the reference section for more choices of parameter values, for example, for separated parameters for year, month, and day when create date types.