Datetime Fields
You can work with datetime fields using the dateTime type in NetSuite. See the following sections for information about working with the dateTime type.
Using the dateTime Type in NetSuite
When setting a date field using SOAP web services, you must enter a datetime value. The time and the time zone following the date are used to determine the resulting date. When getting the date field through SOAP web services, your preferred time zone influences the resulting datetime. Midnight in the user's time zone of the stored date (which is also displayed in the UI) is converted to Pacific Standard Time (PST) or Pacific Daylight Time (PDT), and sent to the SOAP web services user.
During winter months, the Pacific Time Zone is eight hours behind Coordinated Universal Time (UTC-8) and is referred to as Pacific Standard Time (PST). In summer months, the Pacific Time Zone is seven hours behind Coordinated Universal Time (UTC-7) and is referred to as Pacific Daylight Time (PDT).
The following table gives several examples.
|
Datetime set in the date field |
Time zone of the user |
Date shown in the UI |
Datetime when getting the record2 |
|---|---|---|---|
|
2017-02-21T00:00:00.000-06:00 |
GMT-06:00 |
2/21/2017 |
2017-02-20T22:00:00.000-08:00 |
|
2017-08-21T00:00:00.000-05:00 |
GMT-05:001 |
8/21/2017 |
2017-08-20T22:00:00.000-07:00 |
|
2017-02-21T00:00:00.000-05:00 |
GMT-08:00 |
2/20/20173 |
2017-02-20T00:00:00.000-08:00 |
|
2017-08-21T00:00:00.000-07:00 |
GMT-05:001 |
8/21/2017 |
2017-08-20T22:00:00.000-07:00 |
Notes for the example table:
-
The user has set their time zone to GMT-6, but daylight saving time (DST) affects the result.
-
This is midnight of the date from the UI that is converted to PST or PDT. Note the time difference, which equals the difference between the user's preferred time zone and PST or PDT.
-
The datetime which is to be saved is not greater than midnight in the user's preferred time zone.
Guidelines for the dateTime Type
Consider the following guidelines when using the dateTime type:
-
To avoid problems with conversions, set the time zone of the SOAP web services employee to "(GMT-08:00) Pacific Time (US & Canada)" in Home > Set Preferences (Administrator). Also, submit the datetimes for date fields as midnight and in PST or PDT. For more information, see Setting Date and Time Format for SOAP Web Services. This way you can avoid conversions or truncations, and what is submitted will be identical to what is retrieved through SOAP web services.
-
When changing time zone preferences the user must log in again using SOAP web services for the change to take effect. If the same session is used, the old time zone is used as well. Caching may also occur for a period after changing time zones.
-
Users setting the field value need to pay attention to the DST offset, as it influences the decision point (midnight of user's time zone) according to which value is set to the field.
-
If the time zone specified in a set field request is different from the time zone of the user setting the field, the datetime is first converted to the time zone of the user, and the date portion is stored. The time is then set to midnight and returned in PST or PDT. See the second row of the preceding example table for an example.
-
When posting dateTime values to NetSuite, you should indicate the time zone. If no time zone is indicated, the PST or PDT time zone is used. Note that NetSuite does not use GMT.
Setting Date and Time Format for SOAP Web Services
The following is an example of setting datetime, date, or time fields in SOAP web services, using Date-Time-Timezone:
<xmp><s0:endDate>2013-10-30T20:01:24.405-08:00</s0:endDate></xmp>
If the user does not indicate the time zone in the request, the NetSuite system time zone is used:
(PST UTC-8/PDT UTC-07): <xmp><s0:endDate>2013-10-30T20:01:24.405</s0:endDate></xmp>
Users can indicate a UTC time zone by adding the 'Z' character at the end of the DateTime format:
<xmp><s0:endDate>2013-10-30T20:01:24.405Z</s0:endDate></xmp>
Working with Daylight Saving Time in SOAP Web Services
At specified dates in the calendar year, the time is adjusted for daylight saving in some time zones. This causes a shift from standard time (such as CST) to daylight saving time (such as CDT), and inversely, depending on the time of the year. These changes come with a gain (start of daylight saving time) or loss (start of standard time) of one hour in time difference.
The NetSuite time zone settings in Home > Set Preferences (Administrator) are based on standard time settings. You must keep in mind the required adjustments during daylight saving time in the year. For example, if your time zone setting in shows (GMT-06:00) Central Time (US & Canada), this is perceived as -05:00 in SOAP web services context during daylight saving time, but -06:00 in standard time.
Therefore, if you send a SOAP web services request indicating CST (-6) when daylight saving time is in effect, as in the following example: <tranDate xsi:type="xsd:dateTime">2015-04-13T22:26:26.923-06:00</tranDate>, the datetime field on the target record is set using CDT (-5) i.e.23:26:26.923 instead of the intended 22:26:26.923.
If the time is close to midnight, the date may change to the next day after the conversion.