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 c<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 offSTATUS
This is the initial 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 =head2 get =head2 get_keys =head2 get_records =head2 insert =head2 update
RELATED METHODS
Allow you to change tables, instances, debug messages, printing etc
print_results =head2 set_instance =head2 set_soap =head2 set_table =head2 soap_debug
PRIVATE METHODS
Internal, you should not use, methods. They may change without notice.
SOAP::Transport::HTTP::Client::get_basic_credentials =head2 _get_method =head2 _init =head2 _load_args =head2 _load_wsdl =head2 _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_FunctionsVERSION
Version 0.01
AUTHOR
Greg George, <gng at cpan.org>
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::SimpleYou 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.