Loading

Perl API

From ServiceNow Wiki
Home > Integrate > Web Services > Perl API
Jump to: navigation, search
Web Services

Contents

1 Overview

The Perl API provides a library of Perl classes and sub routines for programmatic access to the platform and its applications. The API utilizes the SOAP web service interface of the platform.

2 System Requirements

The ServiceNow Perl API requires Perl 5.8 (or later) with the following modules installed

Note
Note: Certain versions of the Perl API may not be compatible with the ServiceNow software and may cause 443 connection errors. ServiceNow recommends against using versions 5.14.2, 5.13.6, and 5.16.1 of Perl.


3 Installation

Click here [ ServiceNow-Perl-API.zip (v1.01) ] to download the Perl API. The Perl API is available for use under the terms defined in the Open Source Initiative OSI - Apache License, Version 2.0 license agreement.

After downloading the archive, unpack it into a directory and run the following commands (make sure you are a privileged user on the system):

perl Makefile.PL
make
make test
make install

After installing, you can find documentation for this module with the perldoc command.

perldoc ServiceNow

4 Architecture

Image:perl_api_overview.png
Perl API

4.1 ServiceNow.pm

At the top most of the class hierarchy is the ServiceNow.pm module. This module provides direct subroutines that delegate down into subroutines of the object heirarchy, providing a convenient calling convention if object oriented Perl programming is not a desired practice.

4.2 ITIL Objects

The next layer of the class hierarchy contains the ITIL Objects for example Incident.pm, and Change.pm. These objects extend the Task.pm object which inherits from the GlideRecord.pm object.

4.3 Configuration.pm

To use the Perl API, the programmer instantiates a Configuration.pm object and sets the service endpoint as well as the login credentials to use the API. For example:

my $CONFIG = ServiceNow::Configuration->new();
$CONFIG->setSoapEndpoint("https://instance_name.service-now.com/");

my $incident = ServiceNow::ITIL::Incident->new($CONFIG);

4.4 Connection.pm

The Connection.pm class defines the interfaces for making the SOAP calls to the platform. The default implementation uses the SOAP::Lite module, if you wish to implement your own SOAP interface, you can override this class with your own and implement the following subroutines:

  • new
  • open
  • send
  • close

Note: If running behind a firewall, edit Connection.pm to specify information about the HTTP proxy. In Connection.pm, change the line:

$me->{'SOAP'} = SOAP::Lite->proxy($CONFIG->getSoapEndPoint($target));

to:

$me->{'SOAP'} = SOAP::Lite->proxy($CONFIG->getSoapEndPoint($target), proxy => ['https' => 'http://myproxy.mycompany.com/']);

Substitute the appropriate proxy URL.

5 API

Class Description
ServiceNow.pm A class that contains data querying, creation, and modification subroutines for all the ITIL objects. It is a convenient entry point to the API without using the object oriented ITIL objects directly

5.1 ITIL Objects

Class Description
Incident.pm The incident class, extends Task, which extends GlideRecord. Maps to the incident table.
Problem.pm The problem class, extends Task, which extends GlideRecord. Maps to the problem table.
Change.pm The change request class, extends Task, which extends GlideRecord. Maps to the change_request table.
Request.pm The service request class, extends Task, which extends GlideRecord. Maps to the sc_request table.
RequestedItem.pm The service request item class, extends Task, which extends GlideRecord. Maps to the sc_req_item table.
SC_Task.pm The service request task class, extends Task, which extends GlideRecord. Maps to the sc_task table.
Task.pm The task class extends GlideRecord. Maps to the task table.
Ticket.pm The ticket class, extends Task, which extends GlideRecord. Maps to the ticket table.

5.2 Other

