NAME¶
RT::Client::REST -- talk to RT installation using REST protocol.
SYNOPSIS¶
use Error qw(:try);
use RT::Client::REST;
my $rt = RT::Client::REST->new(
server => 'http://example.com/rt',
timeout => 30,
);
try {
$rt->login(username => $user, password => $pass);
} catch Exception::Class::Base with {
die "problem logging in: ", shift->message;
};
try {
# Get ticket #10
$ticket = $rt->show(type => 'ticket', id => 10);
} catch RT::Client::REST::UnauthorizedActionException with {
print "You are not authorized to view ticket #10\n";
} catch RT::Client::REST::Exception with {
# something went wrong.
};
DESCRIPTION¶
RT::Client::REST is
/usr/bin/rt converted to a Perl module. I
needed to implement some RT interactions from my application, but did not feel
that invoking a shell command is appropriate. Thus, I took
rt tool,
written by Abhijit Menon-Sen, and converted it to an object-oriented Perl
module.
USAGE NOTES¶
This API mimics that of 'rt'. For a more OO-style APIs, please use
RT::Client::REST::Object-derived classes: RT::Client::REST::Ticket and
RT::Client::REST::User. not implemented yet).
METHODS¶
- new ()
- The constructor can take these options (note that these can
also be called as their own methods):
- server
- server is a URI pointing to your RT installation.
If you have already authenticated against RT in some other part of your
program, you can use _cookie parameter to supply an object of type
HTTP::Cookies to use for credentials information.
- timeout
- timeout is the number of seconds HTTP client will
wait for the server to respond. Defaults to LWP::UserAgent's default
timeout, which is 300 seconds.
- basic_auth_cb
- This callback is to provide the HTTP client (based on
LWP::UserAgent) with username and password for basic authentication. It
takes the same arguments as "get_basic_credentials()" of
LWP::UserAgent and returns username and password:
$rt->basic_auth_cb( sub {
my ($realm, $uri, $proxy) = @_;
# do some evil things
return ($username, $password);
}
- login (username => 'root', password => 'password')
=item login (my_userfield => 'root', my_passfield => 'password')
- Log in to RT. Throws an exception on error.
Usually, if the other side uses basic HTTP authentication, you do not have
to log in, but rather prodive HTTP username and password instead. See
basic_auth_cb above.
- show (type => $type, id => $id)
- Return a reference to a hash with key-value pair specifying
object $id of type $type.
- edit (type => $type, id => $id, set => { status
=> 1 })
- Set fields specified in parameter set in object $id
of type $type.
- create (type => $type, set => \%params, text =>
$text)
- Create a new object of type $type and
set initial parameters to %params. For a ticket
object, 'text' parameter can be supplied to set the initial text of the
ticket. Returns numeric ID of the new object. If numeric ID cannot be
parsed from the response,
RT::Client::REST::MalformedRTResponseException is thrown.
- search (type => $type, query => $query, %opts)
- Search for object of type $type by using query $query. For
example:
# Find all stalled tickets
my @ids = $rt->search(
type => 'ticket',
query => "Status = 'stalled'",
);
%opts is a list of key-value pairs:
- orderby
- The value is the name of the field you want to sort by.
Plus or minus sign in front of it signifies ascending order (plus) or
descending order (minus). For example:
# Get all stalled tickets in reverse order:
my @ids = $rt->search(
type => 'ticket',
query => "Status = 'stalled'",
orderby => '-id',
);
"search" returns the list of numeric IDs of objects that matched your
query. You can then use these to retrieve object information using
"show()" method:
my @ids = $rt->search(
type => 'ticket',
query => "Status = 'stalled'",
);
for my $id (@ids) {
my ($ticket) = $rt->show(type => 'ticket', ids => [$id]);
print "Subject: ", $t->{Subject}, "\n";
}
- comment (ticket_id => $id, message => $message,
%opts)
- Comment on a ticket with ID $id.
Optionally takes arguments cc and bcc which are references
to lists of e-mail addresses and attachments which is a list of
filenames to be attached to the ticket.
$rt->comment(
ticket_id => 5,
message => "Wild thing, you make my heart sing",
cc => [qw(dmitri@localhost some@otherdude.com)],
);
- correspond (ticket_id => $id, message => $message,
%opts)
- Add correspondence to ticket ID $id.
Takes optional cc, bcc, and attachments parameters
(see "comment" above).
- get_attachment_ids (id => $id)
- Get a list of numeric attachment IDs associated with ticket
$id.
- get_attachment (parent_id => $parent_id, id =>
$id)
- Returns reference to a hash with key-value pair describing
attachment $id of ticket $parent_id. (parent_id because -- who knows? --
maybe attachments won't be just for tickets anymore in the future).
- get_transaction_ids (parent_id => $id, %opts)
- Get a list of numeric IDs associated with parent ID $id.
%opts have the following options:
- type
- Type of the object transactions are associated wtih.
Defaults to "ticket" (I do not think server-side supports
anything else). This is designed with the eye on the future, as
transactions are not just for tickets, but for other objects as well.
- transaction_type
- If not specified, IDs of all transactions are returned. If
set to a scalar, only transactions of that type are returned. If you want
to specify more than one type, pass an array reference.
Transactions may be of the following types (case-sensitive):
- AddLink
- AddWatcher
- Comment
- Correspond
- Create
- CustomField
- DeleteLink
- DelWatcher
- EmailRecord
- Give
- Set
- Status
- Steal
- Take
- Told
- get_transaction (parent_id => $id, id => $id,
%opts)
- Get a hashref representation of transaction $id associated
with parent object $id. You can optionally specify parent object type in
%opts (defaults to 'ticket').
- merge_tickets (src => $id1, dst => $id2)
- Merge ticket $id1 into ticket
$id2.
- link_tickets (src => $id1, dst => $id2, link_type
=> $type)
- Create a link between two tickets. A link type can be one
of the following:
- •
- DependsOn
- •
- DependedOnBy
- •
- RefersTo
- •
- ReferredToBy
- •
- HasMember
- •
- MemberOf
- unlink_tickets (src => $id1, dst => $id2, link_type
=> $type)
- Remove a link between two tickets (see
link_tickets() )
- take (id => $id)
- Take ticket $id. This will throw
"RT::Client::REST::AlreadyTicketOwnerException" if you are
already the ticket owner.
- untake (id => $id)
- Untake ticket $id. This will throw
"RT::Client::REST::AlreadyTicketOwnerException" if Nobody is
already the ticket owner.
- steal (id => $id)
- Steal ticket $id. This will throw
"RT::Client::REST::AlreadyTicketOwnerException" if you are
already the ticket owner.
EXCEPTIONS¶
When an error occurs, this module will throw exceptions. I recommend using
Error.pm's
try{} mechanism to catch them, but you may also use simple
eval{}. The former will give you flexibility to catch just the
exceptions you want.
Please see RT::Client::REST::Exception for the full listing and description of
all the exceptions.
LIMITATIONS¶
Beginning with version 0.14, methods "edit()" and "show()"
only support operating on a single object. This is a conscious departure from
semantics offered by the original tool, as I would like to have a precise
behavior for exceptions. If you want to operate on a whole bunch of objects,
please use a loop.
DEPENDENCIES¶
The following modules are required:
- •
- Error
- •
- Exception::Class
- •
- LWP
- •
- HTTP::Cookies
- •
- HTTP::Request::Common
SEE ALSO¶
LWP::UserAgent, RT::Client::REST::Exception
BUGS¶
Most likely. Please report.
VARIOUS NOTES¶
RT::Client::REST does not (at the moment, see TODO file) retrieve forms
from RT server, which is either good or bad, depending how you look at it.
VERSION¶
This is version 0.40 of
RT::Client::REST.
AUTHORS¶
Original /usr/bin/rt was written by Abhijit Menon-Sen <ams@wiw.org>. rt
was later converted to this module by Dmitri Tikhonov
<dtikhonov@yahoo.com>. In January of 2008, Damien "dams"
Krotkine <dams@cpan.org> joined as the project's co-maintainer. JLMARTIN
has become co-maintainer as of March 2010.
LICENSE¶
Since original rt is licensed under GPL, so is this module.