Perl web services client examples

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Perl web services client examples

    This content provides practical Perl code examples demonstrating how to integrate with ServiceNow web services using theSOAP::LitePerl package. It covers key operations such as inserting, updating, retrieving, and deleting records in ServiceNow tables via SOAP API calls. These examples are designed to help ServiceNow customers automate and interact programmatically with their instance data using Perl scripts.

    Show full answer Show less

    The examples assume Perl 5.8 or later, and require dependencies including SOAP::Lite, Crypt::SSLeay, and IO::Socket::SSL. Authentication is handled via basic auth with user credentials embedded in the Perl client.

    Key Features

    • Insert Records: Scripts show how to insert new records into tables such as incident and eccqueue. The eccqueue example demonstrates sending an XML payload built using XML::Writer for complex data structures.
    • Update Records: Update an existing record by specifying its sysid and providing the fields to change, such as shortdescription.
    • Retrieve Keys and Records: Retrieve record identifiers (keys) filtered by criteria (e.g., incidents with category "Network"). Retrieve single records by sysid or by unique fields like incident number, and also retrieve multiple records matching a condition.
    • Delete Records: Delete a record by specifying its sysid.
    • Result and Fault Handling: Each example includes subroutines to print SOAP call results and handle SOAP faults for easier debugging and integration monitoring.

    Practical Application for ServiceNow Customers

    ServiceNow customers can leverage these Perl client samples to:

    • Automate data operations with their ServiceNow instance using familiar Perl scripts.
    • Integrate external Perl-based systems or monitoring tools by programmatically inserting or querying incident and queue data.
    • Handle complex payloads by constructing XML data for fields like payload in eccqueue.
    • Manage records programmatically including creation, updates, retrievals by various keys, and deletions, all over SOAP web services.
    • Implement basic authentication within Perl clients securely for SOAP endpoints.

    These examples form a solid foundation for customers wanting to extend or integrate ServiceNow capabilities using Perl, particularly in environments where Perl is the standard scripting language or for legacy system integrations.

    Examples demonstrating an integration with a Perl web services client.

    Note:
    The following examples require the usage of the Perl language and the SOAP::Lite package.

    System Requirements

    Perl 5.8

    insert

    The following example will insert a record into the Incident table.
    #!/usr/bin/perl -w
 
# declare usage of SOAP::Liteuse SOAP::Lite;
 
# specifying this subroutine, causes basic auth to use# its credentials when challengedsub SOAP::Transport::HTTP::Client::get_basic_credentials{# login as the itil userreturn'itil'=>'itil';}
 
# declare the SOAP endpoint heremy$soap= SOAP::Lite->proxy('https://myinstance.service-now.com/incident.do?SOAP');
 
# calling the insert functionmy$method= SOAP::Data->name('insert')->attr({xmlns =>'http://www.service-now.com/'});
 
# create a new incident with the following short_description and categorymy@params=( SOAP::Data->name(short_description =>'This is an example short description'));push(@params, SOAP::Data->name(category =>'Hardware'));
 
# invoke the SOAP callmy$result=$soap->call($method=>@params);
 
# print any SOAP faults that get returned
print_fault($result);# print the SOAP response that get return
print_result($result);
 
# convenient subroutine for printing all resultssub print_result {my($result)=@_;
 
  if($result->body&&$result->body->{'insertResponse'}){my%keyHash=%{$result->body->{'insertResponse'}};foreachmy$k(keys%keyHash){print"name=$k   value=$keyHash{$k}\n";}}}
 
# convenient subroutine for printing all SOAP faultssub print_fault {my($result)=@_;
 
  if($result->fault){print"faultcode=".$result->fault->{'faultcode'}."\n";print"faultstring=".$result->fault->{'faultstring'}."\n";print"detail=".$result->fault->{'detail'}."\n";}}

    insert (With XML payload)

    The following is an example of inserting a record into the ecc_queue table where the payload field is an XML document. This is done using the Perl language and the SOAP::Lite package, the XML document creation uses the XML::Writer package:
    #!/usr/bin/perl -w#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;use XML::Writer;use XML::Writer::String;
 
## Get parameters passed by OVO notification#$OVMSG{id}=$ARGV[0];$OVMSG{node_name}=$ARGV[1];$OVMSG{node_type}=$ARGV[2];$OVMSG{date_created}=$ARGV[3];$OVMSG{time_created}=$ARGV[4];$OVMSG{date_received}=$ARGV[5];$OVMSG{time_received}=$ARGV[6];$OVMSG{application}=$ARGV[7];$OVMSG{msg_group}=$ARGV[8];$OVMSG{object}=$ARGV[9];$OVMSG{severity}=$ARGV[10];$OVMSG{operator_list}=$ARGV[11];$OVMSG{msg_text}=$ARGV[12];$OVMSG{instruction}=$ARGV[13];
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://<instance name>.service-now.com/ecc_queue.do?SOAP');
 
my$method= SOAP::Data->name('insert')->attr({xmlns =>'http://www.service-now.com/'});
 
# get all incidents with category Networkmy@params=( SOAP::Data->name(agent =>'OVO_Notification'));push(@params, SOAP::Data->name(queue =>'input'));push(@params, SOAP::Data->name(name =>'HP Openview OVO Notification'));push(@params, SOAP::Data->name(source =>$OVMSG{id}));
 
my$s= XML::Writer::String->new();my$writer=new XML::Writer(OUTPUT =>$s);
 
#$writer->xmlDecl();$writer->startTag('notification');
 
write_element('id');
write_element('node_name');
write_element('node_type');
write_element('date_created');
write_element('time_created');
write_element('date_received');
write_element('time_received');
write_element('application');
write_element('msg_group');
write_element('object');
write_element('severity');
write_element('operator_list');
write_element('msg_text');
write_element('instruction');
 
$writer->endTag('notification');
 
$writer->end;
 
sub write_element {my$label=shift;my$value=$OVMSG{$label};$writer->startTag($label);if($value){$writer->characters($value);}$writer->endTag($label);}
 
push(@params, SOAP::Data->name(payload =>$s->value()));
 
print$soap->call($method=>@params)->result;</pre>
 
=== Response to the ''insert''===<source lang="xml"><?xml version="1.0" encoding="UTF-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XML Schema-instance"><soap:Body><insertResponse xmlns="http://www.service-now.com/ecc_queue"><sys_id>1a5ad50e0a0a021101bef2e07705f87a</sys_id><name>HP Openview OVO Notification</name></insertResponse></soap:Body></soap:Envelope>

    update

    #!/usr/bin/perl -w
 
#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://localhost:8080/glide/incident.do?SOAP');
 
my$method= SOAP::Data->name('update')->attr({xmlns =>'http://www.service-now.com/'});
 
# update incident by sys_idmy@params=( SOAP::Data->name(sys_id =>'e8caedcbc0a80164017df472f39eaed1'));push(@params, SOAP::Data->name(short_description =>'this is a new description'));
 
my$result=$soap->call($method=>@params);
 
print_fault($result);
print_result($result);
 
sub print_result {my($result)=@_;
 
  if($result->body&&$result->body->{'updateResponse'}){my%keyHash=%{$result->body->{'updateResponse'}};foreachmy$k(keys%keyHash){print"name=$k   value=$keyHash{$k}\n";}}}
 
sub print_fault {my($result)=@_;
 
  if($result->fault){print"faultcode=".$result->fault->{'faultcode'}."\n";print"faultstring=".$result->fault->{'faultstring'}."\n";print"detail=".$result->fault->{'detail'}."\n";}}

    getKeys

    The following is an example of retrieving a list of s for records of Incident where is Network.

    #!/usr/bin/perl -w
 
#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://<instance name>.service-now.com/incident.do?SOAP');
 
my$method= SOAP::Data->name('getKeys')->attr({xmlns =>'http://www.service-now.com/'});
 
# get all incidents with category Networkmy@params=( SOAP::Data->name(category =>'Network')); 
 
print$soap->call($method=>@params)->result;

    get

    The following is an example of retrieving an Incident record using its sys_id value.

    #!/usr/bin/perl -w#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://<instance name>.service-now.com/incident.do?SOAP');
 
my$method= SOAP::Data->name('get')->attr({xmlns =>'http://www.service-now.com/'});
 
# get incident by sys_idmy@params=( SOAP::Data->name(sys_id =>'9d385017c611228701d22104cc95c371'));
 
my%keyHash=%{$soap->call($method=>@params)->body->{'getResponse'}};
 
# iterate through all fields and print themforeachmy$k(keys%keyHash){print"$k=$keyHash{$k}\n";}

    getRecords

    To query for an Incident using its incident number value:
    #!/usr/bin/perl -w#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://<instance name>.service-now.com/incident.do?SOAP');
 
my$method= SOAP::Data->name('getRecords')->attr({xmlns =>'http://www.service-now.com/'});# get incident by numbermy@params=( SOAP::Data->name(number =>'INC10001'));
 
my%keyHash=%{$soap->call($method=>@params)->body->{'getRecordsResponse'}->{'getRecordsResult'}};
 
# iterate through all fields and print themforeachmy$k(keys%keyHash){print"$k=$keyHash{$k}\n";}

    getRecords (Returning Multiple Results)

    The following is an example of retrieving and displaying an array of Incident records by querying all Incidents that have a of "Network"

    #!/usr/bin/perl -w#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://<instance name>.service-now.com/incident.do?SOAP');
 
my$method= SOAP::Data->name('getRecords')->attr({xmlns =>'http://www.service-now.com/'});
 
# get incident by sys_idmy@params=( SOAP::Data->name(category =>'Network'));
 
my%keyHash=%{$soap->call($method=>@params)->body->{'getRecordsResponse'}};
 
my$i=0;my$size=@{$keyHash{'getRecordsResult'}};for($i=0;$i<$size;$i++){my%record=%{$keyHash{'getRecordsResult'}[$i]};print"------------------------------ $i ----------------------------\n";foreachmy$kk(keys%record){print"$kk=$record{$kk}\n";}}

    deleteRecord

    #!/usr/bin/perl -w
 
#use SOAP::Lite ( +trace => all, maptype => {} );use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials{return'itil'=>'itil';}
 
my$soap= SOAP::Lite->proxy('http://localhost:8080/glide/incident.do?SOAP');
 
my$method= SOAP::Data->name('deleteRecord')->attr({xmlns =>'http://www.service-now.com/'});
 
# delete incident by sys_idmy@params=( SOAP::Data->name(sys_id =>'46f67787a9fe198101e06dfcf3a78e99'));
 
my$result=$soap->call($method=>@params);
 
print_fault($result);
print_result($result);
 
sub print_result {my($result)=@_;
 
  if($result->body&&$result->body->{'deleteRecordResponse'}){my%keyHash=%{$result->body->{'deleteRecordResponse'}};foreachmy$k(keys%keyHash){print"name=$k   value=$keyHash{$k}\n";}}}
 
sub print_fault {my($result)=@_;
 
  if($result->fault){print"faultcode=".$result->fault->{'faultcode'}."\n";print"faultstring=".$result->fault->{'faultstring'}."\n";print"detail=".$result->fault->{'detail'}."\n";}}