Class Description
Configuration.pm The API configuration class, this class must be passed to the constructor of the other API classes. It defines the SOAP endpoint as well as the credentials to use for API access.
GlideRecord.pm The class behind all table access classes.
Connection.pm The Connection class implements the web service access layer in an interface that can be overriden. By default, it uses the SOAP::Lite package for web services support.
Approval.pm The approval class extends GlideRecord. Maps to the sysapproval_approver table
Dictionary.pm The dictionary class extends GlideRecord. Maps to the sys_dictionary table
Attachment.pm The attachment class extends GlideRecord. Used to add attachments to the other objects

6 Examples

6.1 Using the ServiceNow.pm module

6.1.1 Creating an Incident

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");

my $SN = ServiceNow->new($CONFIG);

my $number = $SN->createIncident({"short_description" => "this incident was created from the Perl API", "category" => "hardware"});

print $number ."\n";

6.1.2 Querying an Incident

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");

my $SN = ServiceNow->new($CONFIG);

my @incidents = $SN->queryIncident({'number' => 'INC00002'});
my $count = scalar(@incidents);
print "number of incidents=" . $count . "\n";
foreach my $incident (@incidents) {
    print "Incident number: $incident->{'number'}\n";
    print "Assignent Group: $incident->{'assignment_group'}\n";
    print "Opened by:       $incident->{'opened_by'}\n";
    print "Opened by DV:    $incident->{'dv_opened_by'}\n";
    print "SD:       $incident->{'short_description'}\n";
    print "TW:       $incident->{'time_worked'}\n";
    print "\n"
}

6.1.3 Querying Journal fields

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");

my $SN = ServiceNow->new($CONFIG);

my @journals = $SN->queryJournal('INC00002');

print $journals[0]->{'element'} . " = " . $journals[0]->{'value'} ."\n";
print $journals[1]->{'element'} . " = " . $journals[1]->{'value'} ."\n";

6.2 Using the ITIL Objects

6.2.1 Creating an Incident

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;
use ServiceNow::ITIL::Incident;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");

# setting incident values as a hash map in the insert argument
my $incident = ServiceNow::ITIL::Incident->new($CONFIG);
my $sys_id = $incident->insert({"short_description" => "this incident was created from the Perl API", "category" => "hardware"});
print $sys_id ."\n";

# setting incident values by making setValue calls to the incident object
$incident = ServiceNow::ITIL::Incident->new($CONFIG);
$incident->setValue("short_description", "this incident was created from the Perl API - 2");
$incident->setValue("category", "hardware");
$sys_id = $incident->insert();
print $sys_id ."\n";

6.2.2 Querying for Incidents

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;
use ServiceNow::ITIL::Incident;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");

my $incident = ServiceNow::ITIL::Incident->new($CONFIG);
$incident->addQuery("assignment_group", "Service Desk");
$incident->addQuery("category", "Hardware");
$incident->query();
while($incident->next()) {
        print "number=" . $incident->getValue("number") . "\n";
        print "sd=" . $incident->getValue("short_description") . "\n";
        print "opened_by Display Value= " . $incident->getDisplayValue("opened_by") . "\n";
        print "opened_by sys_id= " . $incident->getValue('opened_by');
}

6.2.3 Adding an attachment to a newly created Incident

#!/usr/bin/perl -w

use ServiceNow;
use ServiceNow::Configuration;
use ServiceNow::ITIL::Incident;

my $CONFIG = ServiceNow::Configuration->new();

$CONFIG->setSoapEndPoint("https://<instance name>.service-now.com/");
$CONFIG->setUserName("admin");
$CONFIG->setUserPassword("admin");


my $incident = ServiceNow::ITIL::Incident->new($CONFIG);
$incident->setValue("short_description", "test incident for attachment 2");
$incident->insert();
$incident->attach("/Users/davidloo/Desktop/test_files/number_test.xls");

7 Version History

7.1 Version 1.01

6 Jun 2012 - Patch

  • Attachment library fix to remove additional dot between filename and suffix.
  • Attachment library fix to add binmode to FILE so Windows OS will handle properly.

7.2 Version 1.00

15 Mar 2010 - Original Version Release

Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Views
Personal tools