NAME

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

SYNOPSIS

my $rt = RT::Client::REST->new(
  username => $user,
  password => $pass,
  server => 'http://example.com/rt',
);

try {
  # Get tickets 10 through 20
  @tx = $rt->show(type => 'ticket', objects => [10 .. 20]);
} 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.

As of this writing (version 0.06), RT::Client::REST is missing a lot of things that rt has. It does not support attachments, CCs, BCCs, and probably other things. RT::Client::REST does not retrieve forms from RT server, which is either good or bad, depending how you look at it. More work on this module will be performed in the future as I get a better grip of this whole REST business. It also does not have 'list' (or 'search') operation; this will be added in a later version.

METHODS

new ()

The constructor can take these options:

• server is a URI pointing to your RT installation.

• username and password are used to authenticate your request. After an instance of RT::Client::REST is used to issue a successful request, subsequent requests will use a cookie, so the first request is an effect a log in.

• Alternatively, 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.

• All of the above, server, username, password, and cookie can also be used as regular methods after your object is instantiated.

show (type => $type, objects => \@ids)

Get a list of objects of type 4type. One or more IDs should be specified. This returns an array of hashrefs (I don't get "forms", so I just take the third element and return it).

edit (type => $type, objects => \@ids, set => { status => 1 })

For all objects of type $type whose ID is in @ids, set fields as prescribed by the set parameter.

create (type => $type, set => \%params)

Create a new object of type $type and set initial parameters to %params. Returns numeric ID of the new object. If numeric ID cannot be parsed from the response, RT::Client::REST::MalformedRTResponseException is thrown.

comment (ticket_id => $id, message => "This is a comment")

Comment on a ticket with ID $id.

correspond (ticket_id => $id, message => "This is a comment")

Add correspondence to ticket ID $id.

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

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. Here is the hierarchy:

• RT::Client::REST::Exception

  • RT::Client::REST::OddNumberOfArgumentsException

  • RT::Client::REST::InvaildObjectTypeException

  • RT::Client::REST::MalformedRTResponseException

  • RT::Client::REST::InvalidParameterValueException

  • RT::Client::REST::RTException. This exception is virtual; only its subclasses are thrown. This group is used when RT REST interface returns an error message. Exceptions derived from it all have a custom field code which can be used to get RT's numeric error code.

    • RT::Client::REST::ObjectNotFoundException

    • RT::Client::REST::CouldNotCreateObjectException

    • RT::Client::REST::AuthenticationFailureException

    • RT::Client::REST::UnknownRTException

  • RT::Client::REST::HTTPException. This is thrown if anything besides 200 OK code is returned by the underlying HTTP protocol. Custom field code can be used to access the actual HTTP status code.

DEPENDENCIES

The following modules are required:

• Error

• Exception::Class

• LWP

• HTTP::Cookies

• HTTP::Request::Common

BUGS

Most likely. Please report.

TODO

• Add the rest of the features available in /usr/bin/rt.

• Implement /usr/bin/rt using this RT::Client::REST.

VERSION

This is version 0.06 of RT::Client::REST. /usr/bin/rt shipped with RT 3.4.5 is version 0.02, so the logical version continuation is to have one higher.

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@vonage.com>

LICENSE

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