1ServiceNow(3)         User Contributed Perl Documentation        ServiceNow(3)
2
3
4

ServiceNow module

6       Service-now Perl API - ServiceNow perl module
7

Desciption

9       ServiceNow module is a collection of Perl subroutines that provides
10       convenient and direct access to the Service-now platform
11
12   System Requirements
13       The Service-now Perl API requires Perl 5.8 with the following modules
14       installed
15
16         * SOAP::Lite (prerequisites http://soaplite.com/prereqs.html) 0.71 or later
17         * Crypt::SSLeay
18         * IO::Socket::SSL
19

Constructor

21       new
22
23       new(Configuration object, optional Instance ID)
24
25       Example:
26
27         $config = ServiceNow::Configuration->new();
28         $SN = ServiceNow->new($config);
29
30       Sets up an instance of the ServiceNow object using a Configuration
31       object and an optional Instance ID.
32

Subroutines

34   Incident
35       createIncident
36
37       createIncident(optional paramaters)
38
39       Example:
40
41         $number = $SN->createIncident({"short_description" => "this is the short description"});
42
43       Create an incident.  Returns an incident number upon success. On
44       failure returns undef.
45
46       queryIncident
47
48       queryIncident(Reference to named parameters hash of Incident fields and
49       exact values)
50
51       Example:
52
53         @results = $SN->queryIncident({'number' => 'INC0000054'});
54
55       Query for Incidents matching specified criteria.  Returns an array of
56       incident records.
57
58       updateIncident
59
60       updateIncident($number, optional hash of Incident fields and values to
61       update)
62
63       Example:
64
65         $ret = $SN->updateIncident($number,{$field => $value});
66
67       Update a ServiceNow incident Returns undef on failure, all other values
68       indicate success.
69
70       closeIncident
71
72       closeIncident(incident number, optional hash of Incident fields and
73       values to update)
74
75       Example:
76
77         $number = $SN->closeIncident($number, {$field => $value});
78
79       Close a ServiceNow Incident and optionally specify work effort.
80       Returns the incident number on success, undef on failure.
81
82       reopenIncident
83
84       reopenIncident(incident number)
85
86       Example:
87
88         my $ret = $SN->reopenIncident('INC99999');
89
90       Reopen a closed ServiceNow incident.  Returns the incident number on
91       success, undef on failure.
92
93       reassignIncident
94
95       reassignIncident(Incident number, assignment group, optional assigned
96       to)
97
98       Example:
99
100         my $ret = $SN->reassignIncident('INC99999', 'SOME_GROUP');
101         my $ret = $SN->reassignIncident('INC99999', 'SOME_GROUP', 'username');
102
103       Reassign a ServiceNow Incident to a new assignment_group.(and
104       optionally specify an assigned_to) Returns the incident number on
105       success, undef on failure.
106
107   Ticket
108       createTicket
109
110       createTicket(Reference to named parameters hash of ticket fields and
111       values)
112
113       Example:
114
115         my $number = $SN->createTicket({"category" => "hardware"});
116
117       Create a ServiceNow ticket associated with an incident.  Returns a
118       ticket number upon success. On failure returns undef.
119
120       updateTicket
121
122       updateTicket(The ticket number , Reference to named parameters hash of
123       ticket fields and values to update)
124
125       Example:
126
127         my $ret = $SN->updateTicket($number, {$field => $value});
128
129       Returns undef on failure, all other values indicate success.
130
131       queryTicket
132
133       queryTicket( Reference to named parameters hash of Incident fields and
134       exact values )
135
136       Example:
137
138         my @tickets = $SN->queryTicket({'number' => $number});
139
140       Query for tickets matching specified criteria.  Reference to array of
141       hashes of all matching tickets, undef on failure or if no records
142       found.
143
144       closeTicket
145
146       closeTicket(Ticket number, {$field => $value})
147
148       Example:
149
150         my $ret = $SN->closeTicket($number);
151         my $ret = $SN->closeTicket($number, {"comments" => "ticket closed"});
152
153       Close a ServiceNow ticket and optionally specify work effort.  Returns
154       the ticket number on success, undef on failure.
155
156       reopenTicket
157
158       reopenTicket(The ticket number)
159
160       Example:
161
162         my $ret = $SN->reopenTicket('TKT99999');
163
164       Reopen a closed ServiceNow ticket.  Returns the ticket number on
165       success, undef on failure.
166
167       reassignTicket
168
169       reassignTicket(ticket number, the incident assignment group, optional
170       person to assign the ticket to)
171
172       Example:
173
174         my $ret = $SN->reassignTicket('TKT99999', 'SOME_GROUP');
175         my $ret = $SN->reassignTicket('TKT99999', 'SOME_GROUP', 'username');
176
177       Reassign a ServiceNow ticket to a new assignment_group.  Returns the
178       ticket number on success, undef on failure.
179
180   RequestedItem / Request
181       createRequestedItem
182
183       createRequestedItem(catalog item number, requested for, variables)
184
185       Example:
186
187         my $req = $SN->createRequestedItem('CITM10000', "username", {'description' => 'Some description', 'group' => 'SOME_GROUP'});
188
189       Create a Service Catalog RequestedItem (and indirectly the associated
190       Request and Tasks).  Returns a RequestedItem number upon success. On
191       failure returns undef.
192
193       queryRequestedItem
194
195       queryRequestedItem(Reference to named parameters hash of RequestedItem
196       fields and exact values)
197
198       Example:
199
200         my $requestedItems = $SN->queryRequestedItem({'number' => 'SOME_RI_NUMBER'});
201
202       Query for RequestedItems matching specified criteria.  Reference to
203       array of hashes of all matching RequestedItem, undef on failure or if
204       no records found.
205
206       queryRequest
207
208       queryRequest(Reference to named parameters hash of Request fields and
209       exact values)
210
211       Example:
212
213         my $requests = $SN->queryRequest({'number' => 'SOME_REQUEST_NUMBER'});
214
215       Query for Requests matching specified criteria.  Reference to array of
216       hashes of all matching Request, undef on failure or if no records
217       found.
218
219   Task
220       createTask
221
222       createTask(optional paramaters)
223
224       Example:
225
226         $number = $SN->createTask({"short_description" => "this is the short description"});
227
228       Create a task record.  Returns an task number upon success. On failure
229       returns undef.
230
231       closeTask
232
233       closeTask(task number, optional work effort in seconds)
234
235       Example:
236
237         my $ret = $SN->closeTask($number);
238         my $ret = $SN->closeTask($number, $seconds);
239
240       Close a ServiceNow Task and optionally specify work effort.  Returns
241       true on success, undef on failure.
242
243       reopenTask
244
245       reopenTask(task number)
246
247       Example:
248
249         my $ret = $SN->reopenTask('TASK99999');
250
251       Reopen a closed ServiceNow Task.  Returns true on success, undef on
252       failure.
253
254       reassignTask
255
256       reassignTask(task number, assignment group, optional person it is being
257       assigned to)
258
259       Example:
260
261         my $ret = $SN->reassignTask('TASK99999', 'SOME_GROUP');
262         my $ret = $SN->reassignTask('TASK99999', 'SOME_GROUP', 'username');
263
264       Reassign a ServiceNow Task to a new assignment_group. (and optionally
265       specify an assigned_to) Returns true on success, undef on failure.
266
267       updateTask
268
269       updateTask(task number, reference to named parameters hash of Task
270       fields and values)
271
272       Example:
273
274         my $ret = $SN->updateTask($number, {$field => $value});
275
276       Update a ServiceNow Task.  Returns true on success, undef on failure.
277
278       queryTask
279
280       queryTask(reference to named parameters hash of Task fields and exact
281       values )
282
283       Example:
284
285          my @tasks = $SN->queryTask({'number' => $number});
286          foreach my $task (@tasks) {
287             print "Incident number: $task->{'number'}\n";
288             print "Assignent Group: $task->{'assignment_group'}\n";
289             print "Opened by:       $task->{'opened_by'}\n";
290             print "SD:       $task->{'short_description'}\n";
291             print "TW:       $task->{'time_worked'}\n";
292             print "\n"
293          }
294
295       Query for Tasks matching specified criteria.  Array of hashes of all
296       matching Tasks, undef on failure or if no records found.
297
298   Journal
299       queryJournal
300
301       queryJournal(Incident/Ticket/Task number, optional journal field name )
302
303       Query for journals entries for the specified incident, ticket or task.
304       Return array of hashes of all matching Journals, undef on failure or if
305       no records found.  There will be one hash per per journal entry,
306       'value' will contain the journal entry string, 'element' will be the
307       name of the field (e.g. 'comments', 'work_notes', etc.)
308
309       appendJournal
310
311       appendJournal(Incident/Ticket/Task number, field name, journal text)
312
313       Example:
314
315         my $ret =  $SN->appendJournal('INC99999', 'comments' "some comment text");
316
317       Append a journal entry to the specified journal field of an incident,
318       ticket, or task.  Returns true on success, undef on failure.
319
320   Approval
321       queryApproval
322
323       queryApproval(reference to named parameters hash of approval fields and
324       exact values)
325
326       Example:
327
328         my @approvals = $SN->queryApproval({'approver' => 'username'});
329
330       Query for approvals Return array of hashes of all matching approvals,
331       undef on failure or if no records found.
332
333       approve
334
335       approve(sys_id of the approval,approval state,optional comment text)
336
337       Example:
338
339         my $ret = $SN->approve($sys_id, 'Approved');
340         my $ret = $SN->approve($sys_id, 'Rejected', "Please do something else");
341
342       Approve/reject a ServiceNow approval request and optionally provide a
343       comment.  Returns the sys_id on success, undef on failure.
344
345   Dictionary
346       queryFields
347
348       queryFields(table, optional boolean)
349
350       Example:
351
352          my @fields = $SN->queryFields('incident');
353
354       List all the fields of an Incident, Request, RequestedItem or Task.
355       Returns a reference to a hash of fields in the specified table type.
356       The hash key is the field name, and the hash value is a hash reference
357       to attributes about the field: 'mandatory', 'hint', 'label',
358       'reference' and 'choice'.  Returns undef on failure. If getchoices is
359       true then 'choices' is a reference to a hash containing individual
360       choices, keyed by choice value and containing choice 'label' and
361       'hint'.
362
363
364
365perl v5.32.0                      2020-07-28                     ServiceNow(3)