ServiceNow: SOAP Journal

Integration using Web Services

Category Archives: Best Practices

Announcing ServiceNow::SOAP – a better Perl API

I am excited to announce the release on CPAN of ServiceNow::SOAP — a better Perl API for ServiceNow.

This module has the following features:

  • Support for both Direct and Scripted Web Services.
  • The Direct Web Services methods closely match ServiceNow’s published methods, allowing you to take advantage of all features documented in the ServiceNow wiki.
  • Easy to use methods for querying large tables.  These methods follow ServiceNow’s best practice recommendation, which is to call getKeys before calling getRecords.
  • Query performance can be improved by limiting the list of columns returned.
  • Support for insertMultiple.
  • Detailed POD documentation, with lots of examples.

If you are using Perl, please check out ServiceNow::SOAP here, and give me your feedback.


Using SoapUI to test Web Services

SoapUI is a nifty tool for testing Web Services. I use it all the time.  It really helps you understand what is happening.  Check out this great video by John Andersen:

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.