servicenow(3) - Linux man page

ServiceNow module

Service-now Perl API - ServiceNow perl module

Desciption

ServiceNow module is a collection of Perl subroutines that provides convenient and direct access to the Service-now platform

System Requirements

The Service-now Perl API requires Perl 5.8 with the following modules installed 
* SOAP::Lite (prerequisites http://soaplite.com/prereqs.html) 0.71 or later
* Crypt::SSLeay
* IO::Socket::SSL

Constructor

new

new(Configuration object, optional Instance ID )

Example: 

$config = ServiceNow::Configuration->new();
$SN = ServiceNow->new($config);
Sets up an instance of the ServiceNow object using a Configuration object and an optional Instance ID .

Subroutines

Incident

createIncident

createIncident(optional paramaters)

Example: 

$number = $SN->createIncident({"short_description" => "this is the short description"});
Create an incident. Returns an incident number upon success. On failure returns undef.

queryIncident

queryIncident(Reference to named parameters hash of Incident fields and exact values)

Example: 

@results = $SN->queryIncident({'number' => 'INC0000054'});
Query for Incidents matching specified criteria. Returns an array of incident records.

updateIncident

updateIncident($number, optional hash of Incident fields and values to update)

Example: 

$ret = $SN->updateIncident($number,{$field => $value});
Update a ServiceNow incident Returns undef on failure, all other values indicate success.

closeIncident

closeIncident(incident number, optional hash of Incident fields and values to update)

Example: 

$number = $SN->closeIncident($number, {$field => $value});
Close a ServiceNow Incident and optionally specify work effort. Returns the incident number on success, undef on failure.

reopenIncident

reopenIncident(incident number)

Example: 

my $ret = $SN->reopenIncident('INC99999');
Reopen a closed ServiceNow incident. Returns the incident number on success, undef on failure.

reassignIncident

reassignIncident(Incident number, assignment group, optional assigned to)

Example: 

my $ret = $SN->reassignIncident('INC99999', 'SOME_GROUP');
my $ret = $SN->reassignIncident('INC99999', 'SOME_GROUP', 'username');
Reassign a ServiceNow Incident to a new assignment_group.(and optionally specify an assigned_to) Returns the incident number on success, undef on failure.

Ticket

createTicket

createTicket(Reference to named parameters hash of ticket fields and values)

Example: 

my $number = $SN->createTicket({"category" => "hardware"});
Create a ServiceNow ticket associated with an incident. Returns a ticket number upon success. On failure returns undef.

updateTicket

updateTicket(The ticket number , Reference to named parameters hash of ticket fields and values to update)

Example: 

my $ret = $SN->updateTicket($number, {$field => $value});
Returns undef on failure, all other values indicate success.

queryTicket

queryTicket( Reference to named parameters hash of Incident fields and exact values )

Example: 

my @tickets = $SN->queryTicket({'number' => $number});
Query for tickets matching specified criteria. Reference to array of hashes of all matching tickets, undef on failure or if no records found.

closeTicket

closeTicket(Ticket number, {$field => $value})

Example: 

my $ret = $SN->closeTicket($number);
my $ret = $SN->closeTicket($number, {"comments" => "ticket closed"});
Close a ServiceNow ticket and optionally specify work effort. Returns the ticket number on success, undef on failure.

reopenTicket

reopenTicket(The ticket number)

Example: 

my $ret = $SN->reopenTicket('TKT99999');
Reopen a closed ServiceNow ticket. Returns the ticket number on success, undef on failure.

reassignTicket

reassignTicket(ticket number, the incident assignment group, optional person to assign the ticket to)

Example: 

my $ret = $SN->reassignTicket('TKT99999', 'SOME_GROUP');
my $ret = $SN->reassignTicket('TKT99999', 'SOME_GROUP', 'username');
Reassign a ServiceNow ticket to a new assignment_group. Returns the ticket number on success, undef on failure.

RequestedItem / Request

createRequestedItem

createRequestedItem(catalog item number, requested for, variables)

Example: 

my $req = $SN->createRequestedItem('CITM10000', "username", {'description' => 'Some description', 'group' => 'SOME_GROUP'});
Create a Service Catalog RequestedItem (and indirectly the associated Request and Tasks). Returns a RequestedItem number upon success. On failure returns undef.

queryRequestedItem

queryRequestedItem(Reference to named parameters hash of RequestedItem fields and exact values)

Example: 

my $requestedItems = $SN->queryRequestedItem({'number' => 'SOME_RI_NUMBER'});
Query for RequestedItems matching specified criteria. Reference to array of hashes of all matching RequestedItem, undef on failure or if no records found.

queryRequest

queryRequest(Reference to named parameters hash of Request fields and exact values)

Example: 

my $requests = $SN->queryRequest({'number' => 'SOME_REQUEST_NUMBER'});
Query for Requests matching specified criteria. Reference to array of hashes of all matching Request, undef on failure or if no records found.

Task

createTask

createTask(optional paramaters)

Example: 

$number = $SN->createTask({"short_description" => "this is the short description"});
Create a task record. Returns an task number upon success. On failure returns undef.

closeTask

closeTask(task number, optional work effort in seconds)

Example: 

my $ret = $SN->closeTask($number);
my $ret = $SN->closeTask($number, $seconds);
Close a ServiceNow Task and optionally specify work effort. Returns true on success, undef on failure.

reopenTask

reopenTask(task number)

Example: 

my $ret = $SN->reopenTask('TASK99999');
Reopen a closed ServiceNow Task. Returns true on success, undef on failure.

reassignTask

reassignTask(task number, assignment group, optional person it is being assigned to)

Example: 

my $ret = $SN->reassignTask('TASK99999', 'SOME_GROUP');
my $ret = $SN->reassignTask('TASK99999', 'SOME_GROUP', 'username');
Reassign a ServiceNow Task to a new assignment_group. (and optionally specify an assigned_to) Returns true on success, undef on failure.

updateTask

updateTask(task number, reference to named parameters hash of Task fields and values)

Example: 

my $ret = $SN->updateTask($number, {$field => $value});
Update a ServiceNow Task. Returns true on success, undef on failure.

queryTask

queryTask(reference to named parameters hash of Task fields and exact values )

Example: 

my @tasks = $SN->queryTask({'number' => $number});
foreach my $task (@tasks) {
   print "Incident number: $task->{'number'}\n";
   print "Assignent Group: $task->{'assignment_group'}\n";
   print "Opened by:       $task->{'opened_by'}\n";
   print "SD:       $task->{'short_description'}\n";
   print "TW:       $task->{'time_worked'}\n";
   print "\n"
}
Query for Tasks matching specified criteria. Array of hashes of all matching Tasks, undef on failure or if no records found.

Journal

queryJournal

queryJournal(Incident/Ticket/Task number, optional journal field name )

Query for journals entries for the specified incident, ticket or task. Return array of hashes of all matching Journals, undef on failure or if no records found. There will be one hash per per journal entry, 'value' will contain the journal entry string, 'element' will be the name of the field (e.g. 'comments', 'work_notes', etc.)

appendJournal

appendJournal(Incident/Ticket/Task number, field name, journal text)

Example: 

my $ret =  $SN->appendJournal('INC99999', 'comments' "some comment text");
Append a journal entry to the specified journal field of an incident, ticket, or task. Returns true on success, undef on failure.

Approval

queryApproval

queryApproval(reference to named parameters hash of approval fields and exact values)

Example: 

my @approvals = $SN->queryApproval({'approver' => 'username'});
Query for approvals Return array of hashes of all matching approvals, undef on failure or if no records found.

approve

approve(sys_id of the approval,approval state,optional comment text)

Example: 

my $ret = $SN->approve($sys_id, 'Approved');
my $ret = $SN->approve($sys_id, 'Rejected', "Please do something else");
Approve/reject a ServiceNow approval request and optionally provide a comment. Returns the sys_id on success, undef on failure.

Dictionary

queryFields

queryFields(table, optional boolean)

Example: 

my @fields = $SN->queryFields('incident');
List all the fields of an Incident, Request, RequestedItem or Task. Returns a reference to a hash of fields in the specified table type. The hash key is the field name, and the hash value is a hash reference to attributes about the field: 'mandatory', 'hint', 'label', 'reference' and 'choice'. Returns undef on failure. If getchoices is true then 'choices' is a reference to a hash containing individual choices, keyed by choice value and containing choice 'label' and 'hint'.