Scenario
User sends a web service request to create, update or retrieve a record in NetSuite but gets an incorrect value for the date or datetime field.
Solution
The web services operation used to demonstrate this topic is the Add and Get operations. However, this discussion applies to other operations that retrieve, set and manipulate date/datetime field values in NetSuite.
The Item Receipt record image below shows the date and datetime values set on the record created in NetSuite after the above web services Add request has been processed. Please note the change in date as time on request is near midnight.Figure 1.0
Sample Web Services SOAP XML Add request to create an Item Receipt record in NetSuite. The request sets a User interface date field (tranDate) and a custom datetime field (Date and Time) with internal ID - custbody26:
Figure 1.1
Figure 1.2
Excerpt of a Sample SOAP XML Get Web services operation response:
Figure 1.3
The following are the points to note when sending web services requests that manipulate or retrieve date/datetime fields in NetSuite:
Time zone:
All web services requests that retrieve data from date/datetime field, retrieve it in the Pacific Time Zone format (Figure 1.3). Please note that if the field in the user interface shows only the date portion, the retrieval request will assume midnight (12 AM or 00:00) for the time portion and '000' for the milliseconds portion of the date field before conversion to Pacific time zone (Server time) which is returned in the result set. For example, 2015-04-13T22:00:00.000-07:00 for date field and 2015-04-13T22:02:43.000-07:00 for datetime field. Kindly compare Figure 1.2 and Figure 1.3.
In cases of record creation or manipulation using web services operation, if the time zone is not specified in the request (e.g. 2015-04-13T22:26:26.923 - Figure 1.1), the application assumes Pacific time zone. At the point of web services request execution in NetSuite, the date and time set on the record will be dependent on the time zone settings of the web services user in Home > Set Preferences > Localization > Time Zone(Figure 1.0). For example, if the request is sent without specifying a time zone, NetSuite assumes Pacific time zone and then converts from Pacific time zone (PST/PDT) to User's time zone (CST/CDT) if user's time zone is not in Pacific time zone. Please see Figure 1.2 and 1.3 for the difference in dates after conversion.
Also, if you specify a time zone in the web services request (e.g. 2015-04-13T22:26:26.923-05:00), NetSuite converts the time specified in the request to the web services user's time zone if they are different. Please note that appending 'Z' to the datetime field value (e.g. 2015-04-13T22:26:26.923Z) via web services indicate UTC 00:00 (e.g. 2015-04-13T22:26:26.923-00:00). Conversion is still done based on user timezone preferences. Hence, for a datetime value of '2015-04-13T22:26:26.923Z' and web services time zone of Central Daylight Time (-05:00), the date/datetime field is set as '2015-04-13T17:26:26.923' on the record. In the user interface, the record displays '2015-04-13' for date field and '2015-04-13 17:26:26' or '2015-04-13 05:26:26 pm' for datetime field. In all cases, please take daylight saving time into consideration. This is further explained in the 'Daylight Saving Time' section below.
Daylight Saving Time:
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 e.g. CST to Daylight time e.g. CDT and vice versa depending on the time of the year. These changes come with a gain (start of daylight time) or loss (start of standard time) of one (1) hour in time difference.
The NetSuite timezone setting in Home > User Preferences > Localization > Time Zone(Figure 1.0) are based on standard time settings. Hence, the user needs to keep in mind required adjustments during daylight time in the year. For example, if your time zone setting in User > Set Preferences shows (GMT-06:00) Central Time (US & Canada), this is perceived as -05:00 in web services context during daylight time but -06:00 in Standard time.
Therefore, if you send a web services request indicating CST (-6) during daylight time of the year as shown below:
<tranDatexsi:type="xsd:dateTime">2015-04-13T22:26:26.923-06:00</tranDate>In summary, your timezone in the user preferences is adjusted for daylight savings when setting datetime fields at daylight time of the year.