UseRtTool

bin/rt/ command line tool

$RTHOME/bin/rt is a command line tool that comes with RT. bin/rt can be useful for automating certain RT-related activities: making custom reports, pulling data to feed to other processes, making mass changes to tickets (be careful!), etc. It can both query and update the RT database. bin/rt has its limitations; it cannot deal with custom fields yet (as of January, 2006).

There is no POD (Plain Old Documentation) for the bin/rt tool, but bin/rt has many help pages available by typing bin/rt help.

Telling /bin/rt how to connect

bin/rt talks to your RT web site (not directly to the database) and it needs to know how to connect as if it were a user using a web browser. You can provide connection information either via environment variables or via a configuration file. Define RTUSER to be the RT user name and RTSERVER to be the base URL of your RT web site. E.g.:

export RTUSER=kevin
export RTSERVER=http://127.0.0.1/rt

(syntax is for Bourne-type UNIX shells).

Or create /.rtrc in your home directory and place lines in it like this:

server http://your.rt.server/your_rt_url_path
user   YOUR_RT_USERNAME
passwd YOUR_RT_PASSWORD

By default, bin/rt assumes a server of http://localhost/rt and the same user name as the currently logged-in operating system user.

The user defined above must be a privileged user in your RT instance, i.e. a user who can be granted rights and who has a password. If you don't specify a user, then the operating system user who executes the bin/rt command is used; in this case, the operating system user must also be defined as a privileged user in RT, and the /unix login/ field for that user should be set to the name of the operating system user also. For example, you could have an operating system user named /rt/ and an RT user named /rt/ whose /unix login/ is also /rt/.

Remember that any queries and modifications you perform with the bin/rt command are limited by the permissions of the RT user identity used.

If your web server authenticates in addition to RT itself, place the web server authentication in your server URL, e.g.: http://user:pass@server/rt.

Using bin/rt

Until someone feels like updating this wiki page, refer to the usage documentation available by typing bin/rt help.

Examples

• Display all tickets in Queue number 3 where there is no due date and the ticket isn't closed.

bin/rt ls -o -Created -t ticket "Queue = '3' and due = 'Not set'  \
    AND Status != 'resolved' AND Status != 'rejected' "

Custom Fields

It turns out that bin/rt CAN handle custom fields, but like all things RT, you must ask properly!

1. If your Custom Field Name contains spaces use single quotes around it for bin/rt to work. Otherwise if you don't use spaces in your Custom Field Names then single quotes are not necessary.

2. The user (as in "export RTUSER=yourname") must have the ability to update custom fields.

3. You must specify the custom field name EXACTLY as it is shown in "rt show ticket/123".

If you get any of the above wrong, RT will simply ignore the set command with no feedback.

So with this result from an 'rt show ticket/123" command (on any ticket):

CF-TaskType: Project Task

The following create code example works fine:

rt create -t ticket set subject='do a bunch of stuff' set CF-TaskType='Project Task'

I use the above routinely in RT v3.6.3

- Ron (rtmaster@standsure.com) 22-May-2008

And the following create code example works fine, using a Custom Field Name with spaces and single quotes:

rt create -t ticket set subject='do a bunch of stuff' set CF-'Task Type'='Project Task'

- Noopy 06-Oct-2011

Note that you can also use the CF's number (this is a lifesaver when CF are named with accents and/or quotes):

rt create -t ticket set CF-28='Here is a new value'

- TheFreeCat 11-Sept-2012

Notes

• A more complicated but much more flexible alternative to using bin/rt is to write a Perl script using the RT API. See ObjectModel and CliBasics for some preliminaries.

• Query arguments to bin/rt are written in TicketSQL.

• For mass updates, you can do things like this:

bin/rt list -i "Queue = 'testqueue'" | bin/rt edit - set status=resolved

• For complicated updates, you may have to write a script to grab the details of all the relevant tickets, figure out what changes are required, then execute the required 'rt edit' commands to make the changes.

• Certain fields have special constraints. For instance, it is not possible to directly set a ticket owner; the ticket must first be assigned to the modifying user, /then/ to the final desired owner name.