[rt-users] API Documentation

[Mike Friedman]

We're currently running RT 2.0.15 with plans to upgrade to a current
version of RT3 in the near future.  My particular interest is in the perl
API, because I have written a lot of perl scripts that allow us to
integrate RT functionality into some of our other processes.

With RT2, I've been using the primitive CLI in my scripts, mostly because
when I started I didn't even know there was a real perl API to RT.  But a
few months ago, I was told on this list that RT2, as well as RT3, has an
API.  If not now, then at least when we go to RT3, I'd like to start using
the API instead.

My problem is that I'd like some documentation on how to use the API, e.g.
how to create a ticket, update a ticket (change its queue, its status, add
a comment, resolve it, etc.) from perl.  The main benefit over the CLI I'm
using now would be return codes and error messages so that my scripts can
have reliable information about success and failure of particular
functions.

But I was also told on this list that there's no documentation;  that I
should look at the source.  But this can be quite time-consuming.  I've
looked at some of the perl code that comes with RT, so I have an idea of
what the API looks like.  But what I'd really like is what would normally
appear on a man page, e.g, prototype function calls with return values.

If this isn't actually documented, perhaps someone could post sample code
to do the following kinds of things.  (Where RT2 and RT3 differ, I'd
prefer the RT3 version).  I've shown the CLI equivalent that I'm using
now:

   o Create a ticket:
       rt --create --noedit --status=sssss --owner=ooooo --queue=qqqq
          --requestors=rrrrr --subject='sss sss' --source [filename | -]

   o Change a ticket's queue, status, etc.:
       rt --id=nnnnn --queue=qqqqq --status=ssssss

   o Add a comment to a ticket (using a file or STDIN as the source):
       rt --id=nnnnn --comment --noedit --source [filename | -]

   o Search for a ticket with particular contents in the Subject:
       rt --limit-subject='sss sss sss' --summary %id5%created25%subject80

   o Update the set of Requestors for a ticket:
       Currently, I need to retrieve the list of Requestors, subtract
       each Requestor one at a time, then add each new Requestor, one
       at a time (pseudo-code follows):
       $rtout = `rt --id=nnnnn --summary '%requestor200'`;
       ...
       @requestors = split(/\,/,$rtout);
       for ($i = 0; $i <= $#requestors; $i++) {
          system("rt --id=nnnnn --requestors=-$requestors[$i]");
          }
       ...
       Then add new Requestors, one at a time.

You get the idea.  If I could see sample code to do each, or some, of the
above using the API, I could proceed from there.

Thanks.

Mike

------------------------------------------------------------------------------
Mike Friedman                             System and Network Security
mikef at ack.Berkeley.EDU                    2484 Shattuck Avenue
1-510-642-1410                            University of California at Berkeley
http://ack.Berkeley.EDU/~mikef            http://security.berkeley.edu
------------------------------------------------------------------------------