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 ticket #10
    $ticket = $rt->show(type => 'ticket', id => 10);
  } 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.

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. More work on this module will be performed in the future as I get a better grip of this whole REST business.

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:

• 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, 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)

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.

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

RT::Client::REST::Exception

BUGS

Most likely. Please report.

VERSION

This is version 0.22 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@vonage.com>

LICENSE

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