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.60
10

SYNOPSIS

12         use Error qw(:try);
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         } catch Exception::Class::Base with {
23           die "problem logging in: ", shift->message;
24         };
25
26         try {
27           # Get ticket #10
28           $ticket = $rt->show(type => 'ticket', id => 10);
29         } catch RT::Client::REST::UnauthorizedActionException with {
30           print "You are not authorized to view ticket #10\n";
31         } catch RT::Client::REST::Exception with {
32           # something went wrong.
33         };
34

DESCRIPTION

36       RT::Client::REST is /usr/bin/rt converted to a Perl module.  I needed
37       to implement some RT interactions from my application, but did not feel
38       that invoking a shell command is appropriate.  Thus, I took rt tool,
39       written by Abhijit Menon-Sen, and converted it to an object-oriented
40       Perl module.
41

USAGE NOTES

43       This API mimics that of 'rt'.  For a more OO-style APIs, please use
44       RT::Client::REST::Object-derived classes: RT::Client::REST::Ticket and
45       RT::Client::REST::User.  not implemented yet).
46

METHODS

48       new ()
49           The constructor can take these options (note that these can also be
50           called as their own methods):
51
52           server
53             server is a URI pointing to your RT installation.
54
55             If you have already authenticated against RT in some other part
56             of your program, you can use _cookie parameter to supply an
57             object of type HTTP::Cookies to use for credentials information.
58
59           timeout
60             timeout is the number of seconds HTTP client will wait for the
61             server to respond.  Defaults to LWP::UserAgent's default timeout,
62             which is 180 seconds (please check LWP::UserAgent's documentation
63             for accurate timeout information).
64
65           basic_auth_cb
66             This callback is to provide the HTTP client (based on
67             LWP::UserAgent) with username and password for basic
68             authentication.  It takes the same arguments as
69             "get_basic_credentials()" of LWP::UserAgent and returns username
70             and password:
71
72               $rt->basic_auth_cb( sub {
73                 my ($realm, $uri, $proxy) = @_;
74                 # do some evil things
75                 return ($username, $password);
76               }
77
78           user_agent_args
79             A hashref which will be passed to the user agent's constructor
80             for maximum flexibility.
81
82           user_agent
83             Accessor to the user_agent object.
84
85           logger
86             A logger object.  It should be able to debug(), info(), warn()
87             and error().  It is not widely used in the code (yet), and so it
88             is mostly useful for development.
89
90             Something like this will get you started:
91
92               use Log::Dispatch;
93               my $log = Log::Dispatch->new(
94                 outputs => [ [ 'Screen', min_level => 'debug' ] ],
95               );
96               my $rt = RT::Client::REST->new(
97                 server => ... etc ...
98                 logger => $log
99               );
100
101           verbose_errors
102             On user-agent errors, report some more information about what is
103             going wrong. Defaults are pretty laconic about the "Malformed RT
104             response".
105
106       login (username => 'root', password => 'password') =item login
107       (my_userfield => 'root', my_passfield => 'password')
108           Log in to RT.  Throws an exception on error.
109
110           Usually, if the other side uses basic HTTP authentication, you do
111           not have to log in, but rather provide HTTP username and password
112           instead.  See basic_auth_cb above.
113
114       show (type => $type, id => $id)
115           Return a reference to a hash with key-value pair specifying object
116           $id of type $type. The keys are the names of RT's fields. Keys for
117           custom fields are in the form of "CF.{CUST_FIELD_NAME}".
118
119       edit (type => $type, id => $id, set => { status => 1 })
120           Set fields specified in parameter set in object $id of type $type.
121
122       create (type => $type, set => \%params, text => $text)
123           Create a new object of type $type and set initial parameters to
124           %params.  For a ticket object, 'text' parameter can be supplied to
125           set the initial text of the ticket.  Returns numeric ID of the new
126           object.  If numeric ID cannot be parsed from the response,
127           RT::Client::REST::MalformedRTResponseException is thrown.
128
129       search (type => $type, query => $query, %opts)
130           Search for object of type $type by using query $query.  For
131           example:
132
133             # Find all stalled tickets
134             my @ids = $rt->search(
135               type => 'ticket',
136               query => "Status = 'stalled'",
137             );
138
139           %opts is a list of key-value pairs:
140
141           orderby
142               The value is the name of the field you want to sort by.  Plus
143               or minus sign in front of it signifies ascending order (plus)
144               or descending order (minus).  For example:
145
146                 # Get all stalled tickets in reverse order:
147                 my @ids = $rt->search(
148                   type => 'ticket',
149                   query => "Status = 'stalled'",
150                   orderby => '-id',
151                 );
152
153           "search" returns the list of numeric IDs of objects that matched
154           your query.  You can then use these to retrieve object information
155           using "show()" method:
156
157             my @ids = $rt->search(
158               type => 'ticket',
159               query => "Status = 'stalled'",
160             );
161             for my $id (@ids) {
162               my ($ticket) = $rt->show(type => 'ticket', id => $id);
163               print "Subject: ", $ticket->{Subject}, "\n";
164             }
165
166       comment (ticket_id => $id, message => $message, %opts)
167           Comment on a ticket with ID $id.  Optionally takes arguments cc and
168           bcc which are references to lists of e-mail addresses and
169           attachments which is a list of filenames to be attached to the
170           ticket.
171
172             $rt->comment(
173               ticket_id   => 5,
174               message     => "Wild thing, you make my heart sing",
175               cc          => [qw(dmitri@localhost some@otherdude.com)],
176             );
177
178       correspond (ticket_id => $id, message => $message, %opts)
179           Add correspondence to ticket ID $id.  Takes optional cc, bcc, and
180           attachments parameters (see "comment" above).
181
182       get_attachment_ids (id => $id)
183           Get a list of numeric attachment IDs associated with ticket $id.
184
185       get_attachments_metadata (id => $id)
186           Get a list of the metadata related to every attachment of the
187           ticket <$id> Every member of the list is a hashref with the shape:
188
189             {
190               id       => $attachment_id,
191               Filename => $attachment_filename,
192               Type     => $attachment_type,
193               Size     => $attachment_size,
194             }
195
196       get_attachment (parent_id => $parent_id, id => $id, undecoded => $bool)
197           Returns reference to a hash with key-value pair describing
198           attachment $id of ticket $parent_id.  (parent_id because -- who
199           knows? -- maybe attachments won't be just for tickets anymore in
200           the future).
201
202           If the option undecoded is set to a true value, the attachment will
203           be returned verbatim and undecoded (this is probably what you want
204           with images and binary data).
205
206       get_links (type => $type, id => $id)
207           Get link information for object of type $type whose id is $id.  If
208           type is not specified, 'ticket' is used.
209
210       get_transaction_ids (parent_id => $id, %opts)
211           Get a list of numeric IDs associated with parent ID $id.  %opts
212           have the following options:
213
214           type
215             Type of the object transactions are associated with.  Defaults to
216             "ticket" (I do not think server-side supports anything else).
217             This is designed with the eye on the future, as transactions are
218             not just for tickets, but for other objects as well.
219
220           transaction_type
221             If not specified, IDs of all transactions are returned.  If set
222             to a scalar, only transactions of that type are returned.  If you
223             want to specify more than one type, pass an array reference.
224
225             Transactions may be of the following types (case-sensitive):
226
227             AddLink
228             AddWatcher
229             Comment
230             Correspond
231             Create
232             CustomField
233             DeleteLink
234             DelWatcher
235             EmailRecord
236             Give
237             Set
238             Status
239             Steal
240             Take
241             Told
242       get_transaction (parent_id => $id, id => $id, %opts)
243           Get a hashref representation of transaction $id associated with
244           parent object $id.  You can optionally specify parent object type
245           in %opts (defaults to 'ticket').
246
247       merge_tickets (src => $id1, dst => $id2)
248           Merge ticket $id1 into ticket $id2.
249
250       link_tickets (src => $id1, dst => $id2, link_type => $type)
251           Create a link between two tickets.  A link type can be one of the
252           following:
253
254           • DependsOn
255
256           • DependedOnBy
257
258           • RefersTo
259
260           • ReferredToBy
261
262           • HasMember
263
264           • MemberOf
265
266       unlink_tickets (src => $id1, dst => $id2, link_type => $type)
267           Remove a link between two tickets (see link_tickets())
268
269       take (id => $id)
270           Take ticket $id.  This will throw
271           "RT::Client::REST::AlreadyTicketOwnerException" if you are already
272           the ticket owner.
273
274       untake (id => $id)
275           Untake ticket $id.  This will throw
276           "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
277           already the ticket owner.
278
279       steal (id => $id)
280           Steal ticket $id.  This will throw
281           "RT::Client::REST::AlreadyTicketOwnerException" if you are already
282           the ticket owner.
283

EXCEPTIONS

285       When an error occurs, this module will throw exceptions.  I recommend
286       using Error.pm's try{} mechanism to catch them, but you may also use
287       simple eval{}.  The former will give you flexibility to catch just the
288       exceptions you want.
289
290       Please see RT::Client::REST::Exception for the full listing and
291       description of all the exceptions.
292

LIMITATIONS

294       Beginning with version 0.14, methods "edit()" and "show()" only support
295       operating on a single object.  This is a conscious departure from
296       semantics offered by the original tool, as I would like to have a
297       precise behavior for exceptions.  If you want to operate on a whole
298       bunch of objects, please use a loop.
299

DEPENDENCIES

301       The following modules are required:
302
303       • Error
304
305       • Exception::Class
306
307       • LWP
308
309       • HTTP::Cookies
310
311       • HTTP::Request::Common
312

SEE ALSO

314       LWP::UserAgent, RT::Client::REST::Exception
315

BUGS

317       Most likely.  Please report.
318

VARIOUS NOTES

320       RT::Client::REST does not (at the moment, see TODO file) retrieve forms
321       from RT server, which is either good or bad, depending how you look at
322       it.
323

AUTHOR

325       Dmitri Tikhonov
326
328       This software is copyright (c) 2020, 2018 by Dmitri Tikhonov.
329
330       This is free software; you can redistribute it and/or modify it under
331       the same terms as the Perl 5 programming language system itself.
332

CONTRIBUTORS

334       •   Abhijit Menon-Sen <ams@wiw.org>
335
336       •   belg4mit <belg4mit>
337
338       •   bobtfish <bobtfish@bobtfish.net>
339
340       •   Byron Ellacott <code@bje.id.au>
341
342       •   Dean Hamstead <djzort@cpan.org>
343
344       •   DJ Stauffer <dj@djstauffer.com>
345
346       •   dkrotkine <dkrotkine@gmail.com>
347
348       •   Dmitri Tikhonov <dmitri@cpan.org>
349
350       •   Marco Pessotto <melmothx@gmail.com>
351
352       •   pplusdomain <pplusdomain@gmail.com>
353
354       •   Sarvesh D <sarveshd@openmailbox.org>
355
356       •   Søren Lund <soren@lund.org>
357
358       •   Tom Harrison <tomh@apnic.net>
359
360
361
362perl v5.34.0                      2021-07-22               RT::Client::REST(3)
Impressum