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.57
10
12 use Error qw(:try);
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 } catch Exception::Class::Base with {
23 die "problem logging in: ", shift->message;
24 };
25 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
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
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
48 new ()
49 The constructor can take these options (note that these can also be
50 called as their own methods):
51 server
53 server is a URI pointing to your RT installation.
54 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 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 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 $rt->basic_auth_cb( sub {
73 my ($realm, $uri, $proxy) = @_;
74 # do some evil things
75 return ($username, $password);
76 }
77 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 Something like this will get you started:
84 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 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 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 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 edit (type => $type, id => $id, set => { status => 1 })
108 Set fields specified in parameter set in object $id of type $type.
109 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 search (type => $type, query => $query, %opts)
118 Search for object of type $type by using query $query. For
119 example:
120 # Find all stalled tickets
122 my @ids = $rt->search(
123 type => 'ticket',
124 query => "Status = 'stalled'",
125 );
126 %opts is a list of key-value pairs:
128 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 # Get all stalled tickets in reverse order:
135 my @ids = $rt->search(
136 type => 'ticket',
137 query => "Status = 'stalled'",
138 orderby => '-id',
139 );
140 "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 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 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 $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 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 get_attachment_ids (id => $id)
171 Get a list of numeric attachment IDs associated with ticket $id.
172 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 {
178 id => $attachment_id,
179 Filename => $attachment_filename,
180 Type => $attachment_type,
181 Size => $attachment_size,
182 }
183 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 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 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 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 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 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 Transactions may be of the following types (case-sensitive):
214 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 merge_tickets (src => $id1, dst => $id2)
236 Merge ticket $id1 into ticket $id2.
237 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 · DependsOn
243 · DependedOnBy
245 · RefersTo
247 · ReferredToBy
249 · HasMember
251 · MemberOf
253 unlink_tickets (src => $id1, dst => $id2, link_type => $type)
255 Remove a link between two tickets (see link_tickets())
256 take (id => $id)
258 Take ticket $id. This will throw
259 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
260 the ticket owner.
261 untake (id => $id)
263 Untake ticket $id. This will throw
264 "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
265 already the ticket owner.
266 steal (id => $id)
268 Steal ticket $id. This will throw
269 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
270 the ticket owner.
271
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 Please see RT::Client::REST::Exception for the full listing and
279 description of all the exceptions.
280
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
289 The following modules are required:
290 · Error
292 · Exception::Class
294 · LWP
296 · HTTP::Cookies
298 · HTTP::Request::Common
300
302 LWP::UserAgent, RT::Client::REST::Exception
303
305 Most likely. Please report.
306
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
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
321 · Abhijit Menon-Sen <ams@wiw.org>
322 · Dmitri Tikhonov <dtikhonov@yahoo.com>
324 · Damien "dams" Krotkine <dams@cpan.org>
326 · Dean Hamstead <dean@bytefoundry.com.au>
328 · Miquel Ruiz <mruiz@cpan.org>
330 · JLMARTIN
332 · SRVSH
334
336 This software is copyright (c) 2020 by Dmitri Tikhonov.
337 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.
340perl v5.30.2 2020-04-29 RT::Client::REST(3)