SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

MAN page from Mandriva 2011 perl-RT-Client-REST-0.410.0-1mdv2011.0.noarch.rpm

RT::Client::REST

Section: User Contributed Perl Documentation (3)
Updated: 2010-07-06
Index 

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 neededto implement some RT interactions from my application, but did not feel thatinvoking a shell command is appropriate. Thus, I took rt tool, writtenby 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 useRT::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 alsobe called as their own methods):
server
server is a URI pointing to your RT installation.

If you have already authenticated against RT in some otherpart of your program, you can use _cookie parameter to supply an objectof type HTTP::Cookies to use for credentials information.

timeout
timeout is the number of seconds HTTP client will wait for theserver to respond. Defaults to LWP::UserAgent's default timeout, whichis 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 thesame arguments as "get_basic_credentials()" of LWP::UserAgent andreturns username and password:

  $rt->basic_auth_cb( sub {    my ($realm, $uri, $proxy) = @_;    # do some evil things    return ($username, $password);  }
login (username => 'root', password => 'password')
Log in to RT. Throws an exception on error.

Usually, if the other side uses basic HTTP authentication, you do nothave 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 $idof 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 initialtext of the ticket.Returns numeric ID of the new object. If numeric ID cannot be parsed fromthe response, RT::Client::REST::MalformedRTResponseException is thrown.
search (type => $type, query => $query, %opts)
Search for object of type $type by using query $query. Forexample:

  # 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 minussign in front of it signifies ascending order (plus) or descendingorder (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 matchedyour query. You can then use these to retrieve object informationusing "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 listsof e-mail addresses and attachments which is a list of filenames tobe attached to the ticket.

  $rt->comment(    ticket_id   => 5,    message     => "Wild thing, you make my heart sing",    cc          => [qw(dmitri@localhost someAATTotherdude.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. %optshave 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 withthe eye on the future, as transactions are not just for tickets, but forother objects as well.
transaction_type
If not specified, IDs of all transactions are returned. If set to ascalar, only transactions of that type are returned. If you want to specifymore 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 withparent 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 arealready the ticket owner.
untake (id => $id)
Untake ticket $id.This will throw "RT::Client::REST::AlreadyTicketOwnerException" if Nobodyis already the ticket owner.
steal (id => $id)
Steal ticket $id.This will throw "RT::Client::REST::AlreadyTicketOwnerException" if you arealready the ticket owner.
 

EXCEPTIONS

When an error occurs, this module will throw exceptions. I recommendusing Error.pm's try{} mechanism to catch them, but you may also usesimple eval{}. The former will give you flexibility to catch just theexceptions you want.

Please see RT::Client::REST::Exception for the full listing anddescription of all the exceptions. 

LIMITATIONS

Beginning with version 0.14, methods "edit()" and "show()" only supportoperating on a single object. This is a conscious departure from semanticsoffered by the original tool, as I would like to have a precise behaviorfor exceptions. If you want to operate on a whole bunch of objects, pleaseuse 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 fromRT 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 <amsAATTwiw.org>. rtwas later converted to this module by Dmitri Tikhonov <dtikhonovAATTyahoo.com>.In January of 2008, Damien ``dams'' Krotkine <damsAATTcpan.org> joined as theproject's co-maintainer. JLMARTIN has become co-maintainer as of March 2010. 

LICENSE

Since original rt is licensed under GPL, so is this module.


 

Index

NAME
SYNOPSIS
DESCRIPTION
USAGE NOTES
METHODS
EXCEPTIONS
LIMITATIONS
DEPENDENCIES
SEE ALSO
BUGS
VARIOUS NOTES
VERSION
AUTHORS
LICENSE

This document was created byman2html,using the manual pages.