1RT::Client::REST(3) User Contributed Perl Documentation RT::Client::REST(3)
2
6 RT::Client::REST - Client for RT using REST API
7
9 version 0.72
10
12 use Try::Tiny;
13 use RT::Client::REST;
14 my $rt = RT::Client::REST->new(
16 server => 'http://example.com/rt',
17 timeout => 30,
18 );
19 try {
21 $rt->login(username => $user, password => $pass);
22 }
23 catch {
24 if ($_->isa('Exception::Class::Base') {
25 die "problem logging in: ", shift->message;
26 }
27 };
28 try {
30 # Get ticket #10
31 $ticket = $rt->show(type => 'ticket', id => 10);
32 }
33 catch {
34 if ($_->isa('RT::Client::REST::UnauthorizedActionException')) {
35 print "You are not authorized to view ticket #10\n";
36 }
37 if ($_->isa('RT::Client::REST::Exception')) {
38 # something went wrong.
39 }
40 };
41
43 RT::Client::REST is /usr/bin/rt converted to a Perl module. I needed
44 to implement some RT interactions from my application, but did not feel
45 that invoking a shell command is appropriate. Thus, I took rt tool,
46 written by Abhijit Menon-Sen, and converted it to an object-oriented
47 Perl module.
48
50 This API mimics that of 'rt'. For a more OO-style APIs, please use
51 RT::Client::REST::Object-derived classes: RT::Client::REST::Ticket and
52 RT::Client::REST::User. not implemented yet).
53
55 new ()
56 The constructor can take these options (note that these can also be
57 called as their own methods):
58 server
60 server is a URI pointing to your RT installation.
61 If you have already authenticated against RT in some other part
63 of your program, you can use _cookie parameter to supply an
64 object of type HTTP::Cookies to use for credentials information.
65 timeout
67 timeout is the number of seconds HTTP client will wait for the
68 server to respond. Defaults to LWP::UserAgent's default timeout,
69 which is 180 seconds (please check LWP::UserAgent's documentation
70 for accurate timeout information).
71 basic_auth_cb
73 This callback is to provide the HTTP client (based on
74 LWP::UserAgent) with username and password for basic
75 authentication. It takes the same arguments as
76 get_basic_credentials() of LWP::UserAgent and returns username
77 and password:
78 $rt->basic_auth_cb( sub {
80 my ($realm, $uri, $proxy) = @_;
81 # do some evil things
82 return ($username, $password);
83 }
84 user_agent_args
86 A hashref which will be passed to the user agent's constructor
87 for maximum flexibility.
88 user_agent
90 Accessor to the user_agent object.
91 logger
93 A logger object. It should be able to debug(), info(), warn()
94 and error(). It is not widely used in the code (yet), and so it
95 is mostly useful for development.
96 Something like this will get you started:
98 use Log::Dispatch;
100 my $log = Log::Dispatch->new(
101 outputs => [ [ 'Screen', min_level => 'debug' ] ],
102 );
103 my $rt = RT::Client::REST->new(
104 server => ... etc ...
105 logger => $log
106 );
107 verbose_errors
109 On user-agent errors, report some more information about what is
110 going wrong. Defaults are pretty laconic about the "Malformed RT
111 response".
112 login (username => 'root', password => 'password') =item login
114 (my_userfield => 'root', my_passfield => 'password')
115 Log in to RT. Throws an exception on error.
116 Usually, if the other side uses basic HTTP authentication, you do
118 not have to log in, but rather provide HTTP username and password
119 instead. See basic_auth_cb above.
120 show (type => $type, id => $id)
122 Return a reference to a hash with key-value pair specifying object
123 $id of type $type. The keys are the names of RT's fields. Keys for
124 custom fields are in the form of "CF.{CUST_FIELD_NAME}".
125 edit (type => $type, id => $id, set => { status => 1 })
127 Set fields specified in parameter set in object $id of type $type.
128 create (type => $type, set => \%params, text => $text)
130 Create a new object of type $type and set initial parameters to
131 %params. For a ticket object, 'text' parameter can be supplied to
132 set the initial text of the ticket. Returns numeric ID of the new
133 object. If numeric ID cannot be parsed from the response,
134 RT::Client::REST::MalformedRTResponseException is thrown.
135 search (type => $type, query => $query, format => $format, %opts)
137 Search for object of type $type by using query $query. For
138 example:
139 # Find all stalled tickets
141 my @ids = $rt->search(
142 type => 'ticket',
143 query => "Status = 'stalled'",
144 );
145 %opts is a list of key-value pairs:
147 orderby
149 The value is the name of the field you want to sort by. Plus
150 or minus sign in front of it signifies ascending order (plus)
151 or descending order (minus). For example:
152 # Get all stalled tickets in reverse order:
154 my @ids = $rt->search(
155 type => 'ticket',
156 query => "Status = 'stalled'",
157 orderby => '-id',
158 );
159 By default, "search" returns the list of numeric IDs of objects
161 that matched your query. You can then use these to retrieve object
162 information using show() method:
163 my @ids = $rt->search(
165 type => 'ticket',
166 query => "Status = 'stalled'",
167 );
168 for my $id (@ids) {
169 my ($ticket) = $rt->show(type => 'ticket', id => $id);
170 say "Subject: ", $ticket->{Subject}
171 }
172 "search" can return a list of lists of ID and Subject when asked
174 for format 's'.
175 my @results = $rt->search(
177 type => 'ticket',
178 query => "Status = 'stalled'",
179 format => 's',
180 );
181 for my $result (@results) {
182 say "ID: $result[0], Subject: $result[1]"
183 }
184 comment (ticket_id => $id, message => $message, %opts)
186 Comment on a ticket with ID $id.
187 Optionally takes arguments:
189 cc and bcc
191 References to lists of e-mail addresses
192 attachments
194 A list of filenames to be attached to the ticket
195 html
197 When true, indicates to RT that the message is html
198 $rt->comment(
200 ticket_id => 5,
201 message => "Wild thing, you make my heart sing",
202 cc => [qw(dmitri@localhost some@otherdude.com)],
203 );
204 $rt->comment(
206 ticket_id => 5,
207 message => "<b>Wild thing</b>, you make my <i>heart sing</i>",
208 html => 1
209 );
210 correspond (ticket_id => $id, message => $message, %opts)
212 Add correspondence to ticket ID $id. Takes optional cc, bcc, and
213 attachments parameters (see "comment" above).
214 get_attachment_ids (id => $id)
216 Get a list of numeric attachment IDs associated with ticket $id.
217 get_attachments_metadata (id => $id)
219 Get a list of the metadata related to every attachment of the
220 ticket <$id> Every member of the list is a hashref with the shape:
221 {
223 id => $attachment_id,
224 Filename => $attachment_filename,
225 Type => $attachment_type,
226 Size => $attachment_size,
227 }
228 get_attachment (parent_id => $parent_id, id => $id, undecoded => $bool)
230 Returns reference to a hash with key-value pair describing
231 attachment $id of ticket $parent_id. (parent_id because -- who
232 knows? -- maybe attachments won't be just for tickets anymore in
233 the future).
234 If the option undecoded is set to a true value, the attachment will
236 be returned verbatim and undecoded (this is probably what you want
237 with images and binary data).
238 get_links (type => $type, id => $id)
240 Get link information for object of type $type whose id is $id. If
241 type is not specified, 'ticket' is used.
242 get_transaction_ids (parent_id => $id, %opts)
244 Get a list of numeric IDs associated with parent ID $id. %opts
245 have the following options:
246 type
248 Type of the object transactions are associated with. Defaults to
249 "ticket" (I do not think server-side supports anything else).
250 This is designed with the eye on the future, as transactions are
251 not just for tickets, but for other objects as well.
252 transaction_type
254 If not specified, IDs of all transactions are returned. If set
255 to a scalar, only transactions of that type are returned. If you
256 want to specify more than one type, pass an array reference.
257 Transactions may be of the following types (case-sensitive):
259 AddLink
261 AddWatcher
262 Comment
263 Correspond
264 Create
265 CustomField
266 DeleteLink
267 DelWatcher
268 EmailRecord
269 Give
270 Set
271 Status
272 Steal
273 Take
274 Told
275 get_transaction (parent_id => $id, id => $id, %opts)
276 Get a hashref representation of transaction $id associated with
277 parent object $id. You can optionally specify parent object type
278 in %opts (defaults to 'ticket').
279 merge_tickets (src => $id1, dst => $id2)
281 Merge ticket $id1 into ticket $id2.
282 link_tickets (src => $id1, dst => $id2, link_type => $type)
284 Create a link between two tickets. A link type can be one of the
285 following:
286 • DependsOn
288 • DependedOnBy
290 • RefersTo
292 • ReferredToBy
294 • HasMember
296 • MemberOf
298 unlink_tickets (src => $id1, dst => $id2, link_type => $type)
300 Remove a link between two tickets (see link_tickets())
301 take (id => $id)
303 Take ticket $id. This will throw
304 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
305 the ticket owner.
306 untake (id => $id)
308 Untake ticket $id. This will throw
309 "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
310 already the ticket owner.
311 steal (id => $id)
313 Steal ticket $id. This will throw
314 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
315 the ticket owner.
316
318 When an error occurs, this module will throw exceptions. I recommend
319 using Try::Tiny or Syntax::Keyword::Try try{} mechanism to catch them,
320 but you may also use simple eval{}.
321 Please see RT::Client::REST::Exception for the full listing and
323 description of all the exceptions.
324
326 Beginning with version 0.14, methods edit() and show() only support
327 operating on a single object. This is a conscious departure from
328 semantics offered by the original tool, as I would like to have a
329 precise behavior for exceptions. If you want to operate on a whole
330 bunch of objects, please use a loop.
331
333 The following modules are required:
334 • Exception::Class
336 • LWP
338 • HTTP::Cookies
340 • HTTP::Request::Common
342
344 LWP::UserAgent, RT::Client::REST::Exception
345
347 Most likely. Please report.
348
350 RT::Client::REST does not (at the moment, see TODO file) retrieve forms
351 from RT server, which is either good or bad, depending how you look at
352 it.
353
355 Dean Hamstead <dean@fragfest.com.au>
356
358 This software is copyright (c) 2023, 2020 by Dmitri Tikhonov.
359 This is free software; you can redistribute it and/or modify it under
361 the same terms as the Perl 5 programming language system itself.
362
364 • Abhijit Menon-Sen <ams@wiw.org>
365 • belg4mit <belg4mit>
367 • bobtfish <bobtfish@bobtfish.net>
369 • Byron Ellacott <code@bje.id.au>
371 • Dean Hamstead <djzort@cpan.org>
373 • DJ Stauffer <dj@djstauffer.com>
375 • dkrotkine <dkrotkine@gmail.com>
377 • Dmitri Tikhonov <dmitri@cpan.org>
379 • Marco Pessotto <melmothx@gmail.com>
381 • pplusdomain <pplusdomain@gmail.com>
383 • Sarvesh D <sarveshd@openmailbox.org>
385 • Søren Lund <soren@lund.org>
387 • Tom Harrison <tomh@apnic.net>
389perl v5.36.0 2023-02-28 RT::Client::REST(3)