NAME
ServiceNow::Simple - Simple yet powerful ServiceNow API interface
SYNOPSIS
Note: To use the SOAP web services API the user you use must have the appropriate 'soap' role(s) (there are a few) and the table/fields must have access for the appropriate 'soap' role(s) if they are not open. This is true, whether you use this module or other web services to interact with ServiceNow.
There is a ServiceNow demonstration instance you can play with if you are unsure. Try https://demo019.service-now.com/navpage.do
using user 'admin' with password 'admin'. You will need to give the 'admin' user the 'soap' role and change the ACL for sys_user_group to allow read and write for the 'soap' role (see the Wiki http://wiki.servicenow.com/index.php?title=Main_Page
on how). Tables that are open do not need the ACL changes to allow access via these API's.
use ServiceNow::Simple;
## Normal (minimal) use
#######################
my $sn = ServiceNow::Simple->new({ instance => 'some_name', table => 'sys_user' });
# where your instance is https://some_name.service-now.com
## All options to new
#####################
my $sn = ServiceNow::Simple->new({
instance => 'some_name',
table => 'sys_user',
__display_value => 1, # Return the display value for a reference field
__limit => 23, # Maximum records to return
__log => $log, # Log to a File::Log object
__print_results => 1, # Print
__soap_debug => 1 # Print SOAP::Lite debug details
});
## Get Keys
###########
my $sn = ServiceNow::Simple->new({
instance => 'instance',
table => 'sys_user_group',
user => 'itil',
password => 'itil',
});
my $results = $sn->get_keys({ name => 'Administration' });
# Single match:
# $results = {
# 'count' => '1',
# 'sys_id' => '23105e1f1903ac00fb54sdb1ad54dc1a'
# };
$results = $sn->get_keys({ __encoded_query => 'GOTOnameSTARTSWITHa' });
# Multi record match:
# $results = {
# 'count' => '6',
# 'sys_id' => '23105e1f1903ac00fb54sdb1ad54dc1a,2310421b1cae0100e6ss837b1e7aa7d0,23100ed71cae0100e6ss837b1e7aa797,23100ed71cae0100e6ss837b1e7aa79d,2310421b1cae0100e6ss837b1e7aa7d4,231079c1b84ac5009c86fe3becceed2b'
# };
## Insert a record
##################
# Change table before insert
$sn->set_table('sys_user');
# Do the insert
my $result = $sn->insert({
user_name => 'GNG',
name => 'GNG Test Record',
active => 'true',
});
# Check the results, if there is an error $result will be undef
if ($result)
{
print Dumper($result), "\n";
# Sample success result:
# $VAR1 = {
# 'name' => 'GNG Test Record',
# 'sys_id' => '2310f10bb8d4197740ff0d351492f271'
# };
}
else
{
print Dumper($sn->{__fault}), "\n";
# Sample failure result:
# $VAR1 = {
# 'detail' => 'com.glide.processors.soap.SOAPProcessingException: Insert Aborted : Error during insert of sys_user (GNG Test Record)',
# 'faultcode' => 'SOAP-ENV:Server',
# 'faultstring' => 'com.glide.processors.soap.SOAPProcessingException: Insert Aborted : Error during insert of sys_user (GNG Test Record)'
# };
}
## Get Records
##############
my $sn = ServiceNow::Simple->new({
instance => 'some_name',
table => 'sys_user_group',
__print_results => 1,
});
my $results = $sn->get_records({ name => 'Administration', __columns => 'name,description' });
# Sample as printed to stdout, __print_results (same as $results):
# $data_hr = {
# 'count' => 1,
# 'rows' => [
# {
# 'description' => 'Administrator group.',
# 'name' => 'Administration'
# }
# ]
# };
# Encoded query with minimal returned fields
$results = $sn->get_records({ __encoded_query => 'GOTOnameSTARTSWITHa', __columns => 'name,email' });
# $results = {
# 'count' => 2,
# 'rows' => [
# {
# 'email' => '',
# 'name' => 'Administration'
# },
# {
# 'email' => 'android_dev@my_org.com',
# 'name' => 'Android'
# },
# ]
# };
## Update
#########
my $r = $sn->update({
sys_id => '97415d1f1903ac00fb54adb1ad54dc1a', ## REQUIRED, sys_id must be provided
active => 'true', # Other field(s)
}); # Administration group, which should always be defined, set 'Active' to true
# $r eq '97415d1f1903ac00fb54adb1ad54dc1a'
## Change to another table
##########################
$sn->set_table('sys_user');
## Change to another instance
#############################
$sn->set_instance('my_dev_instance');
## SOAP debug messages
##########################
$sn->soap_debug(1); # Turn on
... do something
$sn->soap_debug(0); # Turn off
KEY FEATURES
Caching of user, password and proxy - one place to change and user and password is not scattered through many scripts
Results in simple perlish style. Ensures consistancy of returned types, AVOIDS an array of hashes for many items and a hash for one item, thereby keeping your code simpler
Arguments are 'typed' as per the WSDL. This avoids UTF-8/16 data being encoded as base64 when it should be a string.
Allows returning of only those fields you require by defining them, rather than defining all the fields you don't want! See __columns below. This can save a lot of bandwidth when getting records.
STATUS
This is the early release and is subject to change while more extensive testing is carried out. More documentation to follow.
MAIN METHODS
The set of methods that do things on ServiceNow and return useful information
new
new creates a new 'ServiceNow::Simple' object. Parameters are passed in a hash reference. It requires that the instance of ServiceNow and the initial table be defined. The instance is the some_name in https://some_name.service-now.com. The table is the database name on the table to be operated on, for example the 'User' table is sys_user.
The parameters that can be passed are:
- instance
-
REQUIRED. The ServiceNow instance that ServiceNow::Simple should connect to.
- table
-
REQUIRED. The table that ServiceNow::Simple will operate on unless changed with table() method
- user
-
The user that ServiceNow::Simple will connect to the instance as. Note that this user will need to have one or more of the 'soap' roles. Note: if the configuration has been run and the user and password defined, this argument is not required. It can be used to over-ride the configuration value. See the 'simple.cfg' file located in the same location as the Simple.pm file. Note that the data in Simple.cfg is obfuscated (at least for user and password)
- password
-
The password for the user, see user above.
- __limit
-
Set the limit on the number of records that will be returned. By default this is 250 records. Settting this in the new method will apply this limit to all further calls unless that call defines it's own __limit.
= item __display_value
If set to true is will alter the way reference field information is returned. By default or if false a reference field will return the sys_id of the record. If set to true, the value returned is the display value (what you would see if looking at the form). This can also be set using the set_display_value() method.
- __print_results
-
If true, results return will also be printed to STDOUT using Date::Dumper's Dump method. See the print_results() method.
- __log
-
Used to define the log object. This can be a File::Log object or another log object that implements the msg(level, message) and exp(message) methods.
- __soap_debug
-
If true, with activate soap debug messages. See also the soap_debug() method.
get
Query a single record from the targeted table by sys_id and return the record and its fields. So the expected argument (hash reference) would be { sys_id => <the_sys_id> } and could also include:
- __exclude_columns
-
Specify a list of comma delimited field names to exclude from the result set
- __columns
-
The opposite (and more useful IMHO) of __exclude_columns, define that field name you want returned. Often this is a much smaller list.
- __use_view
-
Specify a Form view by name, to be used for limiting and expanding the results returned. When the form view contains deep referenced fields eg. caller_id.email, this field will be returned in the result as well
The get() returns a hash reference where the keys are the field names.
Example (that should run against the ServiceNow demo instance):
use ServiceNow::Simple;
use Data::Dumper;
my $sn = ServiceNow::Simple->new({
instance => 'demo019',
user => 'admin',
password => 'admin',
table => 'sys_user_group',
});
# THIS IS ONLY CALLED TO GET THE SYS_ID FOR THE GET CALL
my $results = $sn->get_keys({ name => 'CAB Approval' });
my $r = $sn->get({ sys_id => $results->{sys_id} });
print Dumper($r), "\n";
# Output from Dumper
$VAR1 = {
'active' => '1',
'cost_center' => '',
'default_assignee' => '',
'description' => 'CAB approvers',
'email' => '',
'exclude_manager' => '0',
'include_members' => '0',
'manager' => '',
'name' => 'CAB Approval',
'parent' => '',
'roles' => '',
'source' => '',
'sys_created_by' => 'admin',
'sys_created_on' => '2011-09-30 16:30:34',
'sys_id' => 'b85d44954a3623120004689b2d5dd60a',
'sys_mod_count' => '0',
'sys_updated_by' => 'admin',
'sys_updated_on' => '2011-09-30 16:30:34',
'type' => ''
};
get_keys
Query the targeted table by example values and return a comma delimited list of sys_id. Example values are key/value pairs where the key is the field name and the value is the value you want to match. You can also use an __encoded_query. See OTHER FIELD ARGUMENTS below.
$results = $sn->get_keys({ active => true, site_name => 'knoxfield', __limit => 6, });
# Multi record match:
# $results = {
# 'count' => '6',
# 'sys_id' => '23105e1f1903ac00fb54sdb1ad54dc1a,2310421b1cae0100e6ss837b1e7aa7d0,23100ed71cae0100e6ss837b1e7aa797,23100ed71cae0100e6ss837b1e7aa79d,2310421b1cae0100e6ss837b1e7aa7d4,231079c1b84ac5009c86fe3becceed2b'
# };
get_records
Query the targeted table by example values and return all matching records and their fields. See OTHER FIELD ARGUMENTS.
my $results = $sn->get_records({
active => true,
site_name => 'knoxfield',
__limit => 2,
__columns => 'name,description'
});
# Sample result set:
# $data_hr = {
# 'count' => 2,
# 'rows' => [
# {
# 'description' => 'Knoxfield Main Site',
# 'name' => 'KNX Main Office'
# },
# {
# 'description' => 'Knoxfield Warehouse',
# 'name' => 'KNX Warehouse'
# },
# ]
# };
insert
Creates a new record for the table. Note: You need to provide all fields configured as mandatory (these are reflected in the WSDL as fileds with the attribute minOccurs=1). Example:
$sn->set_table('sys_user');
my $result = $sn->insert({
user_name => 'GNG',
name => 'GNG Test Record',
active => 'true',
});
print Dumper($result), "\n";
# Sample success result:
# $VAR1 = {
# 'name' => 'GNG Test Record',
# 'sys_id' => '2310f10bb8d4197740ff0d351492f271'
# };
update
Updates an existing record in the targeted table, identified by the mandatory sys_id field. Example:
my $r = $sn->update({
sys_id => '97415d1f1903ac00fb54adb1ad54dc1a', ## REQUIRED, sys_id must be provided
active => 'true', # Other field(s)
});
$r will be the sys_id, unless there is a fault, in which case it is undef and $self->{__fault}
will be set as follows:
$self->{__fault}{faultcode}
$self->{__fault}{faultstring}
$self->{__fault}{detail}
RELATED METHODS
Allow you to change tables, instances, debug messages, printing etc
print_results
If called without an argument, returns the current value. Called with a true value sets printing of results using Data::Dumper's Dump method. Will also log to the log file if __log object is defined.
set_instance
Allows the instance to be changed from what was defined in the call to new.
set_table
Define the table the next method will work with/on. Example:
$sn->set_table('sys_user');
# query something on User table
#...
$sn->set_table('cmn_locations');
# Now query something on Locations table
soap_debug
Turn on or off soap debug messages. Example:
$sn->soap_debug(1); # Turn on debugging
# do some stuff
$sn->soap_debug(0); # Turn off debugging
# do some more stuff
set_display_value
Affects what is returned for a reference field. By default a reference field returns the sys_id of the field referenced. Turning on set_display_value will change this to return the display value for that table. Example:
$sn->set_display_value(1); # Turn on 'display value'
$sn->set_display_value(0); # Turn off 'display value', so sys_id is returned
PRIVATE METHODS
Internal, you should not use, methods. They may change without notice.
set_soap
SOAP::Transport::HTTP::Client::get_basic_credentials
_get_method
_init
_load_args
_load_wsdl
_print_fault
USEFUL LINKS
http://wiki.servicenow.com/index.php?title=Direct_Web_Services
http://wiki.servicenow.com/index.php?title=Direct_Web_Service_API_Functions
A demo instance: https://demo019.service-now.com/
Query building: http://wiki.servicenow.com/index.php?title=RSS_Feed_Generator
OTHER FIELD ARGUMENTS
__encoded_query
Specify an encoded query string to be used in filtering the returned results. The encoded query string format is similar to the value that may be specified in a sysparm_query URL parameter. Example:
__encoded_query => 'active=true^nameSTARTSWITHa'
__order_by
Determines what fields the results are ordered by (ascending order). Example:
__order_by => 'active'
__order_by_desc
Order by in descending order.
__exclude_columns
Specify a list of comma delimited field names to exclude from the results. This is, generally the opposite of what you want. See __columns below.
__columns
Define the columns you want in the results as a comma delimited list. Example:
__columns => 'active,name,sys_id'
__limit
Limit the number of records that are returned. The default is 250. This can be set in the constructor new(). Example:
__limit => 2000, # Return up to 2000 records
__first_row
Instruct the results to be offset by this number of records, from the beginning of the set. When used with __last_row has the effect of querying for a window of results. The results are inclusive of the first row number.
__last_row
Instruct the results to be limited by this number of records, from the beginning of the set, or the __start_row value when specified. When used with __first_row has the effect of querying for a window of results. The results are less than the last row number, and does not include the last row.
__use_view
Specify a Form view by name, to be used for limiting and expanding the results returned. When the form view contains deep referenced fields eg. caller_id.email, this field will be returned in the result as well
FILES
config.cache
Used to provide user, password and proxy settings for tests in /t
Simple.cfg
A configuration file that can contain the default user, password and proxy to use for all calls to method new() unless the 'user', 'password' and 'proxy' arguments are provided. The user and password are obfuscated. This is a very useful feature, only one place to change the user and password and they are not visible in a whole bunch of scripts.
VERSION
Version 0.05
AUTHOR
Greg George, <gng at cpan.org>
TODO
Currently the default SOAP serialization is used rather than forcing types from the WSDL. This can be a problem for UTF8 (non ASCII) characters which will likely be encoded as 'base64' rather than 'string'
BUGS
Please report any bugs or feature requests to bug-ServiceNow::Simple at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ServiceNow::Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc ServiceNow::Simple
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
The ServiceNow Wiki (see useful links), and authors of SOAP::Lite:
Paul Kulchenko (paulclinger@yahoo.com)
Randy J. Ray (rjray@blackperl.com)
Byrne Reese (byrne@majordojo.com)
Martin Kutter (martin.kutter@fen-net.de)
Fred Moyer (fred@redhotpenguin.com)
LICENSE AND COPYRIGHT
Copyright 2013 Greg George.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.