Provided by: librt-client-rest-perl_0.56-1_all bug


       RT::Client::REST - Client for RT using REST API


       version 0.56


         use Error qw(:try);
         use RT::Client::REST;

         my $rt = RT::Client::REST->new(
           server => '',
           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.


       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.


       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).


       new ()
           The constructor can take these options (note that these can also be called as their
           own methods):

             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 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).

             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);

             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.

             Something like this will get you started:

               use Log::Dispatch;
               my $log = Log::Dispatch->new(
                 outputs => [ [ 'Screen', min_level => 'debug' ] ],
               my $rt = RT::Client::REST->new(
                 server => ... etc ...
                 logger => $log

       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 provide 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.
           The keys are the names of RT's fields. Keys for custom fields are in the form of

       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:

               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

                 # 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 $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.

               ticket_id   => 5,
               message     => "Wild thing, you make my heart sing",
               cc          => [qw(dmitri@localhost],

       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_attachments_metadata (id => $id)
           Get a list of the metadata related to every attachment of the ticket <$id> Every
           member of the list is a hashref with the shape:

               id       => $attachment_id,
               Filename => $attachment_filename,
               Type     => $attachment_type,
               Size     => $attachment_size,

       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

             Type of the object transactions are associated with.  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.

             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):

       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.


       When an error occurs, this module will throw exceptions.  I recommend using'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


       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.


       The following modules are required:

       · Error

       · Exception::Class

       · LWP

       · HTTP::Cookies

       · HTTP::Request::Common


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


       Most likely.  Please report.


       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.


       Original /usr/bin/rt was written by Abhijit Menon-Sen <>.  rt was later
       converted to this module by Dmitri Tikhonov <>.  In January of 2008,
       Damien "dams" Krotkine <> joined as the project's co-maintainer. JLMARTIN has
       become co-maintainer as of March 2010.  SRVSH became a co-maintainer in November 2015.


       ·   Abhijit Menon-Sen <>

       ·   Dmitri Tikhonov <>

       ·   Damien "dams" Krotkine <>

       ·   Dean Hamstead <>

       ·   Miquel Ruiz <>

       ·   JLMARTIN

       ·   SRVSH


       This software is copyright (c) 2018 by Dmitri Tikhonov.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.