SOAP Web Service and time zones examples

jonnyseymour · ‎07-14-2015

After reading this documents, you should understand:

What is the impact of different time zones on Web Services
How to pass the time in client time to be converted into UTC
How does it look on a simple web service
How does it look on a scripted web service

Different time zones

The system has a default time zone usually as US/Pacific (PDT = UTC-7).

That difference is considered when saving the date/time fields from clients. At database level, they are stored as UTC.

Web services are very consistent but time-zones has a few considerations:

On WS messages, TRY to pass the INPUT date/time fields as UTC. If you pass the information as TEXT (not inside javascript), it's considered as UTC.
If a CLIENT need to pass client date/time, USE glide construction javascript (gs.dateGenerate). The server will transform into UTC later on.
The WS date/time responses come back in UTC as well.

e.g. On a SOAP request, if you use

...

<input xxxx> javascript:gs.dateGenerate('2015-05-09','00:00:00') </input xxxx>

...

That ensure the date will be consider NON-UTC and transformed into client the timezone for the queries so it will retrieve the same results

as when searching on the Web interface that tend to be confusing to customer. Note the response* date/time fields will be on UTC as well.

Below are a few cases of the behavior when date/time fields are used:

User has US/Pacific time zone	Date/time	UTC	RESULT
User Browser	2015-06-26 03:11:41	2015-06-26 10:11:41	Set Display time
Database	2015-06-26 10:11:41	2015-06-26 10:11:41	No difference
Web Service	2015-06-26 10:11:41	2015-06-26 10:11:41	No difference
Web Service	2015-06-26 03:11:41	2015-06-26 03:11:41	No difference
Web Service	gs.DateGenerate('2015-06-26','10:11:41')	2015-06-26 17:11:41	Set Display time
Web Service	gs.DateGenerate('2015-06-26','03:11:41')	2015-06-26 10:11:41	Set Display time
Web service Response	2015-06-26 10:11:41	2015-06-26 10:11:41	No difference. It is UTC

If I create a new incident. Based on an incident INCD045006 with field

* open_at=10:11:41 UTC,

the following is the expected behavior with getRecords operation:

Users browsing the incident form will see the date on their local time zone.

That is because the user has US/Pacific (PDT = UTC-7) set on their User profile form.

That is UTC = 10:11:41 ==> UTC-7 = 03:11:41

Here is what we know SOAP will handle those time zones on Get Operations:

On SOAP getRecords operation, you can input the date/time fields:

1. With dates as text — you need to use UTC times

2. With dates created with glide — you need to use User localized times

Here are some examples:

Case 1: Using the date as text: Use UTC times to match your records

As you can see, you need to submit the date/time input AS TEXT in UTC times (not client times)

Here is the text for the query-using date in text:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inc="http://www.service-now.com/incident">
   <soapenv:Header/>
   <soapenv:Body>
           <inc:getRecords>
                       <__encoded_query>opened_at&gt;2015-06-26T10:00:00
                                                                                       ^opened_at&lt;2015-06-26T10:12:00</__encoded_query>
</inc:getRecords>
   </soapenv:Body>
</soapenv:Envelope>

Case 2: Using glide to generate times: Use the time on the SOAP user localized times.

As you can see, when using glide based data/time, you need to provide the date as the client time-zone set. However, notice the result will be back in UTC.

Here is the request for the query-using glide:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inc="http://www.service-now.com/incident">
   <soapenv:Header/>
   <soapenv:Body>
           <inc:getRecords>
                       <__encoded_query>opened_at&gt;javascript:gs.dateGenerate(&#39;2015-06-26&#39;,&#39;03:11:00&#39;)
                       ^opened_at&lt;javascript:gs.dateGenerate(&#39;2015-06-26&#39;,&#39;03:12:00&#39;)</__encoded_query>
           </inc:getRecords>
   </soapenv:Body>
</soapenv:Envelope>

FOR SCRIPTED WEB-SERVICES

You can modify the normal behavior on your script itself. By default, text is considered as UTC date/time.

If changes on the scripting side are required, you could use setDisplayValue(data) to get the transformation into UTC wanted from the client text submitted.

Below is an example:

If you are passing the date/time information as text, you could set them as follow:

// scripted webservice snip 
var gdt1 = new GlideDateTime();
gdt1.setDisplayValue(request.start_date);   <-- IF THE INPUT WAS DATE/TIME TEXT, the script will consider it as client date INSTEAD of UTC (default)

Considering request.start date is the date/field passed as input to the Scripted Web Service.

You can also perform a similar script to provide the date/time fields responses into the client time instead of UTC.

More information here:

NOTES: Tested on Fuji, Firefox 38.05 and Soap UI 5.1.3

Let me know if you have found a different behavior