ServiceNow: SOAP Journal

Integration using Web Services

Time Zones and Date Formats

There is an inconsistent and somewhat unexpected behavior in how the Web Service API handles date-time fields.  This behavior is documented in the wiki:, and summarized as follows:

  • When reading data using Web Services:  all date and time fields are returned in GMT.
  • For updates, inserts and encoded queries:  date and time fields are assumed to be in local time.

To avoid time-zone problems, follow these two simple rules whenever using the Direct Web Services API.

  1. Create dedicated Web Services accounts in the sys_user table.  Do not use normal accounts which are assigned to real users.
  2. Set the time zone to GMT and the date format to yyyy-MM-dd for all Web Services accounts.

The inconsistent behavior is easily verified using a small perl script.  To reproduce the test, follow these instructions:

  1. Obtain a developer instance at
  2. Create a new user named “soap.test” with password “password”.
  3. Grant “soap.test” the following roles:
    • itil
    • soap_query_update
    • soap_create
  4. This script uses the ServiceNow::SOAP perl module.
  5. Edit the script, changing the instance to match your instance in step 1.
  6. Set the timezone for “soap.test” to anything other than GMT and run the script. Note that the dates do not match.
  7. Set the timezone for “soap.test” to GMT and run the script again.  Note that this time the dates match.
use strict;
use ServiceNow::SOAP;

my $instance = 'devxxxxx';
my $username = 'soap.test';
my $password = 'password';

my $sn = ServiceNow($instance, $username, $password);

# insert a change_request
my $change_request = $sn->table('change_request');

my $start_date = "2015-06-01 12:00:00";

my %result = $change_request->insert(
    short_description => 'Timezone change_request test',
    start_date => $start_date

my $sys_id = $result{sys_id};
my $number = $result{number};

print "inserted number=$number sys_id=$sys_id\n";

# read the record back
my $newrec = $change_request->getRecord($sys_id);

# compare the times
print "expected start_date=", $start_date, "\n";
print "actual   start_date=", $newrec->{start_date}, "\n";

Note: This post from May 2013 was updated in May 2015 to use ServiceNow::SOAP.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: