Perl web services client examples

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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 documentation provides practical Perl code examples demonstrating how to integrate with ServiceNow using a Perl web services client through SOAP. It specifically uses theSOAP::Litepackage along with prerequisites such asCrypt::SSLeayandIO::Socket::SSL. These examples enable ServiceNow customers to perform common record operations like inserting, updating, querying, and deleting records on ServiceNow tables such asIncidentandeccqueue.

    Show full answer Show less

    Key Features

    • Authentication: Basic authentication is handled via a Perl subroutine returning itil user credentials, ensuring secure access to ServiceNow SOAP endpoints.
    • Insert Records: Demonstrates inserting an incident with fields like shortdescription and category. Also includes an example inserting a record into eccqueue with an XML payload created using XML::Writer.
    • Update Records: Shows updating an incident record identified by sysid with field changes such as modifying the short description.
    • Query Records: Includes multiple methods:
      • getKeys: Retrieve a list of sysids for Incident records matching a category filter.
      • get: Retrieve a single Incident record by sysid, printing all fields.
      • getRecords: Query Incident records by field (e.g., category) and handle multiple results by iterating through returned records.
    • Delete Records: Example deleting an Incident record by sysid.
    • Error Handling: Each example includes subroutines to print SOAP faults and response details, aiding troubleshooting.

    Practical Application for ServiceNow Customers

    ServiceNow customers can use these Perl examples to automate common CRUD (Create, Read, Update, Delete) operations on ServiceNow records through SOAP-based web services. This is especially useful for integrating legacy Perl-based systems or custom scripts with ServiceNow.

    By leveraging these code snippets, customers can:

    • Insert new records into ServiceNow tables programmatically, including complex payloads such as XML documents.
    • Update existing records precisely by sysid.
    • Query records efficiently by various fields, retrieving full records or just keys for further processing.
    • Delete records when necessary with confirmation of operation success.
    • Handle authentication securely and manage SOAP responses and errors effectively.

    These examples form a foundation for building robust Perl integrations with ServiceNow SOAP APIs, enabling automated workflows, data synchronization, and notification handling.

    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";}}