1RT::Client::REST(3) User Contributed Perl Documentation RT::Client::REST(3)
2
6 RT::Client::REST -- talk to RT installation using REST protocol.
7
9 use Error qw(:try);
10 use RT::Client::REST;
11 my $rt = RT::Client::REST->new(
13 server => 'http://example.com/rt',
14 timeout => 30,
15 );
16 try {
18 $rt->login(username => $user, password => $pass);
19 } catch Exception::Class::Base with {
20 die "problem logging in: ", shift->message;
21 };
22 try {
24 # Get ticket #10
25 $ticket = $rt->show(type => 'ticket', id => 10);
26 } catch RT::Client::REST::UnauthorizedActionException with {
27 print "You are not authorized to view ticket #10\n";
28 } catch RT::Client::REST::Exception with {
29 # something went wrong.
30 };
31
33 RT::Client::REST is /usr/bin/rt converted to a Perl module. I needed
34 to implement some RT interactions from my application, but did not feel
35 that invoking a shell command is appropriate. Thus, I took rt tool,
36 written by Abhijit Menon-Sen, and converted it to an object-oriented
37 Perl module.
38
40 This API mimics that of 'rt'. For a more OO-style APIs, please use
41 RT::Client::REST::Object-derived classes: RT::Client::REST::Ticket and
42 RT::Client::REST::User. not implemented yet).
43
45 new ()
46 The constructor can take these options (note that these can also be
47 called as their own methods):
48 server
50 server is a URI pointing to your RT installation.
51 If you have already authenticated against RT in some other part
53 of your program, you can use _cookie parameter to supply an
54 object of type HTTP::Cookies to use for credentials information.
55 timeout
57 timeout is the number of seconds HTTP client will wait for the
58 server to respond. Defaults to LWP::UserAgent's default timeout,
59 which is 300 seconds.
60 basic_auth_cb
62 This callback is to provide the HTTP client (based on
63 LWP::UserAgent) with username and password for basic
64 authentication. It takes the same arguments as
65 "get_basic_credentials()" of LWP::UserAgent and returns username
66 and password:
67 $rt->basic_auth_cb( sub {
69 my ($realm, $uri, $proxy) = @_;
70 # do some evil things
71 return ($username, $password);
72 }
73 login (username => 'root', password => 'password')
75 Log in to RT. Throws an exception on error.
76 Usually, if the other side uses basic HTTP authentication, you do
78 not have to log in, but rather prodive HTTP username and password
79 instead. See basic_auth_cb above.
80 show (type => $type, id => $id)
82 Return a reference to a hash with key-value pair specifying object
83 $id of type $type.
84 edit (type => $type, id => $id, set => { status => 1 })
86 Set fields specified in parameter set in object $id of type $type.
87 create (type => $type, set => \%params, text => $text)
89 Create a new object of type $type and set initial parameters to
90 %params. For a ticket object, 'text' parameter can be supplied to
91 set the initial text of the ticket. Returns numeric ID of the new
92 object. If numeric ID cannot be parsed from the response,
93 RT::Client::REST::MalformedRTResponseException is thrown.
94 search (type => $type, query => $query, %opts)
96 Search for object of type $type by using query $query. For
97 example:
98 # Find all stalled tickets
100 my @ids = $rt->search(
101 type => 'ticket',
102 query => "Status = 'stalled'",
103 );
104 %opts is a list of key-value pairs:
106 orderby
108 The value is the name of the field you want to sort by. Plus
109 or minus sign in front of it signifies ascending order (plus)
110 or descending order (minus). For example:
111 # Get all stalled tickets in reverse order:
113 my @ids = $rt->search(
114 type => 'ticket',
115 query => "Status = 'stalled'",
116 orderby => '-id',
117 );
118 "search" returns the list of numeric IDs of objects that matched
120 your query. You can then use these to retrieve object information
121 using "show()" method:
122 my @ids = $rt->search(
124 type => 'ticket',
125 query => "Status = 'stalled'",
126 );
127 for my $id (@ids) {
128 my ($ticket) = $rt->show(type => 'ticket', ids => [$id]);
129 print "Subject: ", $t->{Subject}, "\n";
130 }
131 comment (ticket_id => $id, message => $message, %opts)
133 Comment on a ticket with ID $id. Optionally takes arguments cc and
134 bcc which are references to lists of e-mail addresses and
135 attachments which is a list of filenames to be attached to the
136 ticket.
137 $rt->comment(
139 ticket_id => 5,
140 message => "Wild thing, you make my heart sing",
141 cc => [qw(dmitri@localhost some@otherdude.com)],
142 );
143 correspond (ticket_id => $id, message => $message, %opts)
145 Add correspondence to ticket ID $id. Takes optional cc, bcc, and
146 attachments parameters (see "comment" above).
147 get_attachment_ids (id => $id)
149 Get a list of numeric attachment IDs associated with ticket $id.
150 get_attachment (parent_id => $parent_id, id => $id)
152 Returns reference to a hash with key-value pair describing
153 attachment $id of ticket $parent_id. (parent_id because -- who
154 knows? -- maybe attachments won't be just for tickets anymore in
155 the future).
156 get_transaction_ids (parent_id => $id, %opts)
158 Get a list of numeric IDs associated with parent ID $id. %opts
159 have the following options:
160 type
162 Type of the object transactions are associated wtih. Defaults to
163 "ticket" (I do not think server-side supports anything else).
164 This is designed with the eye on the future, as transactions are
165 not just for tickets, but for other objects as well.
166 transaction_type
168 If not specified, IDs of all transactions are returned. If set
169 to a scalar, only transactions of that type are returned. If you
170 want to specify more than one type, pass an array reference.
171 Transactions may be of the following types (case-sensitive):
173 AddLink
175 AddWatcher
176 Comment
177 Correspond
178 Create
179 CustomField
180 DeleteLink
181 DelWatcher
182 EmailRecord
183 Give
184 Set
185 Status
186 Steal
187 Take
188 Told
189 get_transaction (parent_id => $id, id => $id, %opts)
190 Get a hashref representation of transaction $id associated with
191 parent object $id. You can optionally specify parent object type
192 in %opts (defaults to 'ticket').
193 merge_tickets (src => $id1, dst => $id2)
195 Merge ticket $id1 into ticket $id2.
196 link_tickets (src => $id1, dst => $id2, link_type => $type)
198 Create a link between two tickets. A link type can be one of the
199 following:
200 · DependsOn
202 · DependedOnBy
204 · RefersTo
206 · ReferredToBy
208 · HasMember
210 · MemberOf
212 unlink_tickets (src => $id1, dst => $id2, link_type => $type)
214 Remove a link between two tickets (see link_tickets())
215 take (id => $id)
217 Take ticket $id. This will throw
218 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
219 the ticket owner.
220 untake (id => $id)
222 Untake ticket $id. This will throw
223 "RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
224 already the ticket owner.
225 steal (id => $id)
227 Steal ticket $id. This will throw
228 "RT::Client::REST::AlreadyTicketOwnerException" if you are already
229 the ticket owner.
230
232 When an error occurs, this module will throw exceptions. I recommend
233 using Error.pm's try{} mechanism to catch them, but you may also use
234 simple eval{}. The former will give you flexibility to catch just the
235 exceptions you want.
236 Please see RT::Client::REST::Exception for the full listing and
238 description of all the exceptions.
239
241 Beginning with version 0.14, methods "edit()" and "show()" only support
242 operating on a single object. This is a conscious departure from
243 semantics offered by the original tool, as I would like to have a
244 precise behavior for exceptions. If you want to operate on a whole
245 bunch of objects, please use a loop.
246
248 The following modules are required:
249 · Error
251 · Exception::Class
253 · LWP
255 · HTTP::Cookies
257 · HTTP::Request::Common
259
261 LWP::UserAgent, RT::Client::REST::Exception
262
264 Most likely. Please report.
265
267 RT::Client::REST does not (at the moment, see TODO file) retrieve forms
268 from RT server, which is either good or bad, depending how you look at
269 it.
270
272 This is version 0.37 of RT::Client::REST.
273
275 Original /usr/bin/rt was written by Abhijit Menon-Sen <ams@wiw.org>.
276 rt was later converted to this module by Dmitri Tikhonov
277 <dtikhonov@yahoo.com>. In January of 2008, Damien "dams" Krotkine
278 <dams@cpan.org> joined as the project's co-maintainer.
279
281 Since original rt is licensed under GPL, so is this module.
282perl v5.12.0 2008-08-16 RT::Client::REST(3)