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
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.:
(syntax is for Bourne-type UNIX shells).
Or create /.rtrc in your home directory and place lines in it like this:
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.
Until someone feels like updating this wiki page, refer to the usage documentation available by typing
- 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' "
It turns out that bin/rt CAN handle custom fields, but like all things RT, you must ask properly!
- 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.
- The user (as in "export RTUSER=yourname") must have the ability to update custom fields.
- 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 (email@example.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
- 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.