GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  RT::CLIENT::REST (3)

.ds Aq ’

NAME

RT::Client::REST -- talk to RT installation using REST protocol.

CONTENTS

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

<B>RT::Client::RESTB> is <B>/usr/bin/rtB> 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 <B>rtB> 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):
<B>serverB> <B>serverB> 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 <B>_cookieB> parameter to supply an object of type <B>HTTP::CookiesB> to use for credentials information.

<B>timeoutB> <B>timeoutB> is the number of seconds HTTP client will wait for the server to respond. Defaults to LWP::UserAgent’s default timeout, which is 180 seconds (please check LWP::UserAgent’s documentation for accurate timeout information).
<B>basic_auth_cbB> 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);
  }



<B>loggerB> A logger object. It should be able to debug(), info(), warn() and error(). It is not widely used in the code (yet), and so it is mostly useful for development.
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 <B>basic_auth_cbB> above.

show (type => $type, id => $id) Return a reference to a hash with key-value pair specifying object $id of type $type. The keys are the names of RT’s fields. Keys for custom fields are in the form of CF.{CUST_FIELD_NAME}.
edit (type => $type, id => $id, set => { status => 1 }) Set fields specified in parameter <B>setB> in object $id of type $type.
create (type => $type, set => \%params, text => $text) Create a new object of type <B>B>$type<B>B> and set initial parameters to <B>B>%params<B>B>. 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, <B>RT::Client::REST::MalformedRTResponseExceptionB> 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:
<B>orderbyB> 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, id => $id);
    print "Subject: ", $ticket->{Subject}, "\n";
  }



comment (ticket_id => $id, message => $message, %opts) Comment on a ticket with ID <B>B>$id<B>B>. Optionally takes arguments <B>ccB> and <B>bccB> which are references to lists of e-mail addresses and <B>attachmentsB> 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 <B>B>$id<B>B>. Takes optional <B>ccB>, <B>bccB>, and <B>attachmentsB> 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, undecoded => $bool) 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).

If the option undecoded is set to a true value, the attachment will be returned verbatim and undecoded (this is probably what you want with images and binary data).

get_links (type => $type, id => $id) Get link information for object of type $type whose id is $id. If type is not specified, ’ticket’ is used.
get_transaction_ids (parent_id => $id, %opts) Get a list of numeric IDs associated with parent ID $id. %opts have the following options:
<B>typeB> 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.
<B>transaction_typeB> 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 <B>B>$id1<B>B> into ticket <B>B>$id2<B>B>.
link_tickets (src => $id1, dst => $id2, link_type => $type) Create a link between two tickets. A link type can be one of the following:
o DependsOn
o DependedOnBy
o RefersTo
o ReferredToBy
o HasMember
o MemberOf
unlink_tickets (src => $id1, dst => $id2, link_type => $type) Remove a link between two tickets (see <B>B>link_tickets()<B>B>)
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 <B>try{}B> mechanism to catch them, but you may also use simple <B>eval{}B>. 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:
o Error
o Exception::Class
o LWP
o HTTP::Cookies
o HTTP::Request::Common

SEE ALSO

LWP::UserAgent, RT::Client::REST::Exception

BUGS

Most likely. Please report.

VARIOUS NOTES

<B>RT::Client::RESTB> 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.50 of <B>RT::Client::RESTB>.

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. SRVSH became a co-maintainer in November 2015.

LICENSE

Perl license.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 RT::CLIENT::REST (3) 2015-12-11

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.