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

EXCEPTIONS

273       When an error occurs, this module will throw exceptions.  I recommend
274       using Error.pm's try{} mechanism to catch them, but you may also use
275       simple eval{}.  The former will give you flexibility to catch just the
276       exceptions you want.
277
278       Please see RT::Client::REST::Exception for the full listing and
279       description of all the exceptions.
280

LIMITATIONS

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

DEPENDENCIES

289       The following modules are required:
290
291       · Error
292
293       · Exception::Class
294
295       · LWP
296
297       · HTTP::Cookies
298
299       · HTTP::Request::Common
300

SEE ALSO

302       LWP::UserAgent, RT::Client::REST::Exception
303

BUGS

305       Most likely.  Please report.
306

VARIOUS NOTES

308       RT::Client::REST does not (at the moment, see TODO file) retrieve forms
309       from RT server, which is either good or bad, depending how you look at
310       it.
311

AUTHORS

313       Original /usr/bin/rt was written by Abhijit Menon-Sen <ams@wiw.org>.
314       rt was later converted to this module by Dmitri Tikhonov
315       <dtikhonov@yahoo.com>.  In January of 2008, Damien "dams" Krotkine
316       <dams@cpan.org> joined as the project's co-maintainer. JLMARTIN has
317       become co-maintainer as of March 2010.  SRVSH became a co-maintainer in
318       November 2015.
319

AUTHORS

321       ·   Abhijit Menon-Sen <ams@wiw.org>
322
323       ·   Dmitri Tikhonov <dtikhonov@yahoo.com>
324
325       ·   Damien "dams" Krotkine <dams@cpan.org>
326
327       ·   Dean Hamstead <dean@bytefoundry.com.au>
328
329       ·   Miquel Ruiz <mruiz@cpan.org>
330
331       ·   JLMARTIN
332
333       ·   SRVSH
334
336       This software is copyright (c) 2018 by Dmitri Tikhonov.
337
338       This is free software; you can redistribute it and/or modify it under
339       the same terms as the Perl 5 programming language system itself.
340
341
342
343perl v5.28.1                      2018-12-24               RT::Client::REST(3)
Impressum