The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ServiceNow-Simple-0.04
River stage zero No dependents
/ ServiceNow::Simple

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

STATUS

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

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 date 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

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

VERSION

Version 0.04

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:

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.