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.60
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 user_agent_args
79 A hashref which will be passed to the user agent's constructor
80 for maximum flexibility.
81 user_agent
83 Accessor to the user_agent object.
84 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 Something like this will get you started:
91 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 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 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 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 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 edit (type => $type, id => $id, set => { status => 1 })
120 Set fields specified in parameter set in object $id of type $type.
121 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 search (type => $type, query => $query, %opts)
130 Search for object of type $type by using query $query. For
131 example:
132 # Find all stalled tickets
134 my @ids = $rt->search(
135 type => 'ticket',
136 query => "Status = 'stalled'",
137 );
138 %opts is a list of key-value pairs:
140 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 # Get all stalled tickets in reverse order:
147 my @ids = $rt->search(
148 type => 'ticket',
149 query => "Status = 'stalled'",
150 orderby => '-id',
151 );
152 "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 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 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 $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 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 get_attachment_ids (id => $id)
183 Get a list of numeric attachment IDs associated with ticket $id.
184 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 {
190 id => $attachment_id,
191 Filename => $attachment_filename,
192 Type => $attachment_type,
193 Size => $attachment_size,
194 }
195 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 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 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 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 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 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 Transactions may be of the following types (case-sensitive):
226 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 merge_tickets (src => $id1, dst => $id2)
248 Merge ticket $id1 into ticket $id2.
249 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 • DependsOn
255 • DependedOnBy
257 • RefersTo
259 • ReferredToBy
261 • HasMember
263 • MemberOf
265 unlink_tickets (src => $id1, dst => $id2, link_type => $type)
267 Remove a link between two tickets (see link_tickets())
268 take (id => $id)
270 Take ticket $id. This will throw
271 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
272 the ticket owner.
273 untake (id => $id)
275 Untake ticket $id. This will throw
276 "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
277 already the ticket owner.
278 steal (id => $id)
280 Steal ticket $id. This will throw
281 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
282 the ticket owner.
283
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 Please see RT::Client::REST::Exception for the full listing and
291 description of all the exceptions.
292
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
301 The following modules are required:
302 • Error
304 • Exception::Class
306 • LWP
308 • HTTP::Cookies
310 • HTTP::Request::Common
312
314 LWP::UserAgent, RT::Client::REST::Exception
315
317 Most likely. Please report.
318
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
325 Dmitri Tikhonov
326
328 This software is copyright (c) 2020, 2018 by Dmitri Tikhonov.
329 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
334 • Abhijit Menon-Sen <ams@wiw.org>
335 • belg4mit <belg4mit>
337 • bobtfish <bobtfish@bobtfish.net>
339 • Byron Ellacott <code@bje.id.au>
341 • Dean Hamstead <djzort@cpan.org>
343 • DJ Stauffer <dj@djstauffer.com>
345 • dkrotkine <dkrotkine@gmail.com>
347 • Dmitri Tikhonov <dmitri@cpan.org>
349 • Marco Pessotto <melmothx@gmail.com>
351 • pplusdomain <pplusdomain@gmail.com>
353 • Sarvesh D <sarveshd@openmailbox.org>
355 • Søren Lund <soren@lund.org>
357 • Tom Harrison <tomh@apnic.net>
359perl v5.34.0 2022-01-21 RT::Client::REST(3)