1RT::Client::REST(3)   User Contributed Perl Documentation  RT::Client::REST(3)
2
3
4

NAME

6       RT::Client::REST - Client for RT using REST API
7

VERSION

9       version 0.72
10

SYNOPSIS

12         use Try::Tiny;
13         use RT::Client::REST;
14
15         my $rt = RT::Client::REST->new(
16           server => 'http://example.com/rt',
17           timeout => 30,
18         );
19
20         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
29         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

DESCRIPTION

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

USAGE NOTES

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

METHODS

55       new ()
56           The constructor can take these options (note that these can also be
57           called as their own methods):
58
59           server
60             server is a URI pointing to your RT installation.
61
62             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
66           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
72           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
79               $rt->basic_auth_cb( sub {
80                 my ($realm, $uri, $proxy) = @_;
81                 # do some evil things
82                 return ($username, $password);
83               }
84
85           user_agent_args
86             A hashref which will be passed to the user agent's constructor
87             for maximum flexibility.
88
89           user_agent
90             Accessor to the user_agent object.
91
92           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
97             Something like this will get you started:
98
99               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
108           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
113       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
117           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
121       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
126       edit (type => $type, id => $id, set => { status => 1 })
127           Set fields specified in parameter set in object $id of type $type.
128
129       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
136       search (type => $type, query => $query, format => $format, %opts)
137           Search for object of type $type by using query $query.  For
138           example:
139
140             # Find all stalled tickets
141             my @ids = $rt->search(
142               type => 'ticket',
143               query => "Status = 'stalled'",
144             );
145
146           %opts is a list of key-value pairs:
147
148           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
153                 # Get all stalled tickets in reverse order:
154                 my @ids = $rt->search(
155                   type => 'ticket',
156                   query => "Status = 'stalled'",
157                   orderby => '-id',
158                 );
159
160           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
164             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
173           "search" can return a list of lists of ID and Subject when asked
174           for format 's'.
175
176             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
185       comment (ticket_id => $id, message => $message, %opts)
186           Comment on a ticket with ID $id.
187
188           Optionally takes arguments:
189
190           cc and bcc
191             References to lists of e-mail addresses
192
193           attachments
194             A list of filenames to be attached to the ticket
195
196           html
197             When true, indicates to RT that the message is html
198
199             $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
205             $rt->comment(
206               ticket_id   => 5,
207               message     => "<b>Wild thing</b>, you make my <i>heart sing</i>",
208               html        => 1
209             );
210
211       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
215       get_attachment_ids (id => $id)
216           Get a list of numeric attachment IDs associated with ticket $id.
217
218       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
222             {
223               id       => $attachment_id,
224               Filename => $attachment_filename,
225               Type     => $attachment_type,
226               Size     => $attachment_size,
227             }
228
229       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
235           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
239       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
243       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
247           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
253           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
258             Transactions may be of the following types (case-sensitive):
259
260             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
280       merge_tickets (src => $id1, dst => $id2)
281           Merge ticket $id1 into ticket $id2.
282
283       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
287           • DependsOn
288
289           • DependedOnBy
290
291           • RefersTo
292
293           • ReferredToBy
294
295           • HasMember
296
297           • MemberOf
298
299       unlink_tickets (src => $id1, dst => $id2, link_type => $type)
300           Remove a link between two tickets (see link_tickets())
301
302       take (id => $id)
303           Take ticket $id.  This will throw
304           "RT::Client::REST::AlreadyTicketOwnerException" if you are already
305           the ticket owner.
306
307       untake (id => $id)
308           Untake ticket $id.  This will throw
309           "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
310           already the ticket owner.
311
312       steal (id => $id)
313           Steal ticket $id.  This will throw
314           "RT::Client::REST::AlreadyTicketOwnerException" if you are already
315           the ticket owner.
316

EXCEPTIONS

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
322       Please see RT::Client::REST::Exception for the full listing and
323       description of all the exceptions.
324

LIMITATIONS

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

DEPENDENCIES

333       The following modules are required:
334
335       • Exception::Class
336
337       • LWP
338
339       • HTTP::Cookies
340
341       • HTTP::Request::Common
342

SEE ALSO

344       LWP::UserAgent, RT::Client::REST::Exception
345

BUGS

347       Most likely.  Please report.
348

VARIOUS NOTES

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

AUTHOR

355       Dean Hamstead <dean@fragfest.com.au>
356
358       This software is copyright (c) 2023, 2020 by Dmitri Tikhonov.
359
360       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

CONTRIBUTORS

364       •   Abhijit Menon-Sen <ams@wiw.org>
365
366       •   belg4mit <belg4mit>
367
368       •   bobtfish <bobtfish@bobtfish.net>
369
370       •   Byron Ellacott <code@bje.id.au>
371
372       •   Dean Hamstead <djzort@cpan.org>
373
374       •   DJ Stauffer <dj@djstauffer.com>
375
376       •   dkrotkine <dkrotkine@gmail.com>
377
378       •   Dmitri Tikhonov <dmitri@cpan.org>
379
380       •   Marco Pessotto <melmothx@gmail.com>
381
382       •   pplusdomain <pplusdomain@gmail.com>
383
384       •   Sarvesh D <sarveshd@openmailbox.org>
385
386       •   Søren Lund <soren@lund.org>
387
388       •   Tom Harrison <tomh@apnic.net>
389
390
391
392perl v5.36.0                      2023-02-28               RT::Client::REST(3)
Impressum