Request Tracker Wiki - User contributions [en]

InstallationGuides

2025-07-17T12:22:34Z

Jbrandt: /* The best/easiest distribution for RT */

=Picking a Linux Distribution=

RT runs on Arch Linux, Debian, FreeBSD, NetBSD, RHEL, Fedora, Solaris, SuSE, Gentoo, OpenBSD, and more. If you maintain other Linux systems, it's best to stick with the Linux you have the most experience with. If you're just starting and don't have a preference, it's safe to use Linux distributions based on either Debian or Red Hat, where you'll find guides (including Fedora, and Ubuntu). The [[ManualInstallation]] page had details on installation steps.

= Generic Installation Guides =

* [[ManualRequirements]] - software and knowledge you need to install RT.
* [[ManualInstallation]] - general overview of installation process and first time configuring.
* [[DevelopmentInstallation]] - HOWTO setup RT to run from a development directory
* [http://www.sgsosu.net/nmetro/docs.html Installation and Administration Guides] - Request Tracker, Reporting and Asset Tracker

= Platform-Specific Installation Guides =

* Arch Linux
** [https://wiki.archlinux.org/index.php/Request_Tracker Request Tracker (Arch Wiki)]
* CentOS:
** [[CentOS7Install]] (CentOS 7.2.1511 install using Perl RPMs and CPANminus to source CPAN dependencies)
* [[SuSE|SUSE Linux Enterprise (SLE):]]
** [[SLES11InstallGuide]]

= Database Specific Notes =

* [[OracleSetup]]
* RT with [[OracleText]]
* RT with [[PostgreSQLFullText]]
* RT with [[PostgreSQLFullTextTrgm]]

= Web Server Specific Notes =

* [[LighttpdFastCGIGuide]]

= Upgrading =

* [[MigrateToNewServer]]
* [[UpgradingFrom3011To344OnSolaris9]]
* [[Upgrade_RT_3.6.7_to_3.8.8_-_Debian_5.0(lenny)_to_6.0(squeeze)]]

= Other =

* [[CompilingPerl]]
* [[ManualApache]]
* [[InstallMailgateOnly]]

= Deployment guides =

Documents which explain why and which way, rather than how.

* [[ItsFinallyInstalledNowWhat]]
* The [http://web.mit.edu/tooltime/ MITProjectNotebook], especially the [http://web.mit.edu/tooltime/notebook/reference/documentation.html Documentation page], which includes a [http://web.mit.edu/tooltime/notebook/reference/rtbasics.pdf 15 page PDF] User's Manual.

SiteConfig

2025-06-25T12:26:40Z

Jbrandt: /* Plugins */

= What It Is =

The '''SiteConfig''' file lives in <code>${RTHOME}/etc/RT_SiteConfig.pm</code>. Its purpose is to provide you a place to override config settings in <code>${RTHOME}/etc/RT_Config.pm</code> as well as add new config variables as provided by various user [[Contributions]] or for your own purposes.

All of the available configuration options are documented in RT_Config.pm and also [http://bestpractical.com/rt/docs/latest/RT_Config.html available on the web].

You set a config variable like so:

Set($Foo, "Value of Foo");
Set($Bar, 1);
Set(@Baz, "array", "of", "values");
Set(%Zot, "hash" => "of", "keyed" => "values");

You access them like this in RT 3.8 and newer:

RT->Config->Get('Foo') # "Value of option Foo"
RT->Config->Get('Bar') # 1
RT->Config->Get('Baz')->[0] # get option Baz that is array reference and access first element

= Plugins =

Enable extensions, also called plugins, with a <code>Plugin</code> line.

Plugin('RT::Extension::ResetPassword');
Plugin('RT::Extension::Helpdesk');

Use one line for each plugin.

RT before version 4 used syntax like this:

Set(@Plugins, qw(Extension::QuickDelete));

When upgrading, convert to the <code>Plugin</code> form shown above.

==Custom Statuses==

RT 4 and after use the [http://bestpractical.com/rt/docs/latest/customizing/lifecycles.html Lifecycles] system to define custom statuses, workflows, actions, and more.

RT 3.8 and prior used configuration values to define [[CustomStatuses]].

SiteConfig

2025-06-25T12:24:53Z

Jbrandt: /* Plugins and Extensions */

= What It Is =

The '''SiteConfig''' file lives in <code>${RTHOME}/etc/RT_SiteConfig.pm</code>. Its purpose is to provide you a place to override config settings in <code>${RTHOME}/etc/RT_Config.pm</code> as well as add new config variables as provided by various user [[Contributions]] or for your own purposes.

All of the available configuration options are documented in RT_Config.pm and also [http://bestpractical.com/rt/docs/latest/RT_Config.html available on the web].

You set a config variable like so:

Set($Foo, "Value of Foo");
Set($Bar, 1);
Set(@Baz, "array", "of", "values");
Set(%Zot, "hash" => "of", "keyed" => "values");

You access them like this in RT 3.8 and newer:

RT->Config->Get('Foo') # "Value of option Foo"
RT->Config->Get('Bar') # 1
RT->Config->Get('Baz')->[0] # get option Baz that is array reference and access first element

= Plugins =

Enable extensions, also called plugins, with a `Plugin` line.

Plugin('RT::Extension::ResetPassword');
Plugin('RT::Extension::Helpdesk');

Use one line for each plugin.

RT before version 4 used syntax like this:

Set(@Plugins, qw(Extension::QuickDelete));

When upgrading, convert to the `Plugin` form shown above.

==Custom Statuses==

RT 4 and after use the [http://bestpractical.com/rt/docs/latest/customizing/lifecycles.html Lifecycles] system to define custom statuses, workflows, actions, and more.

RT 3.8 and prior used configuration values to define [[CustomStatuses]].

ManualInstallation

2022-12-20T16:13:36Z

Jbrandt:

Prev: [[ManualRequirements]] — Up: [[UserManual]] — Next: [[ManualApacheConfig]]

This guide walks you through installing RT from source on a modern, popular Linux distro. Specifically, that means a distribution based on Debian or Red Hat that’s been released since around 2020.

RT's [https://docs.bestpractical.com/rt/latest/README.html README] for the version you are installing is the best starting resource. It provides the high-level steps to follow, but not details. This guide provides some of those details. It is not meant to be followed step by step, but it does provide guidance once you have picked the database and web server you want to use for RT.

This guide assumes:

* You can install packages generally available in Debian/Ubuntu or Red Hat/Fedora/CentOS.
* You want to install RT, and all of its Perl dependencies, from source to get the latest versions. (This is a trade-off. It means the boundaries of your install will be very clear, but you won’t get security updates for RT or Perl modules from your distribution.)
* You are willing to install a couple of extra tools to manage the RT installation similarly to how you would in other packaging systems (like PyPI, npm, etc.).
* You are willing to do a relatively maximal install of RT, enabling all the options during installation and then setting what you need in the configuration. (You could save a little space and time by being pickier about your options, but then that complicates the guide and makes it harder to turn those options on later if you want.)
* You are using a regular user account on the Linux system that can get superuser privileges with sudo.

== Install the base dependencies ==

These are required by RT, either to run or to install the dependencies.

=== Debian/Ubuntu ===

<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz multiwatch openssl perl w3m</pre>

=== Red Hat Enterprise Linux ===

These instructions are for RHEL specifically. For RHEL-derived distributions like CentOS and Rocky, go to the next section.

<pre>MAJDISTVER="$(. /etc/os-release && echo "${VERSION_ID%%.*}")"
sudo subscription-manager repos --enable "codeready-builder-for-rhel-$MAJDISTVER-$(arch)-rpms"
sudo dnf install "https://dl.fedoraproject.org/pub/epel/epel-release-latest-$MAJDISTVER.noarch.rpm"
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

=== RHEL Community Distributions: Fedora/CentOS/Rocky ===

<pre>sudo dnf install epel-release
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

== Install a database ==

You need access to a database server. It can be remote, or you can install a database server alongside RT. RT supports MySQL, MariaDB, Postgresql, and Oracle, and SQLite for development. Currently MariaDB and Postgreql are easiest to get and install via most Linux packaging systems.

=== Installing and configuring the PostgreSQL server ===

If you want to install a fresh PostgreSQL database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

In order to set up RT’s database, you will need a PostgreSQL account that can create databases and roles and be authenticated with a password. If you don’t have that, you can create it by running:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Enable password authentication in PostgreSQL ===

You need to consider this step whether you install the database locally, or use an existing one already running. RT supports connecting to PostgreSQL a few different ways, but authenticating with a username and password is simplest, and this guide is written based on that. Not all PostgreSQL installations allow this authentication method by default. You need to review your <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

Replace <code>VERSION</code> with the version of your PostgreSQL database. Add these two lines '''above''' any other lines that start with <code>host</code>:

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> crypted password over a network connection (possibly using the localhost loopback network). You might be able to further restrict some of these fields for improved security, but doing so is outside the scope of this install guide. Refer to [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

These are required for RT to be able to talk to any PostgreSQL server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing RT.

=== Installing and configuring the MariaDB server ===

If you want to install a fresh MariaDB database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

In order to set up RT’s database, you will need a MySQL superuser account. To stay consistent with PostgreSQL, I suggest setting a password for it. You can do that by running:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
Record your passphrase; you’ll need it later.

=== Adjust MariaDB’s max_allowed_packet setting ===

You need to consider this step whether you install the database locally, or use an existing one already running. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> setting] functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

These are required for RT to be able to talk to any MariaDB server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Optional: Create RT system accounts ===

Creating separate RT system accounts is optional. Running configure will usually auto detect the correct group and user to use for setting permissions. See the [https://docs.bestpractical.com/rt/latest/configure.html group and user related options for configure] to fine tune the permissions.

You can create this user and group if you prefer not to install as root. This account will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt
sudo useradd --system --home-dir=/opt/rt5/var --gid=rt rt</pre>

=== Get and unpack the RT source code ===

Download the latest source code using the link on the [https://bestpractical.com/download-page RT download page], extract it using <code>tar -xf</code>, and <code>cd</code> into the source code directory to run the rest of the commands in this section. For example:

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.3.tar.gz
tar -xf rt-5.0.3.tar.gz
cd rt-5.0.3</pre>

=== Pre-configure RT ===

The [https://docs.bestpractical.com/rt/latest/configure.html configure] command will detect some information about your system in order to install RT properly, and decide which set of dependencies to install. Here’s what the different parts of our command are doing:

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> setting (see next item). If you know you want to use a specific Perl installed on your system, you can specify its full path instead of the plain <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> installs RT using the dedicated accounts we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory. As an example of manually setting serveral options, you can run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-user=rt --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>

Many of the values have default settings, like /opt/rt5 as the prefix. And the configure script will try to find things like the configured <code>perl</code>, so this can also work for a fairly typical RT:

<pre>./configure --enable-gd --enable-graphviz</pre>

For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Install RT and its Perl dependencies ===

This command will download, build, and install all of the Perl modules necessary to run RT with the configuration you set above. RT has [https://docs.bestpractical.com/rt/latest/rt_perl.html additional documentation] on setting up your perl. Here’s what the different parts of the command are doing:

* <code>make dirs</code> creates RT's directory structure, so we can install dependencies inside it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=…</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command) inside RT's directory structure.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> succeeded.

Make sure you have <code>cd</code>ed into the RT source directory. To install the modules in the standard perl directories, run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo"
sudo make install</pre>

If you want to install the perl libraries in the RT directories, you could run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>

If it works, the command will eventually output a message that says “Congratulations. RT is now installed.” followed by instructions about configuring and setting up the database. We’ll do that next.

=== Configure RT ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
# Single-quote all values EXCEPT the special value `undef`
# that turns off a setting.

# rtname appears in ticket email subjects. It needs to be globally unique,
# so use your organization's domain name.
Set($rtname, 'EDIT WITH yourdomain.example.com');
# Organization is used in the database for ticket links, etc. It also needs to
# be globally unique, so use your organization's domain name.
Set($Organization, 'EDIT WITH yourdomain.example.com');
# WebDomain is domain name of the RT web server. RT uses it to construct links
# and defend against CSRFs.
Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com');
# WebPort is the port where the RT web server runs. Edit the number below if
# you're not using the standard HTTPS port.
Set($WebPort, '443');
# WebPath is the path where the RT web server runs on your WebDomain.
# Edit the path below only if you're using a specific path like example.com/rt
Set($WebPath, '/rt');

# DatabaseUser is the name of the database account RT uses to read and store
# data. 'rt_user' is the default but you can change it if you like.
# DO NOT use the 'rt_admin' superuser created in the instructions above.
Set($DatabaseUser, 'rt_user');
# DatabasePassword is the password for DatabaseUser.
Set($DatabasePassword, 'EDIT WITH SomePassphraseHere');
# DatabaseHost is the hostname of the database server RT should use.
# Change 'localhost' if it lives on a different server.
Set($DatabaseHost, 'localhost');
# DatabasePort is the port number of the database server RT should use.
# `undef` means the default for that database. Change it if you're not
# using the standard port.
Set($DatabasePort, undef);
# DatabaseName is the name of RT's database hosted on DatabaseHost.
# 'rt5' is the default but you can change it if you like.
Set($DatabaseName, 'rt5');
# DatabaseAdmin is the name of the user in the database used to perform
# major administrative tasks. Change 'rt_admin' if you're using a user
# besides the one created in this guide.
Set($DatabaseAdmin, 'rt_admin');

# RT can log to syslog, stderr, and/or a dedicated file.
# Log settings are used both by the primary server and by command line
# tools like rt-crontool, rt-ldapimport, etc.
# You set all of RT's $LogTo* paramaters to a standard log level: 'debug',
# 'info', 'notice', 'warning', 'error', 'critical', 'alert', or 'emergency'.
# For a modern install, if you log to syslog, it goes
# to journald where it's easy to query and automatically gets rotated.
# Some syslogs log only warn and error, so lower levels like debug won't appear here.
Set($LogToSyslog, 'warning');

# When the RT server logs to stderr, that will go to the rt-server journal.
# Command line tools log to their own stderr. Setting this to
# 'warning' or 'error' helps ensure you get notified if RT's cron jobs
# encounter problems.
# When running with Apache, these logs will go to the Apache error log,
# which should be set up with logrotate automatically.
Set($LogToSTDERR, 'warning');

# Turn off optional features that require additional configuration.
# If you want to use these, refer to the RT_Config documentation for
# instructions on how to set them up.
Set(%GnuPG, 'Enable' => '0');
Set(%SMIME, 'Enable' => '0');

# Perl expects to find this 1 at the end of the file.
1;
</pre>

<code>RT_SiteConfig.pm</code> is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== Set up RT’s database ===

RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.

The instructions from <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>, so run:

<pre>make initialize-database</pre>

That runs the <code>rt-setup-database</code> command for you. If you're curious, you can see all of the options in [https://docs.bestpractical.com/rt/latest/rt-setup-database.html RT's documentation].

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* '''If''' you are using an existing database server and the database administrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> option.
* '''If''' you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

=== Set up fulltext indexing ===

Fulltext indexing speeds up searches for ticket content, which makes RT a lot nicer to use.

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### EXAMPLE OUTPUT ONLY - Don't use this directly!
Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>.

=== Set permissions ===

All of RT’s configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>

This is done as part of the installation, so permissions should be correct, but this is helpful if you change something.

=== Verify the installation ===

If everything has gone well, then you should be able to set a password for RT’s <code>root</code> user. You’ll use this later to log in to the web interface and continue setting up your system. Run:

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>

Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network, with SSL, is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto RT using Apache with mod_fcgid or nginx and the RT FastCGI service.

See the [https://docs.bestpractical.com/rt/latest/web_deployment.html RT deployment guide] for the latest recommendations from Best Practical on how to deploy RT.

=== Apache httpd ===

Make sure you have the necessary packages installed, are using the [https://docs.bestpractical.com/rt/latest/web_deployment.html#prefork-MPM preform MPM], and the mod_fcgid module is enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid
sudo a2dismod mpm_event
sudo a2dismod mpm_worker
sudo systemctl restart apache2
sudo a2enmod mpm_prefork
sudo systemctl restart apache2
</pre>
|<pre>sudo dnf install httpd</pre>
|}

In the <code><VirtualHost></code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>Alias</code> or <code>ScriptAlias</code> lines:

<pre>
### Optional apache logs for RT
# Ensure that your log rotation scripts know about these files
# ErrorLog /opt/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug

AddDefaultCharset UTF-8

# ScriptAlias and Location should match RT's WebPath

# If WebPath is empty then use a single slash:
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# If WebPath is 'rt' then add that after the slash:
# ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/

DocumentRoot "/opt/rt5/share/html"

# If WebPath is empty then use a single slash:
<Location />
# If WebPath is 'rt' then add that after the slash:
# <Location /rt>

Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
</pre>

If you're doing a fresh install, the default <code><VirtualHost></code> configuration location varies by distribution and whether or not you're using HTTPS:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

After you’ve edited your configuration, load it by running:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== nginx ===

==== Set up RT FastCGI service for use with nginx ====

===== Create the RT service =====

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

This opens an editor to define the RT service to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server

[Service]
# The --forks option is the number of RT servers to run in parallel.
# 3 should be good for most initial installs. You can increase this
# number later if needed for performance.
ExecStart=/usr/bin/multiwatch --forks=3 --signal=TERM -- /opt/rt5/sbin/rt-server.fcgi
StandardInput=socket
User=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

===== Create the RT socket =====

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

This opens an editor to define the RT socket to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server socket
Wants=network.target
After=network.target
Before=apache2.service httpd.service nginx.service

[Install]
WantedBy=sockets.target

[Socket]
# ListenStream defines the address and port where the RT FastCGI server listens.
# This is NOT the web server itself, so don't make this port 80, 443, etc.
# You may edit this if you like, but note:
# Connections are unencrypted. You should only listen on a secure network
# interface.
# The server can only accept a single socket. You cannot specify more than
# one ListenStream address.
ListenStream=[::1]:5000
Accept=no
FreeBind=yes
</pre>

Save the file and close your editor.

===== Enable the RT socket =====

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

In the <code>http server</code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>location</code> blocks:

<pre>
# The location path should match the WebPath in your RT site configuration.
location / {
include /etc/nginx/fastcgi.conf;
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
fastcgi_param SCRIPT_NAME "";
# This network location should match the ListenStream in rt-server.socket.
fastcgi_pass localhost:5000;
}
</pre>

If you're doing a fresh install, the default <code>http server</code> configuration location varies by distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

After you’ve edited your configuration, load it by running:

<pre>sudo systemctl reload nginx</pre>

Once this is done you can skip ahead to Verify the web interface.

=== Verify the web interface ===

You should be able to visit your web server in your browser, and be presented with RT’s login screen. You should be able to log in with username <code>root</code> and the password you set previously.

If the web server returns a 502 Bad Gateway response, it's having trouble connecting to the RT FCGI server. Check the error logs for your web server:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

For all kinds of errors, you can check the logs for the RT FCGI server and its socket:

<pre>sudo journalctl --unit rt-server.\*</pre>

== Set up RT’s mail server ==

RT both can both send and receive ticket updates via email. Unfortunately, there are too many variables to document a useful setup process here: getting this working usually requires creating DNS records, and coordinating with existing mail servers, which will be the main constraint on your setup. Instead this guide provides a brief overview of how the integration works, and where the connection points are that you likely need to work on.

=== Sending Mail ===

RT only knows how to send mail by passing it off to another program on the system. It does not connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command, which is provided by whichever MTA you have installed (postfix, sendmail, exim, qmail, etc.). There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail configuration options to send mail through different commands] if you need.

The most common setup is to install and configure a proper Mail Transfer Agent (MTA) like Postfix or Exim, and then configure it to send mail to the wider Internet as you need. This works well because the MTAs are robust and well-tested; they have flexible configuration to let you send mail out by relaying to other mail servers you specify with optional authentication; and most distributions install one by default anyway. The only hard part is configuring the MTA to send mail following your site’s policies.

Other software is available that provides a slimmer version of the <code>sendmail</code> command that connects to an external mail server for you, like msmtp. These programs are usually easier to configure than an MTA, but they often lose email permanently if they can’t connect to the external server at the time it’s sent. (MTAs keep email queued locally until they successfully deliver it to another server.)

=== Receiving email ===

RT installs a command called <code>rt-mailgate</code> that receives an email on standard input and posts it to RT’s REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.

The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example <code>/etc/aliases</code> entries look like:

<pre>rt: "|/opt/rt5/bin/rt-mailgate --queue general --action correspond --url https://rt.yourdomain.example.com/"
rt-comment: "|/opt/rt5/bin/rt-mailgate --queue general --action comment --url https://rt.yourdomain.example.com/"</pre>

This works well because, again, you’re probably running an MTA anyway; and the MTA can hold and queue mail if it comes in while RT is down for any reason, giving you a buffer against downtime.

Another common option is to periodically run a tool that fetches mail using a protocol like IMAP, like fetchmail or getmail, and passes it on to <code>rt-mailgate</code>. This is less common because it requires setting up another tool to run, and securely storing another set of mail server credentials. But it is useful when local policy prevents the RT server from receiving email directly.

This is much less common, but it might help to know that <code>rt-mailgate</code> doesn’t have to run on the same system as RT itself. It just needs to be able to connect to RT’s web interface. If you don’t have any other options, you can install the RT software on a different system that receives email, and configure ''that'' system to run <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
1 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
50 3 * * * rt /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon rt /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * rt /opt/rt5/sbin/rt-email-digest -m daily
</pre>

== Set up RT ==

If you’ve gotten this far, congratulations, your RT install is really done now. You can start setting up RT with users, groups, queues, and business logic. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-12-20T14:55:31Z

Jbrandt:

Prev: [[ManualRequirements]] — Up: [[UserManual]] — Next: [[ManualApacheConfig]]

This guide walks you through installing RT from source on a modern, popular Linux distro. Specifically, that means a distribution based on Debian or Red Hat that’s been released since around 2020.

RT's [https://docs.bestpractical.com/rt/latest/README.html README] for the version you are installing is the best starting resource. It provides the high-level steps to follow, but not details. This guide provides some of those details. It is not meant to be followed step by step, but it does provide guidance once you have picked the database and web server you want to use for RT.

This guide assumes:

* You can install packages generally available in Debian/Ubuntu or Red Hat/Fedora/CentOS.
* You want to install RT, and all of its Perl dependencies, from source to get the latest versions. (This is a trade-off. It means the boundaries of your install will be very clear, but you won’t get security updates for RT or Perl modules from your distribution.)
* You are willing to install a couple of extra tools to manage the RT installation similarly to how you would in other packaging systems (like PyPI, npm, etc.).
* You are willing to do a relatively maximal install of RT, enabling all the options during installation and then setting what you need in the configuration. (You could save a little space and time by being pickier about your options, but then that complicates the guide and makes it harder to turn those options on later if you want.)
* You are using a regular user account on the Linux system that can get superuser privileges with sudo.

== Install the base dependencies ==

These are required by RT, either to run or to install the dependencies.

=== Debian/Ubuntu ===

<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz multiwatch openssl perl w3m</pre>

=== Red Hat Enterprise Linux ===

These instructions are for RHEL specifically. For RHEL-derived distributions like CentOS and Rocky, go to the next section.

<pre>MAJDISTVER="$(. /etc/os-release && echo "${VERSION_ID%%.*}")"
sudo subscription-manager repos --enable "codeready-builder-for-rhel-$MAJDISTVER-$(arch)-rpms"
sudo dnf install "https://dl.fedoraproject.org/pub/epel/epel-release-latest-$MAJDISTVER.noarch.rpm"
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

=== RHEL Community Distributions: Fedora/CentOS/Rocky ===

<pre>sudo dnf install epel-release
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

== Install a database ==

You need access to a database server. It can be remote, or you can install a database server alongside RT. RT supports MySQL, MariaDB, Postgresql, and Oracle, and SQLite for development. Currently MariaDB and Postgreql are easiest to get and install via most Linux packaging systems.

=== Installing and configuring the PostgreSQL server ===

If you want to install a fresh PostgreSQL database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

In order to set up RT’s database, you will need a PostgreSQL account that can create databases and roles and be authenticated with a password. If you don’t have that, you can create it by running:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Enable password authentication in PostgreSQL ===

You need to consider this step whether you install the database locally, or use an existing one already running. RT supports connecting to PostgreSQL a few different ways, but authenticating with a username and password is simplest, and this guide is written based on that. Not all PostgreSQL installations allow this authentication method by default. You need to review your <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

Replace <code>VERSION</code> with the version of your PostgreSQL database. Add these two lines '''above''' any other lines that start with <code>host</code>:

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> crypted password over a network connection (possibly using the localhost loopback network). You might be able to further restrict some of these fields for improved security, but doing so is outside the scope of this install guide. Refer to [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

These are required for RT to be able to talk to any PostgreSQL server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing RT.

=== Installing and configuring the MariaDB server ===

If you want to install a fresh MariaDB database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

In order to set up RT’s database, you will need a MySQL superuser account. To stay consistent with PostgreSQL, I suggest setting a password for it. You can do that by running:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
Record your passphrase; you’ll need it later.

=== Adjust MariaDB’s max_allowed_packet setting ===

You need to consider this step whether you install the database locally, or use an existing one already running. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> setting] functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

These are required for RT to be able to talk to any MariaDB server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Optional: Create RT system accounts ===

Creating separate RT system accounts is optional. Running configure will usually auto detect the correct group and user to use for setting permissions. See the [https://docs.bestpractical.com/rt/latest/configure.html group and user related options for configure] to fine tune the permissions.

You can create this user and group if you prefer not to install as root. This account will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt
sudo useradd --system --home-dir=/opt/rt5/var --gid=rt rt</pre>

=== Get and unpack the RT source code ===

Download the latest source code using the link on the [https://bestpractical.com/download-page RT download page], extract it using <code>tar -xf</code>, and <code>cd</code> into the source code directory to run the rest of the commands in this section. For example:

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.3.tar.gz
tar -xf rt-5.0.3.tar.gz
cd rt-5.0.3</pre>

=== Pre-configure RT ===

The [https://docs.bestpractical.com/rt/latest/configure.html configure] command will detect some information about your system in order to install RT properly, and decide which set of dependencies to install. Here’s what the different parts of our command are doing:

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> setting (see next item). If you know you want to use a specific Perl installed on your system, you can specify its full path instead of the plain <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> installs RT using the dedicated accounts we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory. As an example of manually setting serveral options, you can run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-user=rt --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>

Many of the values have default settings, like /opt/rt5 as the prefix. And the configure script will try to find things like the configured <code>perl</code>, so this can also work for a fairly typical RT:

<pre>./configure --enable-gd --enable-graphviz</pre>

For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Install RT and its Perl dependencies ===

This command will download, build, and install all of the Perl modules necessary to run RT with the configuration you set above. RT has [https://docs.bestpractical.com/rt/latest/rt_perl.html additional documentation] on setting up your perl. Here’s what the different parts of the command are doing:

* <code>make dirs</code> creates RT's directory structure, so we can install dependencies inside it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=…</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command) inside RT's directory structure.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> succeeded.

Make sure you have <code>cd</code>ed into the RT source directory. To install the modules in the standard perl directories, run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo"
sudo make install</pre>

If you want to install the perl libraries in the RT directories, you could run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>

If it works, the command will eventually output a message that says “Congratulations. RT is now installed.” followed by instructions about configuring and setting up the database. We’ll do that next.

=== Configure RT ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
# Single-quote all values EXCEPT the special value `undef`
# that turns off a setting.

# rtname appears in ticket email subjects. It needs to be globally unique,
# so use your organization's domain name.
Set($rtname, 'EDIT WITH yourdomain.example.com');
# Organization is used in the database for ticket links, etc. It also needs to
# be globally unique, so use your organization's domain name.
Set($Organization, 'EDIT WITH yourdomain.example.com');
# WebDomain is domain name of the RT web server. RT uses it to construct links
# and defend against CSRFs.
Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com');
# WebPort is the port where the RT web server runs. Edit the number below if
# you're not using the standard HTTPS port.
Set($WebPort, '443');
# WebPath is the path where the RT web server runs on your WebDomain.
# Edit the path below only if you're using a specific path like example.com/rt
Set($WebPath, '/rt');

# DatabaseUser is the name of the database account RT uses to read and store
# data. 'rt_user' is the default but you can change it if you like.
# DO NOT use the 'rt_admin' superuser created in the instructions above.
Set($DatabaseUser, 'rt_user');
# DatabasePassword is the password for DatabaseUser.
Set($DatabasePassword, 'EDIT WITH SomePassphraseHere');
# DatabaseHost is the hostname of the database server RT should use.
# Change 'localhost' if it lives on a different server.
Set($DatabaseHost, 'localhost');
# DatabasePort is the port number of the database server RT should use.
# `undef` means the default for that database. Change it if you're not
# using the standard port.
Set($DatabasePort, undef);
# DatabaseName is the name of RT's database hosted on DatabaseHost.
# 'rt5' is the default but you can change it if you like.
Set($DatabaseName, 'rt5');
# DatabaseAdmin is the name of the user in the database used to perform
# major administrative tasks. Change 'rt_admin' if you're using a user
# besides the one created in this guide.
Set($DatabaseAdmin, 'rt_admin');

# RT can log to syslog, stderr, and/or a dedicated file.
# Log settings are used both by the primary server and by command line
# tools like rt-crontool, rt-ldapimport, etc.
# You set all of RT's $LogTo* paramaters to a standard log level: 'debug',
# 'info', 'notice', 'warning', 'error', 'critical', 'alert', or 'emergency'.
# For a modern install, if you log to syslog, it goes
# to journald where it's easy to query and automatically gets rotated.
# Some syslogs log only warn and error, so lower levels like debug won't appear here.
Set($LogToSyslog, 'warning');

# When the RT server logs to stderr, that will go to the rt-server journal.
# Command line tools log to their own stderr. Setting this to
# 'warning' or 'error' helps ensure you get notified if RT's cron jobs
# encounter problems.
# When running with Apache, these logs will go to the Apache error log,
# which should be set up with logrotate automatically.
Set($LogToSTDERR, 'warning');

# Turn off optional features that require additional configuration.
# If you want to use these, refer to the RT_Config documentation for
# instructions on how to set them up.
Set(%GnuPG, 'Enable' => '0');
Set(%SMIME, 'Enable' => '0');

# Perl expects to find this 1 at the end of the file.
1;
</pre>

<code>RT_SiteConfig.pm</code> is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== Set up RT’s database ===

RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.

The instructions from <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>, so run:

<pre>make initialize-database</pre>

That runs the <code>rt-setup-database</code> command for you. If you're curious, you can see all of the options in [https://docs.bestpractical.com/rt/latest/rt-setup-database.html RT's documentation].

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* '''If''' you are using an existing database server and the database administrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> option.
* '''If''' you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

=== Set up fulltext indexing ===

Fulltext indexing speeds up searches for ticket content, which makes RT a lot nicer to use.

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### EXAMPLE OUTPUT ONLY - Don't use this directly!
Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== Set permissions ===

All of RT’s configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

If everything has gone well, then you should be able to set a password for RT’s <code>root</code> user. You’ll use this later to log in to the web interface and continue setting up your system. Run:

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto RT using Apache with mod_fcgid or nginx and the RT FastCGI service.

See the [https://docs.bestpractical.com/rt/latest/web_deployment.html RT deployment guide] for the latest recommendations from Best Practical on how to deploy RT.

=== Apache httpd ===

Make sure you have the necessary packages installed, are using the [https://docs.bestpractical.com/rt/latest/web_deployment.html#prefork-MPM preform MPM], and the mod_fcgid module is enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid
sudo a2dismod mpm_event
sudo a2dismod mpm_worker
sudo systemctl restart apache2
sudo a2enmod mpm_prefork
sudo systemctl restart apache2
</pre>
|<pre>sudo dnf install httpd</pre>
|}

In the <code><VirtualHost></code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>Alias</code> or <code>ScriptAlias</code> lines:

<pre>
### Optional apache logs for RT
# Ensure that your log rotation scripts know about these files
# ErrorLog /opt/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug

AddDefaultCharset UTF-8

# ScriptAlias and Location should match RT's WebPath

# If WebPath is empty then use a single slash:
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# If WebPath is 'rt' then add that after the slash:
# ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/

DocumentRoot "/opt/rt5/share/html"

# If WebPath is empty then use a single slash:
<Location />
# If WebPath is 'rt' then add that after the slash:
# <Location /rt>

Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
</pre>

If you're doing a fresh install, the default <code><VirtualHost></code> configuration location varies by distribution and whether or not you're using HTTPS:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

After you’ve edited your configuration, load it by running:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== nginx ===

==== Set up RT FastCGI service for use with nginx ====

===== Create the RT service =====

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

This opens an editor to define the RT service to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server

[Service]
# The --forks option is the number of RT servers to run in parallel.
# 3 should be good for most initial installs. You can increase this
# number later if needed for performance.
ExecStart=/usr/bin/multiwatch --forks=3 --signal=TERM -- /opt/rt5/sbin/rt-server.fcgi
StandardInput=socket
User=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

===== Create the RT socket =====

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

This opens an editor to define the RT socket to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server socket
Wants=network.target
After=network.target
Before=apache2.service httpd.service nginx.service

[Install]
WantedBy=sockets.target

[Socket]
# ListenStream defines the address and port where the RT FastCGI server listens.
# This is NOT the web server itself, so don't make this port 80, 443, etc.
# You may edit this if you like, but note:
# Connections are unencrypted. You should only listen on a secure network
# interface.
# The server can only accept a single socket. You cannot specify more than
# one ListenStream address.
ListenStream=[::1]:5000
Accept=no
FreeBind=yes
</pre>

Save the file and close your editor.

===== Enable the RT socket =====

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

In the <code>http server</code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>location</code> blocks:

<pre>
# The location path should match the WebPath in your RT site configuration.
location / {
include /etc/nginx/fastcgi.conf;
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
fastcgi_param SCRIPT_NAME "";
# This network location should match the ListenStream in rt-server.socket.
fastcgi_pass localhost:5000;
}
</pre>

If you're doing a fresh install, the default <code>http server</code> configuration location varies by distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

After you’ve edited your configuration, load it by running:

<pre>sudo systemctl reload nginx</pre>

Once this is done you can skip ahead to Verify the web interface.

=== Verify the web interface ===

You should be able to visit your web server in your browser, and be presented with RT’s login screen. You should be able to log in with username <code>root</code> and the password you set previously.

If the web server returns a 502 Bad Gateway response, it's having trouble connecting to the RT FCGI server. Check the error logs for your web server:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

For all kinds of errors, you can check the logs for the RT FCGI server and its socket:

<pre>sudo journalctl --unit rt-server.\*</pre>

== Set up RT’s mail server ==

RT both can both send and receive ticket updates via email. Unfortunately, there are too many variables to document a useful setup process here: getting this working usually requires creating DNS records, and coordinating with existing mail servers, which will be the main constraint on your setup. Instead this guide provides a brief overview of how the integration works, and where the connection points are that you likely need to work on.

=== Sending Mail ===

RT only knows how to send mail by passing it off to another program on the system. It cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail configuration options to send mail through different commands] if you need.

The most common setup is to install and configure a proper Mail Transfer Agent (MTA) like Postfix or Exim, and then configure it to send mail to the wider Internet as you need. This works well because the MTAs are robust and well-tested; they have flexible configuration to let you send mail out by relaying to other mail servers you specify with optional authentication; and most distributions install one by default anyway. The only hard part is configuring the MTA to send mail following your site’s policies.

Other software is available that provides a slimmer version of the <code>sendmail</code> command that connects to an external mail server for you, like msmtp. These programs are usually easier to configure than an MTA, but they often lose email permanently if they can’t connect to the external server at the time it’s sent. (MTAs keep email queued locally until they successfully deliver it to another server.)

=== Receiving email ===

RT installs a command called <code>rt-mailgate</code> that receives an email on standard input and posts it to RT’s REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.

The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example <code>/etc/aliases</code> entries look like:

<pre>rt: "|/opt/rt5/bin/rt-mailgate --queue general --action correspond --url https://rt.yourdomain.example.com/"
rt-comment: "|/opt/rt5/bin/rt-mailgate --queue general --action comment --url https://rt.yourdomain.example.com/"</pre>
This works well because, again, you’re probably running an MTA anyway; and the MTA can hold and queue mail if it comes in while RT is down for any reason, giving you a buffer against downtime.

Another common option is to periodically run a tool that fetches mail using a protocol like IMAP, like fetchmail or getmail, and passes it on to <code>rt-mailgate</code>. This is less common because it requires setting up another tool to run, and securely storing another set of mail server credentials. But it is useful when local policy prevents the RT server from receiving email directly.

This is much less common, but it might help to know that <code>rt-mailgate</code> doesn’t have to run on the same system as RT itself. It just needs to be able to connect to RT’s web interface. If you don’t have any other options, you can install the RT software on a different system that receives email, and configure ''that'' system to run <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
1 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
50 3 * * * rt /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon rt /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * rt /opt/rt5/sbin/rt-email-digest -m daily
</pre>

== Set up RT ==

If you’ve gotten this far, congratulations, your RT install is really done now. You can start setting up RT with users, groups, queues, and business logic. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-12-20T14:30:05Z

Jbrandt:

Prev: [[ManualRequirements]] — Up: [[UserManual]] — Next: [[ManualApacheConfig]]

This guide walks you through installing RT from source on a modern, popular Linux distro. Specifically, that means a distribution based on Debian or Red Hat that’s been released since around 2020.

RT's [https://docs.bestpractical.com/rt/latest/README.html README] for the version you are installing is the best starting resource. It provides the high-level steps to follow, but not details. This guide provides some of those details. It is not meant to be followed step by step, but it does provide guidance once you have picked the database and web server you want to use for RT.

This guide assumes:

* You can install packages generally available in Debian/Ubuntu or Red Hat/Fedora/CentOS.
* You want to install RT, and all of its Perl dependencies, from source to get the latest versions. (This is a trade-off. It means the boundaries of your install will be very clear, but you won’t get security updates for RT or Perl modules from your distribution.)
* You are willing to install a couple of extra tools to manage the RT installation similarly to how you would in other packaging systems (like PyPI, npm, etc.).
* You are willing to do a relatively maximal install of RT, enabling all the options during installation and then setting what you need in the configuration. (You could save a little space and time by being pickier about your options, but then that complicates the guide and makes it harder to turn those options on later if you want.)
* You are using a regular user account on the Linux system that can get superuser privileges with sudo.

== Install the base dependencies ==

These are required by RT, either to run or to install the dependencies.

=== Debian/Ubuntu ===

<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz multiwatch openssl perl w3m</pre>

=== Red Hat Enterprise Linux ===

These instructions are for RHEL specifically. For RHEL-derived distributions like CentOS and Rocky, go to the next section.

<pre>MAJDISTVER="$(. /etc/os-release && echo "${VERSION_ID%%.*}")"
sudo subscription-manager repos --enable "codeready-builder-for-rhel-$MAJDISTVER-$(arch)-rpms"
sudo dnf install "https://dl.fedoraproject.org/pub/epel/epel-release-latest-$MAJDISTVER.noarch.rpm"
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

=== RHEL Community Distributions: Fedora/CentOS/Rocky ===

<pre>sudo dnf install epel-release
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

== Install a database ==

You need access to a database server. It can be remote, or you can install a database server alongside RT. RT supports MySQL, MariaDB, Postgresql, and Oracle, and SQLite for development. Currently MariaDB and Postgreql are easiest to get and install via most Linux packaging systems.

=== Installing and configuring the PostgreSQL server ===

If you want to install a fresh PostgreSQL database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

In order to set up RT’s database, you will need a PostgreSQL account that can create databases and roles and be authenticated with a password. If you don’t have that, you can create it by running:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Enable password authentication in PostgreSQL ===

You need to consider this step whether you install the database locally, or use an existing one already running. RT supports connecting to PostgreSQL a few different ways, but authenticating with a username and password is simplest, and this guide is written based on that. Not all PostgreSQL installations allow this authentication method by default. You need to review your <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

Replace <code>VERSION</code> with the version of your PostgreSQL database. Add these two lines '''above''' any other lines that start with <code>host</code>:

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> crypted password over a network connection (possibly using the localhost loopback network). You might be able to further restrict some of these fields for improved security, but doing so is outside the scope of this install guide. Refer to [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

These are required for RT to be able to talk to any PostgreSQL server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing RT.

=== Installing and configuring the MariaDB server ===

If you want to install a fresh MariaDB database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

In order to set up RT’s database, you will need a MySQL superuser account. To stay consistent with PostgreSQL, I suggest setting a password for it. You can do that by running:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
Record your passphrase; you’ll need it later.

=== Adjust MariaDB’s max_allowed_packet setting ===

You need to consider this step whether you install the database locally, or use an existing one already running. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> setting] functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

These are required for RT to be able to talk to any MariaDB server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Optional: Create RT system accounts ===

Creating separate RT system accounts is optional. Running configure will usually auto detect the correct group and user to use for setting permissions. See the [https://docs.bestpractical.com/rt/latest/configure.html group and user related options for configure] to fine tune the permissions.

This account will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt
sudo useradd --system --home-dir=/opt/rt5/var --gid=rt rt</pre>

=== Get and unpack the RT source code ===

Download the latest source code using the link on the [https://bestpractical.com/download-page RT download page], extract it using <code>tar -xf</code>, and <code>cd</code> into the source code directory to run the rest of the commands in this section. For example:

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.3.tar.gz
tar -xf rt-5.0.3.tar.gz
cd rt-5.0.3</pre>

=== Pre-configure RT ===

This command will detect some information about your system in order to install RT properly, and decide which set of dependencies to install. Here’s what the different parts of our command are doing:

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> setting (see next item). If you know you want to use a specific Perl installed on your system, you can specify its full path instead of the plain <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> installs RT using the dedicated accounts we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-user=rt --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Install RT and its Perl dependencies ===

This command will download, build, and install all of the Perl modules necessary to run RT with the configuration you set above. Here’s what the different parts of the command are doing:

* <code>make dirs</code> creates RT's directory structure, so we can install dependencies inside it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=…</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command) inside RT's directory structure.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> succeeded.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
If it works, the command will eventually output a message that says “Congratulations. RT is now installed.” followed by instructions about configuring and setting up the database. We’ll do that next.

=== Configure RT ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
# Single-quote all values EXCEPT the special value `undef`
# that turns off a setting.

# rtname appears in ticket email subjects. It needs to be globally unique,
# so use your organization's domain name.
Set($rtname, 'EDIT WITH yourdomain.example.com');
# Organization is used in the database for ticket links, etc. It also needs to
# be globally unique, so use your organization's domain name.
Set($Organization, 'EDIT WITH yourdomain.example.com');
# WebDomain is domain name of the RT web server. RT uses it to construct links
# and defend against CSRFs.
Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com');
# WebPort is the port where the RT web server runs. Edit the number below if
# you're not using the standard HTTPS port.
Set($WebPort, '443');
# WebPath is the path where the RT web server runs on your WebDomain.
# Edit the path below if you're using a specific path.
Set($WebPath, '/');

# DatabaseUser is the name of the database account RT uses to read and store
# data. 'rt_user' is the default but you can change it if you like.
# DO NOT use the 'rt_admin' superuser created in the instructions above.
Set($DatabaseUser, 'rt_user');
# DatabasePassword is the password for DatabaseUser.
Set($DatabasePassword, 'EDIT WITH SomePassphraseHere');
# DatabaseHost is the hostname of the database server RT should use.
# Change 'localhost' if it lives on a different server.
Set($DatabaseHost, 'localhost');
# DatabasePort is the port number of the database server RT should use.
# `undef` means the default for that database. Change it if you're not
# using the standard port.
Set($DatabasePort, undef);
# DatabaseName is the name of RT's database hosted on DatabaseHost.
# 'rt5' is the default but you can change it if you like.
Set($DatabaseName, 'rt5');
# DatabaseAdmin is the name of the user in the database used to perform
# major administrative tasks. Change 'rt_admin' if you're using a user
# besides the one created in this guide.
Set($DatabaseAdmin, 'rt_admin');

# RT can log to syslog, stderr, and/or a dedicated file.
# Log settings are used both by the primary server and by command line
# tools like rt-crontool, rt-ldapimport, etc.
# You set all of RT's $LogTo* paramaters to a standard log level: 'debug',
# 'info', 'notice', 'warning', 'error', 'critical', 'alert', or 'emergency'.
# For a modern install, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that will go to the rt-server journal.
# Command line tools log to their own stderr. Setting this to
# 'warning' or 'error' helps ensure you get notified if RT's cron jobs
# encounter problems.
Set($LogToSTDERR, 'warning');

# Turn off optional features that require additional configuration.
# If you want to use these, refer to the RT_Config documentation for
# instructions on how to set them up.
Set(%GnuPG, 'Enable' => '0');
Set(%SMIME, 'Enable' => '0');

# Perl expects to find this 1 at the end of the file.
1;
</pre>

<code>RT_SiteConfig.pm</code> is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== Set up RT’s database ===

RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.

(The instructions from <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> option.
* '''If''' you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

Fulltext indexing speeds up searches for ticket content, which makes RT a lot nicer to use.

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### EXAMPLE OUTPUT ONLY - Don't use this directly!
Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== Set permissions ===

All of RT’s configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

If everything has gone well, then you should be able to set a password for RT’s <code>root</code> user. You’ll use this later to log in to the web interface and continue setting up your system. Run:

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto RT using Apache with mod_fcgid or nginx and the RT FastCGI service.

See the [https://docs.bestpractical.com/rt/latest/web_deployment.html RT deployment guide] for the latest recommendations from Best Practical on how to deploy RT.

=== Apache httpd ===

Make sure you have the necessary packages installed, are using the [https://docs.bestpractical.com/rt/latest/web_deployment.html#prefork-MPM preform MPM], and the mod_fcgid module is enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid
sudo a2dismod mpm_event
sudo a2dismod mpm_worker
sudo systemctl restart apache2
sudo a2enmod mpm_prefork
sudo systemctl restart apache2
</pre>
|<pre>sudo dnf install httpd</pre>
|}

In the <code><VirtualHost></code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>Alias</code> or <code>ScriptAlias</code> lines:

<pre>
### Optional apache logs for RT
# Ensure that your log rotation scripts know about these files
# ErrorLog /opt/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug

AddDefaultCharset UTF-8

# ScriptAlias and Location should match RT's WebPath

# If WebPath is empty then use a single slash:
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# If WebPath is 'rt' then add that after the slash:
# ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/

DocumentRoot "/opt/rt5/share/html"

# If WebPath is empty then use a single slash:
<Location />
# If WebPath is 'rt' then add that after the slash:
# <Location /rt>

Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
</pre>

If you're doing a fresh install, the default <code><VirtualHost></code> configuration location varies by distribution and whether or not you're using HTTPS:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

After you’ve edited your configuration, load it by running:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== nginx ===

==== Set up RT FastCGI service for use with nginx ====

===== Create the RT service =====

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

This opens an editor to define the RT service to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server

[Service]
# The --forks option is the number of RT servers to run in parallel.
# 3 should be good for most initial installs. You can increase this
# number later if needed for performance.
ExecStart=/usr/bin/multiwatch --forks=3 --signal=TERM -- /opt/rt5/sbin/rt-server.fcgi
StandardInput=socket
User=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

===== Create the RT socket =====

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

This opens an editor to define the RT socket to systemd. Use the editor to add this text to the file:

<pre>[Unit]
Description=RT FCGI server socket
Wants=network.target
After=network.target
Before=apache2.service httpd.service nginx.service

[Install]
WantedBy=sockets.target

[Socket]
# ListenStream defines the address and port where the RT FastCGI server listens.
# This is NOT the web server itself, so don't make this port 80, 443, etc.
# You may edit this if you like, but note:
# Connections are unencrypted. You should only listen on a secure network
# interface.
# The server can only accept a single socket. You cannot specify more than
# one ListenStream address.
ListenStream=[::1]:5000
Accept=no
FreeBind=yes
</pre>

Save the file and close your editor.

===== Enable the RT socket =====

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

In the <code>http server</code> configuration blocks where you want to serve RT, add a configuration block like this, '''above''' any other <code>location</code> blocks:

<pre>
# The location path should match the WebPath in your RT site configuration.
location / {
include /etc/nginx/fastcgi.conf;
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
fastcgi_param SCRIPT_NAME "";
# This network location should match the ListenStream in rt-server.socket.
fastcgi_pass localhost:5000;
}
</pre>

If you're doing a fresh install, the default <code>http server</code> configuration location varies by distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

After you’ve edited your configuration, load it by running:

<pre>sudo systemctl reload nginx</pre>

Once this is done you can skip ahead to Verify the web interface.

=== Verify the web interface ===

You should be able to visit your web server in your browser, and be presented with RT’s login screen. You should be able to log in with username <code>root</code> and the password you set previously.

If the web server returns a 502 Bad Gateway response, it's having trouble connecting to the RT FCGI server. Check the error logs for your web server:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

For all kinds of errors, you can check the logs for the RT FCGI server and its socket:

<pre>sudo journalctl --unit rt-server.\*</pre>

== Set up RT’s mail server ==

RT both can both send and receive ticket updates via email. Unfortunately, there are too many variables to document a useful setup process here: getting this working usually requires creating DNS records, and coordinating with existing mail servers, which will be the main constraint on your setup. Instead this guide provides a brief overview of how the integration works, and where the connection points are that you likely need to work on.

=== Sending Mail ===

RT only knows how to send mail by passing it off to another program on the system. It cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail configuration options to send mail through different commands] if you need.

The most common setup is to install and configure a proper Mail Transfer Agent (MTA) like Postfix or Exim, and then configure it to send mail to the wider Internet as you need. This works well because the MTAs are robust and well-tested; they have flexible configuration to let you send mail out by relaying to other mail servers you specify with optional authentication; and most distributions install one by default anyway. The only hard part is configuring the MTA to send mail following your site’s policies.

Other software is available that provides a slimmer version of the <code>sendmail</code> command that connects to an external mail server for you, like msmtp. These programs are usually easier to configure than an MTA, but they often lose email permanently if they can’t connect to the external server at the time it’s sent. (MTAs keep email queued locally until they successfully deliver it to another server.)

=== Receiving email ===

RT installs a command called <code>rt-mailgate</code> that receives an email on standard input and posts it to RT’s REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.

The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example <code>/etc/aliases</code> entries look like:

<pre>rt: "|/opt/rt5/bin/rt-mailgate --queue general --action correspond --url https://rt.yourdomain.example.com/"
rt-comment: "|/opt/rt5/bin/rt-mailgate --queue general --action comment --url https://rt.yourdomain.example.com/"</pre>
This works well because, again, you’re probably running an MTA anyway; and the MTA can hold and queue mail if it comes in while RT is down for any reason, giving you a buffer against downtime.

Another common option is to periodically run a tool that fetches mail using a protocol like IMAP, like fetchmail or getmail, and passes it on to <code>rt-mailgate</code>. This is less common because it requires setting up another tool to run, and securely storing another set of mail server credentials. But it is useful when local policy prevents the RT server from receiving email directly.

This is much less common, but it might help to know that <code>rt-mailgate</code> doesn’t have to run on the same system as RT itself. It just needs to be able to connect to RT’s web interface. If you don’t have any other options, you can install the RT software on a different system that receives email, and configure ''that'' system to run <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
1 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
50 3 * * * rt /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon rt /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * rt /opt/rt5/sbin/rt-email-digest -m daily
</pre>

== Set up RT ==

If you’ve gotten this far, congratulations, your RT install is really done now. You can start setting up RT with users, groups, queues, and business logic. [[Main Page|Head back to the main page]] to start exploring those topics.

User talk:Bkembree

2022-05-20T17:15:02Z

Jbrandt: Welcome!

'''Welcome to ''Request Tracker Wiki''!'''
We hope you will contribute much and well.
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].
Again, welcome and have fun! [[User:Jbrandt|Jbrandt]] ([[User talk:Jbrandt|talk]]) 13:15, 20 May 2022 (EDT)

User:Bkembree

2022-05-20T17:15:02Z

Jbrandt: Creating user page for new user.

This is my personal bio information.

ManualEmailConfig

2022-05-19T17:27:50Z

Jbrandt:

Prev: [[ManualApacheConfig]] --- Up: [[UserManual]] --- Next: [[ManualBasicAdministration]]

----

= SETTING UP THE MAIL GATEWAY =

The mail gateway is used to receive mail messages '''into''' an RT instance; outbound mail is usually just handed off to the local SMTP sending program, or a specified SMTP smarthost.

The mail gateway requires the web UI to be set up and functional. If you intend to use SSL to secure your mail gateway, you need to make sure that lib-www-perl, a.k.a LWP, is built with SSL support.

1) Documentation for setting up the mail gateway can be found at:

https://docs.bestpractical.com/rt/latest/rt-mailgate.html

2) You need to tell your Mail Transfer Agent (e.g. sendmail, postfix, or qmail) how to forward messages to RT's mail gateway. To do this, create an aliases in your system's mail aliases file. Here's an example, which routes mail to the mailbox [=[mailto:rt@example.com rt@example.com]] (and [=[mailto:rt-comment@example.com rt-comment@example.com]]) into new tickets in the RT queue named '''General'''. Note that the queue name is case-insensitive.

Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://localhost/rt"
rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://localhost/rt"
(Replace /opt/rt4 by your RT installation path and http://localhost/rt by the URL of your RT installation on your webserver)

'''NOTE:''' When you add the above each alias entry should be all one line; make sure you include the quotes.

'''NOTE:''' <code>qmail</code> users should follow the [[QMail]] link to review caveats about <code>fastforward</code> command aliases.

Replace '''general''' with the name of your queue and '''rt''' (before the colon in the alias) with the email address you wish people to send their messages to. You might, for example, have messages to '''support''' go into the '''service''' queue, and '''abuse''' go into the '''ops''' queue. You can have more than one set of aliases point to the same queue, if, for example, you wanted mail to both '''abuse''' and '''security''' both go to the '''ops''' queue.

The queue name may have spaces. <code>rt-mailgate</code> works as well with them, but do not forget to escape these spaces by enclosing the queue name in single quote:
my-queue: "|/opt/rt4/bin/rt-mailgate --queue 'My Queue' --action correspond --url http://localhost/"
If you are using the default sendmail included in most redhat distro's you will most likely need to copy (cp) rt-mailgate to /etc/smrsh or create a symbolic link and change /opt/rt4/bin above to /etc/smrsh or sendmail will complain. These sendmails will only execute programs as alias targets which have been blessed by placing them in a special directory. This is not necessary for Exim or postfix.

You'll choose from "--action correspond" and "--action comment" depending on whether the mail should be resent to the requestor. If you want the requestor to see it, choose correspond; if you want to keep it from the requestor, choose comment.

The URL will be the URL for RT's web interface, such as http://issues.bestpractical.com/, [http://fsck.com/rt/ =]; whatever is the root of your RT install.

3) Stop and start your mail server, so it picks up your configuration changes. With sendmail or postfix (possibly others), you usually also need to type the command "newaliases" to get the server to recognize the new aliases. If this command is unrecognized, it's probably not in your default path; a common location is "/usr/sbin/newaliases".

You '''can''' have the mail gateway on your MX or some other server and have it talk to RT via HTTP. For more details, see [[InstallMailgateOnly]].

To configure a mail transfer agent (postfix) to post tickets to RT4 on a separate server ....

Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
rt: "|/<path-to-mailgate>/rt-mailgate --queue general --action correspond --url http://<the-URL-of-the-RT-server>/"
rt-comment: "|/<path-to-mailgate>/rt-mailgate --queue general --action comment --url http://<the-URL-of-the-RT-server>/"
The link to RT is now configured. However, the rt-mailgate script is a perl script which requires support. On a fresh [[SuSE]] 9.3 server install, the following was needed to provide the necessary perl libraries (someone with deeper knowledge may know of a more restrictive set of libraries, but these worked).

#(install gcc and glibc, if necessary)
perl -MCPAN -eshell (to configure CPAN)
perl -MCPAN -e 'install("LWP")'
perl -MCPAN -e 'install("Bundle::LWP")'

If Using SSL, add:
perl -MCPAN -e 'install("Crypt::SSLeay")'
To test the connection...
echo 'hello' | mail -s "Test subject" rt
If you get a "command died with status 1" error message, the rt-mailgate script possibly doesn't have the execute bit set for the user/group under which postfix is running.
chmod o+x /<path-to-mailgate>/rt-mailgate
For more information on configuring your mail gateway, see [[ManualAdministration]]

= Using Fetchmail/Getmail For Incoming Email =

Fetchmail or Getmail can be used to fetch email from a inbox using IMAP or POP. An example configuration for Fetchmail can be seen below:

set daemon 0
# PID files are more useful for forking systemd services. But fetchmail will
# always write one. Since the service runs fetchmail as the apache user,
# www-data, we need to give fetchmail a path that it has write permission to.
#set pidfile '/opt/rt4/var/run/fetchmail-rtir.pid'
poll "IP_OF_MAIL_SERVER" proto imap port 993
user "rt@mycompany.com" password "password"
ssl
folder 'Inbox'
# Some IMAP servers generate an error like this:
#
# could not decode BASE64 challenge
#
# This might be because the server is configured to expect
# certain authentication attempt types, first. fetchmail also
# tries certain authentication methods first, but not password,
# even with the 'password' keyword.
#
# The 'auth' keyword tells fetchmail to attempt the given
# authentication type, first. That can eliminate initial
# authentication failures, which might eliminate this error
# messgae
# IMAP supports flags on individual messages to indicate the
# message status. The 'Seen' flag indicates that the message has
# been read by a client. This could be a webmail client like Gmail
# our Outlook, or fetchmail. The RT use case for fetchmail expects
# that fetchmail will get all mail that hasn't been delivered to
# RT, regardless of whether other clients have seen it. Without
# this option, fetchmail will only download mail from an IMAP
# server without the 'Seen' flag. This option tells fetchmail to
# ignore 'Seen' flags and download all messages.
# fetchall
mda '/opt/rt4/bin/rt-mailgate --url https://rt.mycompany.com --queue "support" --action correspond'
idle
Lastly you will need a cronjob to pull your inbox periodically
`*/1 * * * * root /usr/bin/getmail --fetchmailrc /opt/rt4/etc/fetchmailrc --quiet`

If you use MS Office 365 or Google (Gmail) for email, basic authentication (username/password) is no longer allowed. See [[Integrating_RT_Email_with_Google_Mail_(Gmail)]] for details on setting up getmail. [https://metacpan.org/pod/App::wsgetmail App-wsgetmail] is an option for fetching email from MS Office 365.

----
Prev: [[ManualApacheConfig]] --- Up: [[UserManual]] --- Next: [[ManualBasicAdministration]]
[[Category:RT User Manual]]
[[Category:RT44]]

Integrating RT Email with Google Mail (Gmail)

2022-05-19T15:42:51Z

Jbrandt:

== Retrieving email from a Google Mailbox ==

The utility [https://pyropus.ca/software/getmail/ getmail] version 5.6 and later comes with a script <code>getmail-gmail-xoauth-tokens</code> which can be used to set up the required OAuth2 configuration to fetch email. The steps for setting up this configuration are described below, starting with configuration in Google.

=== Set up OAuth2 client in Google ===

To run getmail on an RT server, set it up as a "Desktop App", one of the options noted in the [https://developers.google.com/identity/protocols/oauth2/native-app Google documentation]. Following instructions on that page, keeping the following notes in mind:

* Enable the "Gmail API" as noted in the docs.
* On the "OAuth consent screen" create, select "Internal" user type, add scope: "Gmail API .../auth/gmail.modify Read, compose, and send emails from your Gmail account"
* On client id create, set the application type to "Desktop app"

Save the provided "Client ID" and "Client secret" values. These are needed in the next step.

=== Set up getmail on RT server ===

The following are based on [https://www.bytereef.org/howto/oauth2/getmail.html Stefan Krah's notes], with a few updates.

1. Get the initial OAuth2 token

Create /home/user/.getmail/gmail.json

{"scope": "https://mail.google.com/",
"user": "your_account@gmail.com",
"client_id": "xzy.apps.googleusercontent.com",
"client_secret": "foo",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"redirect_uri": "http://localhost/",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"}

Fill "client_id" and "client_secret" with the real values from the previous step.

Note that redirect_uri "urn:ietf:wg:oauth:2.0:oob" no longer works. You need to give it a URL, which Google will redirect to once you approve the access.

chmod 600 /home/user/.getmail/gmail.json

Then run:

getmail-gmail-xoauth-tokens --init /home/user/.getmail/gmail.json

This outputs a Google URL and a prompt will wait for a token. Go to that URL and approve it as "your_account@gmail.com". It will then redirect to a URL like:

http://localhost/?code=A-VERY-LONG-STRING&scope=https://mail.google.com/

Copy the URL and extract the code value, then paste it in the <code>getmail-gmail-xoauth-tokens</code> prompt that is waiting. Hit Return and <code>getmail-gmail-xoauth-tokens</code> should quit silently.

2. Configure getmail to retrieve email

The following is similar to a standard getmail configuration.

Create /home/user/.getmail/getmailrc:

[retriever]
type = SimpleIMAPSSLRetriever
server = imap.gmail.com
username = your_account@gmail.com
use_xoauth2 = True
password_command = ("getmail-gmail-xoauth-tokens", "/home/user/.getmail/gmail.json")

[destination]
type = MDA_external
path = /opt/rt5/bin/rt-mailgate
user = root
group = root
arguments = ("--url", "http://localhost", "--queue", "General", "--action", "correspond",)

[options]
read_all = false

Test it:

/usr/bin/getmail --rcfile=/home/user/.getmail/getmailrc

Then edit /etc/cron.d/rt to fetch mail regularly:

*/3 * * * * user /usr/bin/getmail --rcfile=/home/user/.getmail/getmailrc --quiet

== Sending email via Google SMTP ==

For RT, we usually configure postfix to relay to Google via SMTP. For this to work, you need to allow the RT server to send via your Google account. See the [https://support.google.com/a/answer/2956491 Google documentation], along with the following notes:

* In step 6 (Allowed senders section), choose "Only addresses in my domains"
* In step 7 (Authentication section), choose "Only accept mail from the specified IP addresses". do not choose "Require SMTP Authentication"
* In step 8 (Add allowed IP), add public IP address of RT server

Turn on sender envelope in RT site config:

Set( $SetOutgoingMailFrom, 1 );

Integrating RT Email with Google Mail (Gmail)

2022-05-19T14:31:48Z

Jbrandt: Jbrandt moved page Set Up RT With Gmail to Integrating RT Email with Google Mail (Gmail) without leaving a redirect

== Incoming emails ==

Assuming "your_account@gmail.com" is RT's correspond address:

Set( $CorrespondAddress, 'your_account@gmail.com' );

=== Using getmail 5.6+ to fetch emails ===

==== Set up OAuth2 client on google side ====

Based on https://developers.google.com/identity/protocols/oauth2/native-app, here are some notes:

Enable "Gmail API"

On "OAuth consent screen" create, select "Internal" user type, add scrop: "Gmail API .../auth/gmail.modify Read, compose, and send emails from your Gmail account"

On client id create, set the application type to "Desktop app"

Save the "Client ID" and "Client secret" values, which we will need in the next step.

==== Setup getmail on RT server ====

Based on https://www.bytereef.org/howto/oauth2/getmail.html

1. Get initial OAuth2 token

Create /home/user/.getmail/gmail.json

{"scope": "https://mail.google.com/",
"user": "your_account@gmail.com",
"client_id": "xzy.apps.googleusercontent.com",
"client_secret": "foo",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"redirect_uri": "http://localhost/",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"}

Fill "client_id" and "client_secret" with the real values from previous step.

Note that redirect_uri "urn:ietf:wg:oauth:2.0:oob" does '''not''' work any more, we need to give it a URL, which google will redirect to once user approves the access.

chmod 600 /home/user/.getmail/gmail.json

Then run command:

getmail-gmail-xoauth-tokens --init /home/user/.getmail/gmail.json

It outputs a google URL, go to that URL and approves it as "your_account@gmail.com", which will redirects to URL like:

http://localhost/?code=A-VERY-LONG-STRING&scope=https://mail.google.com/

Copy the code value from URL and paste it to the previous getmail-gmail-xoauth-tokens command window, then hit "Return".
If everything goes well, getmail-gmail-xoauth-tokens shall quit silently.

2. Fetch emails

Create /home/user/.getmail/getmailrc

[retriever]
type = SimpleIMAPSSLRetriever
server = imap.gmail.com
username = your_account@gmail.com
use_xoauth2 = True
password_command = ("getmail-gmail-xoauth-tokens", "/home/user/.getmail/gmail.json")

[destination]
type = MDA_external
path = /opt/rt5/bin/rt-mailgate
user = root
group = root
arguments = ("--url", "http://localhost", "--queue", "General", "--action", "correspond",)

[options]
read_all = false

Test it:

/usr/bin/getmail --rcfile=/home/user/.getmail/getmailrc

Then edit /etc/cron.d/rt to fetch mail regularly:

*/3 * * * * user /usr/bin/getmail --rcfile=/home/user/.getmail/getmailrc --quiet

== Outgoing emails ==

=== Route through Google ===

Based on https://support.google.com/a/answer/2956491, here are a few extra notes:

In step 6(Allowed senders section), choose "Only addresses in my domains"
In step 7(Authentication section), choose "Only accept mail from the specified IP addresses", do '''not''' choose "Require SMTP Authentication"
In step 8(Add allowed IP), add public IP address of RT server

Turn on sender envelope in RT site config:

Set( $SetOutgoingMailFrom, 1 );

Videos

2022-02-04T13:54:40Z

Jbrandt: /* Four Part Intro Series from SNAFU */

Some great videos are available, some by Best Practical and some by RT users.

== RT ==

=== Four Part Intro Series from SNAFU ===

* [https://youtu.be/ZO_uVLsWXiE Part 1: Basic Intro]
* [https://youtu.be/YCYL8eGmXlE Part 2: Working on Tickets]
* [https://youtu.be/G8GRftBTndE Part 3: Bulk Updates and Merging]
* [https://youtu.be/7ltRWqm-TSI Part 4: Updating Tickets, Navigation, Your Signature]
* [https://youtu.be/z2gix30KRqo Part 5: Ticket Triage]

=== University of Washington Tips and Tricks ===

* [https://www.youtube.com/watch?v=YD1fSE105Bc University of Washington RT Tips and Tricks]

=== Best Practical Videos ===

* [https://www.youtube.com/watch?v=aBwYK1a8W7U Attachment Handling]
* [https://www.youtube.com/watch?v=45q3edmNz0s Default Ticket Values]
* [https://www.youtube.com/watch?v=2_F2G6D6BxQ Asset Management in RT]
* [https://www.youtube.com/watch?v=gGKWOxb0nIQ Managing SLAs]
* [https://www.youtube.com/watch?v=sGtKCYLBHHw Automatic Assignment]
* [https://www.youtube.com/watch?v=yQa44O3EwvM&t=1s Introduction to Request Tracker]
* [https://www.youtube.com/watch?v=xyBjOURBsOs&t=567s Creating a new queue in RT]

== RTIR ==

* [https://www.youtube.com/watch?v=we8nDQozeCU RTIR Tour]

ManualInstallation

2021-11-04T19:12:41Z

Jbrandt: /* Set up RT */

Prev: [[ManualRequirements]] — Up: [[UserManual]] — Next: [[ManualApacheConfig]]

This guide walks you through installing RT from source on a modern, popular Linux distro. Specifically, that means a distribution based on Debian or Red Hat that’s been released since around 2020.

This guide assumes:

* You can install packages generally available in Debian/Ubuntu or Red Hat/Fedora/CentOS.
* You want to install RT, and all of its Perl dependencies, from source to get the latest versions. (This is a trade-off. It means the boundaries of your install will be very clear, but you won’t get security updates for RT or Perl modules from your distribution.)
* You are willing to install a couple of extra tools to manage the RT installation similarly to how you would in other packaging systems (like PyPI, npm, etc.).
* You are willing to do a relatively maximal install of RT, enabling all the options during installation and then setting what you need in the configuration. (You could save a little space and time by being pickier about your options, but then that complicates the guide and makes it harder to turn those options on later if you want.)
* You are using a regular user account on the Linux system that can get superuser privileges with sudo.

== Install the base dependencies ==

These are required by RT, either to run or to install the dependencies.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, nobody has written a policy for RT.)

== Install a database ==

You need access to a database server. It can be remote, or you can install a database server alongside RT. RT supports a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

If you want to install a fresh PostgreSQL database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

In order to set up RT’s database, you will need a PostgreSQL superuser account that can be authenticated with a password. If you don’t have that, you can create it by running:

<pre>sudo createuser -sP rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Installing the PostgreSQL client libraries ===

These are required for RT to be able to talk to any PostgreSQL server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

If you want to install a fresh MariaDB database server alongside RT:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

In order to set up RT’s database, you will need a MySQL superuser account. To stay consistent with PostgreSQL, I suggest setting a password for it. You can do that by running:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
Record your passphrase; you’ll need it later.

=== Adjust MariaDB’s max_allowed_packet setting ===

You need to consider this step whether you install the database locally, or use an existing one already running. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> setting] functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

These are required for RT to be able to talk to any MariaDB server.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

Download the latest source code using the link on the [https://bestpractical.com/download-page RT download page], extract it using <code>tar -xf</code>, and <code>cd</code> into the source code directory to run the rest of the commands in this section. For example:

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

This command will detect some information about your system in order to install RT properly, and decide which set of dependencies to install. Here’s what the different parts of our command are doing:

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Install RT and its Perl dependencies ===

This command will download, build, and install all of the Perl modules necessary to run RT with the configuration you set above. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps install RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</pre>
If it works, the command will eventually output a message that says “Congratulations. RT is now installed.” followed by instructions about configuring and setting up the database. We’ll do that next.

=== Configure RT ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
# Single-quote all values EXCEPT the special value `undef`
# that turns off a setting.

# rtname appears in ticket email subjects. It needs to be globally unique,
# so use your organization's domain name.
Set($rtname, 'EDIT WITH yourdomain.example.com');
# Organization is used in the database for ticket links, etc. It also needs to
# be globally unique, so use your organization's domain name.
Set($Organization, 'EDIT WITH yourdomain.example.com');
# WebDomain is domain name of the RT web server. RT uses it to construct links
# and defend against CSRFs.
Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com');
# WebPort is the port where the RT web server runs. Edit the number below if
# you're not using the standard HTTPS port.
Set($WebPort, '443');

# DatabaseUser is the name of the database account RT uses to read and store
# data. 'rt_user' is the default but you can change it if you like.
# DO NOT use the 'rt_admin' superuser created in the instructions above.
Set($DatabaseUser, 'rt_user');
# DatabasePassword is the password for DatabaseUser.
Set($DatabasePassword, 'EDIT WITH SomePassphraseHere');
# DatabaseHost is the hostname of the database server RT should use.
# Change 'localhost' if it lives on a different server.
Set($DatabaseHost, 'localhost');
# DatabasePort is the port number of the database server RT should use.
# `undef` means the default for that database. Change it if you're not
# using the standard port.
Set($DatabasePort, undef);
# DatabaseName is the name of RT's database hosted on DatabaseHost.
# 'rt5' is the default but you can change it if you like.
Set($DatabaseName, 'rt5');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# Turn off optional features that require additional configuration.
# If you want to use these, refer to the RT_Config documentation for
# instructions on how to set them up.
Set(%GnuPG, 'Enable' => '0');
Set(%SMIME, 'Enable' => '0');

# Perl expects to find this 1 at the end of the file.
1;
</pre>
<code>RT_SiteConfig.pm</code> is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== Set up RT’s database ===

RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.

(The instructions from <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> option.
* '''If''' you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

Fulltext indexing speeds up searches for ticket content, which makes RT a lot nicer to use.

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== Set permissions ===

All of RT’s configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

If everything has gone well, then you should be able to set a password for RT’s <code>root</code> user. You’ll use this later to log in to the web interface and continue setting up your system. Run:

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== Verify the web interface ===

You should be able to visit your web server in your browser, and be presented with RT’s login screen. You should be able to log in with username <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== Set up RT’s mail server ==

RT both can both send and receive ticket updates via email. Unfortunately, there are too many variables to document a useful setup process here: getting this working usually requires creating DNS records, and coordinating with existing mail servers, which will be the main constraint on your setup. Instead this guide provides a brief overview of how the integration works, and where the connection points are that you likely need to work on.

=== Sending Mail ===

RT only knows how to send mail by passing it off to another program on the system. It cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail configuration options to send mail through different commands] if you need.

The most common setup is to install and configure a proper Mail Transfer Agent (MTA) like Postfix or Exim, and then configure it to send mail to the wider Internet as you need. This works well because the MTAs are robust and well-tested; they have flexible configuration to let you send mail out by relaying to other mail servers you specify with optional authentication; and most distributions install one by default anyway. The only hard part is configuring the MTA to send mail following your site’s policies.

Other software is available that provides a slimmer version of the <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. These programs are usually easier to configure than an MTA, but they often lose email permanently if they can’t connect to the external server at the time it’s sent. (MTAs keep email queued locally until they successfully deliver it to another server.)

=== Receiving email ===

RT installs a command called <code>rt-mailgate</code> that receives an email on standard input and posts it to RT’s REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.

The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example <code>/etc/aliases</code> entries look like:

<pre>rt: "|/opt/rt5/bin/rt-mailgate --queue general --action correspond --url https://rt.yourdomain.example.com/"
rt-comment: "|/opt/rt5/bin/rt-mailgate --queue general --action comment --url https://rt.yourdomain.example.com/"</pre>
This works well because, again, you’re probably running an MTA anyway; and the MTA can hold and queue mail if it comes in while RT is down for any reason, giving you a buffer against downtime.

Another common option is to periodically run a tool that fetches mail using a protocol like IMAP, like fetchmail or getmail, and passes it on to <code>rt-mailgate</code>. This is less common because it requires setting up another tool to run, and securely storing another set of mail server credentials. But it is useful when local policy prevents the RT server from receiving email directly.

This is much less common, but it might help to know that <code>rt-mailgate</code> doesn’t have to run on the same system as RT itself. It just needs to be able to connect to RT’s web interface. If you don’t have any other options, you can install the RT software on a different system that receives email, and configure ''that'' system to run <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== Set up RT ==

If you’ve gotten this far, congratulations, your RT install is really done now. You can start setting up RT with users, groups, queues, and business logic. [[Main Page|Head back to the main page]] to start exploring those topics.

User

2021-09-01T13:09:12Z

Jbrandt:

An RT user is identified by their e-mail address and a username. Each user is also assigned an id by RT, but this id is typically hidden in the RT interface and is not usually used directly.

A user with the '''Let this user access RT''' is an active user, meaning they can login (if they have a password) and perform actions in RT. Uncheck this option to disable the user account.

Selecting the checkbox 'Let this user be granted rights (Privileged)' on the user administration page makes a user [[Privileged]]. It is also possible to set various configuration options to make new users Privileged when they are created. Privileged users can access the full web interface and can see and modify objects in RT based on their [[Rights]].

If you leave this checkbox unchecked, the user is [[Unprivileged]]. They can still log in if they have a password and they will see the [[SelfService]] interface.

A user can be a member of a [[Group]].

A user with the global user right [[SuperUser]] can do anything.

Privileged

2021-09-01T13:05:34Z

Jbrandt:

The group '''Privileged''' is one of the three groups for which RT manages the membership automatically. The other two are [[Unprivileged]] and [[Everyone]]. Every user is either a member of the Privileged group or of the Unprivileged group. Membership in the Privileged group means a user will see the normal RT web interface when logging in and not the more limited self service interface.

Selecting the checkbox 'Let this user be granted rights (Privileged)' on the user administration page makes a user Privileged. It is also possible to set various configuration options to make new users Privileged when they are created.

Put simply:

* Unprivileged -> User sees [[SelfService]] interface when logging in
* Privileged -> User see the regular RT interface (RT at a glance homepage, etc.)

SelfService

2021-09-01T13:00:12Z

Jbrandt:

The [[SelfService]] interface is available for [[Unprivileged]] users who have been given a password to login. You can configure RT to automatically generate a password for users by following the directions in the [[AutogeneratedPassword]] node.

The [[SelfService]] interface only lists tickets for which the logged in user is a [[Requestor]]. If you wish for users to also see tickets for which they are [[CC]] or [[AdminCC]], see [[OnCreateSetDeptHeadCc]].

Example: A department manager may be made Cc on all tickets created by her staff so that she can see what issues are currently active in her department.

The [[SelfService]] interface is accessible by appending "SelfService" the end of your RT Web site URL. For example, if your RT web interface is setup at http://support.mycompany.com, the SelfService interface would be at http://support.mycompany.com/SelfService/.

Unprivileged

2021-09-01T12:56:25Z

Jbrandt:

The group '''Unprivileged''' is one of the three groups for which RT manages the membership automatically. The other two are [[Privileged]] and [[Everyone]]. Every user is either a member of the Privileged group or of the Unprivileged group.

Unchecking the checkbox 'Let this user be granted rights (Privileged)' checkbox on the user administration page makes a user Unprivileged. In a default RT configuration, new users are created Unprivileged, as when an email comes in and a new user account is automatically created.

Unprivileged users get access to the [[SelfService]] interface, which is limited to pages under ''/SelfService/''.

Privileged

2021-09-01T12:48:08Z

Jbrandt:

The group '''Privileged''' is one of the three groups for which RT manages the membership automatically. The other two are [[Unprivileged]] and [[Everyone]]. Every user is either a member of the Privileged group or of the Unprivileged group. Membership in the Privileged group means a user will see the normal RT web interface when logging in and not the more limited self service interface.

Selecting the checkbox 'Let this user be granted rights (Privileged)' checkbox on the user administration page makes a user Privileged. It is also possible to set various configuration options to make new users Privileged when they are created.

Put simply:

* Unprivileged -> User sees [[SelfService]] interface when logging in
* Privileged -> User see the regular RT interface (RT at a glance homepage, etc.)

ManualRights

2021-02-18T18:29:47Z

Jbrandt:

Prev: [[ManualAdministration]] --- Up: [[UserManual]] --- Next: [[ManualScrips]]

[[File:Global-Group-Rights.png|Global group rights|thumb|500px]]

'''Appendix 2 Rights'''

This is a reference for rights in RT.

There are a great deal of places in RT where you can assign rights to a group or a user. While this is a feature of RT, we recommend adding users to a group, then applying rights directly on that group. When rights are granted on specific users, it can become more challenging to manage each user's rights.

Below is a list of all the areas in RT to update group and user rights. From the Admin menu:

* Custom Fields
:* Custom Fields > Select > [select custom field] > Group Rights
:* Custom Fields > Select > [select custom field] > User Rights
:* Global > Custom Fields > [select Users, Groups, Queues, Tickets, Articles, Assets] > [select custom field] > Group Rights
:* Global > Custom Fields > [select Users, Groups, Queues, Tickets, Articles, Assets] > [select custom field] > User Rights

[[File:Queue-Group-Rights.png|Queue level rights by group|thumb|500px]]

* Groups
:* Groups > Select > [select group] > Group Rights
:* Groups > Select > [select group] > User Rights
:* Global > Group Rights

* Queues
:* Queue > Select > [select queue] > Group Rights
:* Queue > Select > [select queue] > User Rights

* Users (not suggested)
:* Global > User Rights

See also [[Rights]] article.

If you have an RT with existing rights set up and you are trying to find which of the above was used to grant them, you can use the Rights Inspector. This tool is available as an [https://metacpan.org/pod/RT::Extension::RightsInspector extension] for RT 4.4 and it is a core feature starting in RT 5.0.

----

Prev: [[ManualAdministration]] --- Up: [[UserManual]] --- Next: [[ManualScrips]]
[[Category:RT User Manual]]
[[Category:RT44]]

User talk:Ajtast

2019-12-13T14:04:39Z

Jbrandt: Welcome!

'''Welcome to ''Request Tracker Wiki''!'''
We hope you will contribute much and well.
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].
Again, welcome and have fun!
[[User:Jbrandt|Jbrandt]] ([[User talk:Jbrandt|talk]])
09:04, 13 December 2019 (EST)

User:Ajtast

2019-12-13T14:04:39Z

Jbrandt: Creating user page for new user.

Perl coder in deepest darkest cornwall

REST

2019-05-02T17:10:00Z

Jbrandt:

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, the REST 1.0 interface has not changed in any significant way in 4.x.

This page is for REST version 1.0. The next version of the RT REST interface, version 2.0, is available as an [https://metacpan.org/pod/RT::Extension::REST2 extension].

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server

You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

'''fields'''

A list of fields you would like included in the result set.

Example:
<code>/REST/1.0/search/ticket?query=id=42&format=l&fields=Subject,Status,Priority,CF.\{Category\}</code>

Note that you may need to escape characters like the curly braces for CFs.

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

==== Ticket Merge ====
To merge tickets: POST on "<code>/REST/1.0/ticket/<origin-ticket-id>/merge/<into-ticket-id></code>". (I don't think any content is required, but I send "id" and "into" anyway.)

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===

* History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).

* Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.

* Comments in response body starts with with a hash (<code>#</code>) symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/rt-client rt-client]
|[https://github.com/uidzip/rt-client GitHub]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/Rickerd0613/rtapi rtapi]
|[https://github.com/Rickerd0613/rtapi GitHub]
|<code>pip install rtapi</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/z4r/python-rtkit GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://github.com/CZ-NIC/python-rt python-rt]
|[https://github.com/CZ-NIC/python-rt Github]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}

Main Page

2019-05-02T17:07:15Z

Jbrandt:

== RT ==

RT is an open source issue tracking and workflow platform developed and supported by [https://bestpractical.com Best Practical Solutions]. This wiki site is a free resource for the RT community to share ideas, configurations, and customizations to RT, RTIR, and related products.

== About RT Documentation ==

In addition to the information found here, you can find RT's documentation in your install of RT on the server and also [https://bestpractical.com/resources/ on the web at the Best Practical website]. The [https://bestpractical.com/blog Best Practical blog] and the [https://forum.bestpractical.com Community Forum] are also great resources for RT information. Best Practical also offers commercial support services to help get the most out of RT and RTIR.

This site is a [https://en.wikipedia.org/wiki/Wiki wiki], like Wikipedia, which means you can edit it right in your browser. If you use RT and have found it valuable, [[UpdateTheWiki]], post your hints, tricks, tips and tools about how to get the most out of RT. If you currently use RT, please head over to [[RTUsers]] and add yourself and your organization to the user list.

== Getting Started with RT ==

If you're new to RT, start with the [[UserManual]]. We also have a page with [[Videos]] with introductory and more advanced features.

== Current Sections ==

You can go through these pretty much in order if you're starting from scratch, but please plan to spend some quality time with the [[UserManual]] before you try to go live; RT is big and full of tons of features, and you probably can't get your head around all of it in one sitting.

* [[UserManual]]
* [[Demo]]
* [[REST]] API

== Historical Sections ==

RT has been in development for over 20 years, so information on this wiki dates back to many different versions. These sections may contain information on older versions of RT that is no longer completely accurate for modern RT. Pages known to be updated should be moved up to the Current Section.

* [[FAQ]], [[FindingAnswersAboutRT]] and "Common Problems" below.
* [[BugReporting]]
* [[HowToHelp]], [[Translation]]

* [[RTGlossary]] & [[Documentation]]
* [[InstallationGuides]], [[RTTutorials]]
* [[RT Config|RT_Config]] & [[RT SiteConfig|RT_SiteConfig]]

* [[Extensions]] to RT available as installable plugins
* [[Contributions]] by the community to customize RT
* [[RTIR]] RT for Incident Response
* [[RTFM]] RT FAQ Manager

* [[RTHistory]]
* [[InThePress]]
* Customizing with [[CustomizingWithCallbacks|Callbacks]]

=== Common problems ===

* [[CantLocateObject]] - Can't locate object method "new" via package "<code>RT::Handle</code>" at rt3/lib/RT.pm
* [[NoConnectionToSyslog]] - no connection to syslog
* [[NoRecipFound]] - No recipients found. Not sending
* Getting information out of RT3 for [[reporting]] or inclusion elsewhere.
* [[PermissionDenied]] emails|
* Getting RT4.x to play nice with [[certbot]] to obtain free SSL certificates from [http://letsencrypt.org LetsEncrypt].

== Wish lists ==

* [[WikiWishList]] - wish list for this wiki
* [[WishList]] - wish list for the RT
* [[RT3StatisticsPackageWishList]]

== Getting started with MediaWiki ==

To learn more about how to edit wiki pages, click the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents Help] link here or in the navigation on the left.

We have installed the Markdown plugin, so you can edit pages in Markdown.

Several years ago, we moved the wiki from Wikia as noted on the [[Wikia Move]] page.

Main Page

2019-05-02T17:06:21Z

Jbrandt: /* Current Sections */

== RT ==

RT is an open source issue tracking and workflow platform developed and supported by [https://bestpractical.com Best Practical Solutions]. This wiki site is a free resource for the RT community to share ideas, configurations, and customizations to RT, RTIR, and related products.

== About RT Documentation ==

In addition to the information found here, you can find RT's documentation in your install of RT on the server and also [https://bestpractical.com/resources/ on the web at the Best Practical website]. The [https://bestpractical.com/blog Best Practical blog] and the [https://forum.bestpractical.com Community Forum] are also great resources for RT information. Best Practical also offers commercial support services to help get the most out of RT and RTIR.

This site is a [https://en.wikipedia.org/wiki/Wiki wiki], like Wikipedia, which means you can edit it right in your browser. If you use RT and have found it valuable, [[UpdateTheWiki]], post your hints, tricks, tips and tools about how to get the most out of RT. If you currently use RT, please head over to [[RTUsers]] and add yourself and your organization to the user list.

== Getting Started with RT ==

If you're new to RT, start with the [[UserManual]]. We also have a page with [[Videos]] with introductory and more advanced features.

== Current Sections ==

You can go through these pretty much in order if you're starting from scratch, but please plan to spend some quality time with the [[UserManual]] before you try to go live; RT is big and full of tons of features, and you probably can't get your head around all of it in one sitting.

* [[UserManual]]
* [[Demo]]

== Historical Sections ==

RT has been in development for over 20 years, so information on this wiki dates back to many different versions. These sections may contain information on older versions of RT that is no longer completely accurate for modern RT. Pages known to be updated should be moved up to the Current Section.

* [[FAQ]], [[FindingAnswersAboutRT]] and "Common Problems" below.
* [[BugReporting]]
* [[HowToHelp]], [[Translation]]

* [[RTGlossary]] & [[Documentation]]
* [[InstallationGuides]], [[RTTutorials]]
* [[RT Config|RT_Config]] & [[RT SiteConfig|RT_SiteConfig]]

* [[Extensions]] to RT available as installable plugins
* [[Contributions]] by the community to customize RT
* [[RTIR]] RT for Incident Response
* [[RTFM]] RT FAQ Manager

* [[RTHistory]]
* [[InThePress]]
* [[REST]] API
* Customizing with [[CustomizingWithCallbacks|Callbacks]]

=== Common problems ===

* [[CantLocateObject]] - Can't locate object method "new" via package "<code>RT::Handle</code>" at rt3/lib/RT.pm
* [[NoConnectionToSyslog]] - no connection to syslog
* [[NoRecipFound]] - No recipients found. Not sending
* Getting information out of RT3 for [[reporting]] or inclusion elsewhere.
* [[PermissionDenied]] emails|
* Getting RT4.x to play nice with [[certbot]] to obtain free SSL certificates from [http://letsencrypt.org LetsEncrypt].

== Wish lists ==

* [[WikiWishList]] - wish list for this wiki
* [[WishList]] - wish list for the RT
* [[RT3StatisticsPackageWishList]]

== Getting started with MediaWiki ==

To learn more about how to edit wiki pages, click the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents Help] link here or in the navigation on the left.

We have installed the Markdown plugin, so you can edit pages in Markdown.

Several years ago, we moved the wiki from Wikia as noted on the [[Wikia Move]] page.

UpdateTheWiki

2019-04-03T12:51:19Z

Jbrandt:

Updating the wiki is very easy.

== Request an Account ==

There is a link in the upper righthand corner to [[Special:RequestAccount]] which allows you to request an account. Once approved, you can then log in and make updates. (We used to allow self-signup, but the wiki spam was a huge problem so now we approve accounts first.)

== Edit existing pages ==

* Click the Edit link at the top of the page or on any section.
* Edit the page contents and click save.
* If presented with a simple question about RT, answer it. This helps us keep the wiki spam to a minimum.

== Add new pages ==

* Click the edit link on the page where you want to add the first link to the new page.
* Add [[CamelCaseNameOfNewPage]] to the text of the page and click save. ([http://en.wikipedia.org/wiki/CamelCase What's CamelCase?]).
* You should see [[CamelCaseNameOfNewPage]] as a red link.
* Click this link and you will see a create box for the new page.

If name of the new page doesn't match [[CamelCase]] notation, like REST or Ticket use [[REST]] or [[Ticket]].

You can use the following trick as well:

* In the URL string of your browser write https://rt-wiki.bestpractical.com/wiki/NameOfNewPage
* Hit enter and you'll seeing a page that already exists or a page that gives you the option to create a new page. Click the links to do that.
* This trick has a trade-off, as a new page is not linked to from any other page. People can only find it with the search box, so you have to add links later.

Additional information:

* [[WikiWishList]] - wish list for the RT Wiki
* [[LowHangingFruit]] - improvements to wiki formatting which do not require extensive knowledge of RT.

Videos

2019-04-01T12:13:12Z

Jbrandt: Created page with "Some great videos are available, some by Best Practical and some by RT users. == RT == === Four Part Intro Series from SNAFU === * [https://youtu.be/ZO_uVLsWXiE Part 1: Bas..."

Some great videos are available, some by Best Practical and some by RT users.

== RT ==

=== Four Part Intro Series from SNAFU ===

* [https://youtu.be/ZO_uVLsWXiE Part 1: Basic Intro]
* [https://youtu.be/YCYL8eGmXlE Part 2: Working on Tickets]
* [https://youtu.be/G8GRftBTndE Part 3: Bulk Updates and Merging]
* [https://youtu.be/7ltRWqm-TSI Part 4: Updating Tickets, Navigation, Your Signature]

=== University of Washington Tips and Tricks ===

* [https://www.youtube.com/watch?v=YD1fSE105Bc University of Washington RT Tips and Tricks]

=== Best Practical Videos ===

* [https://www.youtube.com/watch?v=aBwYK1a8W7U Attachment Handling]
* [https://www.youtube.com/watch?v=45q3edmNz0s Default Ticket Values]
* [https://www.youtube.com/watch?v=2_F2G6D6BxQ Asset Management in RT]
* [https://www.youtube.com/watch?v=gGKWOxb0nIQ Managing SLAs]

== RTIR ==

* [https://www.youtube.com/watch?v=we8nDQozeCU RTIR Tour]

Main Page

2019-04-01T12:08:32Z

Jbrandt:

== RT ==

RT is an open source issue tracking and workflow platform developed and supported by [https://bestpractical.com Best Practical Solutions]. This wiki site is a free resource for the RT community to share ideas, configurations, and customizations to RT, RTIR, and related products.

== About RT Documentation ==

In addition to the information found here, you can find RT's documentation in your install of RT on the server and also [https://bestpractical.com/resources/ on the web at the Best Practical website]. The [https://bestpractical.com/blog Best Practical blog] and the [https://forum.bestpractical.com Community Forum] are also great resources for RT information. Best Practical also offers commercial support services to help get the most out of RT and RTIR.

This site is a [https://en.wikipedia.org/wiki/Wiki wiki], like Wikipedia, which means you can edit it right in your browser. If you use RT and have found it valuable, [[UpdateTheWiki]], post your hints, tricks, tips and tools about how to get the most out of RT. If you currently use RT, please head over to [[RTUsers]] and add yourself and your organization to the user list.

== Getting Started with RT ==

If you're new to RT, start with the [[UserManual]]. We also have a page with [[Videos]] with introductory and more advanced features.

== Current Sections ==

You can go through these pretty much in order if you're starting from scratch, but please plan to spend some quality time with the [[UserManual]] before you try to go live; RT is big and full of tons of features, and you probably can't get your head around all of it in one sitting.

* [[Demo]]

== Historical Sections ==

RT has been in development for over 20 years, so information on this wiki dates back to many different versions. These sections may contain information on older versions of RT that is no longer completely accurate for modern RT. Pages known to be updated should be moved up to the Current Section.

* [[FAQ]], [[FindingAnswersAboutRT]] and "Common Problems" below.
* [[BugReporting]]
* [[HowToHelp]], [[Translation]]

* [[RTGlossary]] & [[Documentation]]
* [[InstallationGuides]], [[RTTutorials]]
* [[RT Config|RT_Config]] & [[RT SiteConfig|RT_SiteConfig]]

* [[Extensions]] to RT available as installable plugins
* [[Contributions]] by the community to customize RT
* [[RTIR]] RT for Incident Response
* [[RTFM]] RT FAQ Manager

* [[RTHistory]]
* [[InThePress]]
* [[REST]] API
* Customizing with [[CustomizingWithCallbacks|Callbacks]]

=== Common problems ===

* [[CantLocateObject]] - Can't locate object method "new" via package "<code>RT::Handle</code>" at rt3/lib/RT.pm
* [[NoConnectionToSyslog]] - no connection to syslog
* [[NoRecipFound]] - No recipients found. Not sending
* Getting information out of RT3 for [[reporting]] or inclusion elsewhere.
* [[PermissionDenied]] emails|
* Getting RT4.x to play nice with [[certbot]] to obtain free SSL certificates from [http://letsencrypt.org LetsEncrypt].

== Wish lists ==

* [[WikiWishList]] - wish list for this wiki
* [[WishList]] - wish list for the RT
* [[RT3StatisticsPackageWishList]]

== Getting started with MediaWiki ==

To learn more about how to edit wiki pages, click the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents Help] link here or in the navigation on the left.

We have installed the Markdown plugin, so you can edit pages in Markdown.

Several years ago, we moved the wiki from Wikia as noted on the [[Wikia Move]] page.

ManualUsingWebInterface

2019-03-28T20:37:12Z

Jbrandt:

Prev: [[ManualBasicAdministration]] --- Up: [[UserManual]] --- Next: [[ManualAdministration]]

----

RT has a web interface that works in just about every web browser - including screen readers for the blind - and is easy to use. How easy? You're about to find out. Remember, though, that RT is very configurable; if you're reading this to learn how to use a local installation at your site, remember that your administrator could have made changes that will make things look differently than they do here; don't let it throw you.

RT has a powerful interface to create queries using [[TicketSQL]], a SQL-like syntax for searching tickets. The output format can also be configured. i.e. which columns to show. This can be configured using the query builder or a plain text input in advanced mode.

If you see any unfamiliar terms in this chapter, look for them in the RT Concepts section of [[ManualIntroduction]], or in [[RTGlossary]].

This manual is being updated to 4.4; we're going to snip out references to things that were markedly different in older -- particularly pre-4.x -- releases. If you have one of those... you '''really''' need to think about upgrading.

= Logging In =

Your administrator will tell you where your login page is, and what username and (usually) temporary password to use. The login screen looks like this:

[[File:RT-Login.png|RT Login Page|thumb|500px]]

Type your username in the Username text box, type your password in the Password text box, and then click the Login button, or hit ENTER.

= RT at a Glance (Home Page) =

Immediately after logging in, you'll be looking at the home page, RT at a Glance.

[[File:RT-at-a-Glance.png|RT at a Glance|thumb|500px]]

'''NOTE:''' You'll find that many items are clickable hotlinks in the RT interface, such as ticket ids and queues, but the default interface configuration does not highlight these using the usual blue color or underline. Move your mouse around; things which are links will get an underline when you hover the mouse over them. Clicking on these items takes you pretty much where you might expect it would.

Also, note that your installation may have been customized by the administrator, and because of that, things may be in different places than we describe here.

The main part of the page, called "RT at a Glance", will contain a collection of panels, each of which can be minimized, and some of which can also be edited.

By default, these are:

== In the left column ==

* 10 highest priority tickets I own: This section displays what you need to do. Each ticket will display its id, subject, queue, and status from this page. Click any ticket's id or description to display its basic information page (see also the [[ManualUsingWebInterface#Tickets_interface|Tickets interface]] section of this chapter).
* 10 newest unowned tickets: Here you'll see the list of tickets which have been created, but not yet assigned to anyone, sorted with the newest ones at the top. Each ticket has an associated '''Take''' link which you can use to assign the ownership of the ticket to yourself, and start working on it.
* Bookmarked tickets: Here is a facility where you can bookmark any ticket while you're looking at it, no matter its queue or owner, by clicking on an empty star in the top right corner of the page. Tickets you've bookmarked in this way will be displayed in this panel.
* Quick Ticket Creation: This panel lets you enter the bare minimum of information about a new ticket, to create one quickly when necessary. If you need to enter more information about a new ticket, including things like [[CCs]], select a queue from the top submenu of the page, and click the "New Ticket In" button; this will give you the complete New Ticket screen.

== In the right column ==

* My Reminders - If you have set a reminder for yourself in a ticket, you will see the title of the reminder and which ticket it belongs to. Click on the title of the reminder to follow it.
* Queue List - This panel contains a list of all the queues you're permitted to access, logged in with the current user account. They're in alphabetical order, and show tickets in each status based on the queue lifecycle.
* Dashboards: The Dashboards panel (see [[ManualDashboards]]) will contain a list of any Dashboards which have been created for the entire RT installation, your user group, or your personally created dashboards.
* Refresh: This pulldown menu, on the lower right side of the screen, lets you select whether the homepage is automatically refreshed or not. The default is no. Other options are refreshing the page every 2, 5, 10, 20, 60, and 120 minutes. Click the Go! button to select the displayed auto-refresh delay.

== Top navigation bar ==

This is the RT main menu. The options will expand into a menu tree as you select various tasks. Your current location in this tree will always be boldfaced. Some of these options may not be displayed if you do not have the appropriate rights.

* Home: the home page: where you are now. You can always get back to the home page by clicking Home in the upper left of the screen. You can even click this if you're '''on''' the home page, as an easy Refresh link.
* Search: clicking this brings you to the ticket search query builder page (see also [[ManualUsingWebInterface#Searching_for_tickets|Searching for tickets]]).
* Reports: This allows you to quickly create reports on tickets Resolved by owner, Resolved in date range or Created in a date range.
* Articles: clicking this takes you to Articles, RT's integrated knowledgebase.
* Assets: Assets allow you to keep an inventory of items that can then be linked to tickets as needed
* Tools: The options here allow you to view your daily progress, check your reminder and view any approvals you may need
* Admin: This link takes administrators to the section of RT where they can configure users, queues and scrips, and make global setup changes to the installation.
* Logged in as: This menu lets you configure RT for your personal tastes. You can also log out of RT here.

== Top submenu ==

* New ticket in: Use this to quickly start creating a ticket (for more detail, see [[ManualUsingWebInterface#Creating_a_new_ticket|Creating a new ticket]]). Choose a queue from the drop-down menu and click the "New ticket in:" button to begin.
* Search: Type a search term in the text box and click the Search button to find tickets. This box can do some magic, for example you can type in a ticket id, and jump directly to that ticket. Check out [[ManualSimpleSearch]] for more on the magic and [[ManualSearchTickets]] for more ways to search tickets.

= Tickets interface =

The fundamental object in RT is the ticket; a ticket groups all of the information about, and transactions related to, an issue you're using RT to track.

First, you should know some of the various ways to navigate to an existing ticket:

* from the Home page, click a ticket subject under '''10 highest priority tickets I own''' or '''10 newest unowned tickets'''. Or, you can '''Take''' an unowned ticket, which has the extra side effect of assigning ownership to you.
* search for a ticket, from the search box on the Home page or by clicking Search in the top navigation bar, then click on the ticket.
* click a queue name on the Queue List panel and then click a ticket.
* clicking a ticket's URL from within an email message.

= Display =

Any way you navigate to a ticket, you'll arrive at that ticket's Display page first.

The Display view, the first of many possible views of the ticket, (see screenshot) provides an overview of the ticket.

[[File:Ticket-Display.png|Ticket Display Page|thumb|500px]]

Two panes come up on the Display view: Ticket Metadata on top, and History below.

As you can see, it includes information like Basics, People, Reminders, Dates, and Links, each in it's own portlet.

The id and subject of the ticket is above the top command bar.

In the upper right corner of the main window, new tickets will offer by default (depending on user rights) the Actions: Reply, Comment, Forward, Open It, Resolve, Reject, Delete, Take, and Extract Article. Reply and Comment will be covered shortly, in the [[ManualUsingWebInterface#Replying_and_commenting|Replying and Commenting]] section. Resolve means to close a ticket because work on it is finished, Open will change a ticket's status to "open", Take makes you the ticket's owner, and Extract Article is part of RT's integration with the knowledgebase Articles.

If anyone owns a ticket, the Take option disappears; likewise, once a ticket is resolved, the Resolve option disappears. If a resolved ticket is reopened with the Open It option, Open It disappears and Resolve reappears.

The Display page sometimes has an Attachments portlet, which lists ticket attachments, organized by name and then by date.

== History ==

This panel on -- or separate view of -- the ticket shows everything that's ever happened to the ticket, including comments, replies, attachments and status and ownership changes.

== Basics ==

[[File:Ticket-Basics.png|Ticket Basics Page|thumb|500px]]

This is where you change the ticket's subject, status, queue, owner, time estimated, time worked, time left, priority, and final priority. A ticket's subject is what it sounds like; "time estimated","time worked" and "time left" refer to the (total) number of minutes worked on this ticket only. If you're unclear on status, queue, owner, or priority, refer to [[ManualIntroduction#RT_concepts|RT Concepts]].

After changing information on the Basics page (or any other), don't forget to click the Save Changes button.

This is also the page where you can change values in a custom field. Your organization may create its own fields, and they come up on a ticket's Basics page. They work like any other field: you type things in them or select things from them. To create your own custom fields, see [[ManualAdministration]].

== Dates ==

[[ManualTicketDates]]

== People ==

To reach a ticket's People screen from within a ticket, click People on top submenu or, alternatively, click on the porlet's tab.

This page deals with a ticket's owner, requestor, Cc(s), Admin Cc(s) and optionally, Custom Roles. To review these roles, see [[ManualIntroduction#RT_concepts|RT Concepts]].

There are two ways to add a watcher. If you know a potential watcher's email address, you can add one directly. Otherwise, you can search for them, then add whoever you've found.

To search for users before adding them as watchers:
<ul>
# look under "Find people whose"
# choose Username, Email, Name, or Organization from the first drop-down menu
# choose matches, doesn't match, is, or isn't from the second drop-down menu
# type your search term in the text box
# click the Go! button
</ul>

If RT finds a user, their username will appear in the Add new watchers area below. You've now found your user, and you're ready to configure them as a watcher.

To search for groups before adding them as watchers:
<ul>
# look under "Find group whose"
# choose Name or Description from the first drop-down menu
# choose matches, doesn't match, is, or isn't from the second drop-down menu
# type your search term in the text box
# click the Go! button
</ul>

If RT finds a group, the group name will appear in the Add new watchers area. You've now found your group, and you're ready to configure it as a watcher.

To add new watchers:
<ul>
# locate the Add new watchers section of the page
# for each watcher you're adding, choose Requestor, Cc, or [[AdminCC]] from the Type drop-down menu
# type the new watcher's email address in the Email text box, if it's not already filled in
# click the Save Changes button
</ul>

For each email address, RT will search for an existing user to match it. If there is no match, RT will create a new unprivileged user.

To remove a watcher:
<ul>
# locate the Current Watchers section of the page
# check the box next to the watcher(s) to delete
# click the Save Changes button
</ul>

To assign a ticket or change its owner:
<ul>
# change Owner drop-down menu to the person of your choice
# click the Save Changes button
</ul>

To change a ticket's owner to yourself, click Take from within a ticket, this only works if the ticket was assigned to Nobody. Once a ticket is taken, the Take option disappears from the ticket's interface. If the ticket already has an owner, you can click "Steal" instead to own it. There is no intermediate "Are you sure you want to do this?" page, but if you wrongly take a ticket, you can always give it back.

==Links ==

Links in RT include Depends on, Depended on by, Parents, Children, Refers to, and Referred to by. If we just lost you, see [[ManualIntroduction#RT_concepts|RT Concepts]].

To reach a ticket's Links page, from within a ticket, click on the Links portlet tab or Links on the ticket submenu.

You can add or delete links here, or merge duplicate tickets. In this screen shot, the links page for ticket #2, you'll see that ticket #2 is a child of parent ticket #3.

[[File:Ticket-Links.png|Ticket Links Page|thumb|500px]]

To merge two identical, duplicate tickets:
<ul>
# look under Merge
# enter only one ticket number in the Merge Into: text box
# click the Submit button
</ul>

If someone tries to use the ticket ID of a ticket you've merged into another one, RT automatically redirects to the correct, newly-merged ticket.

To add a link (Depends on, Depended on by, Parents, Children, Refers to, Referred to by):
<ul>
# look under New Links
# enter ticket numbers (or other data) into the appropriate fields, separating multiple entries with spaces
# click the Submit button
</ul>

To delete a link:
<ul>
# look under Current Links
# check the box next to the link to delete
# click the Submit button
</ul>

To add a link to an Article, see [[ManualUsingWebInterface#Replying_and_commenting|Replying and Commenting]].

== Jumbo ==

This page shows editable versions of the Basics, Dates, People, and Links (and Custom Fields if added) screens on one page, plus Update Ticket fields for adding comments or replies. This screen is useful if you must modify several aspects of a ticket at once. Be sure to click the Save Changes button when you're done.

= Common tasks =

Now that you know your way around RT's web interface, there are probably many tasks you can figure out on your own. However, we wanted to make sure you had a step-by-step guide to the most important and common tasks such as using RT's search functionality and working with tickets.

== Searching for tickets ==

[[ManualSearchTickets]]

== Creating a new ticket ==

To create a new ticket, start by selecting its queue:
<ul>
# from any page, select the queue of your choice from the "New ticket in" drop-down menu on the top right of the screen
# click the New Ticket in button
</ul>
[[File:Ticket-Create.png|Ticket Create Page|thumb|500px]]

The next page will be the Create a new ticket page, defaulting to the Show basics view with the following fields:

* Queue: this should already be filled in for you.
* Status: generally, you'll leave this at the default, new. However, you might sometimes need to create a ticket to record a past occurrence or a problem that's already being worked on, so you might choose one of the other statuses from the drop-down menu.
* Owner: you can give the ticket an owner or leave this blank and let someone claim it later.
* You may also see some Custom Fields here if you created any and applied them to the queue
* Requestors: the default email address will be yours. Fill in any others if needed.
* Cc and Admin Cc: if you don't know what these are for, see [[ManualIntroduction#RT_concepts|RT Concepts]].
* You may also see some Custom Roles here if you created any and applied them to the queue
* Subject and Attach file should look familiar to most email users and work basically the same way.
* Describe the issue below means you should explain why this ticket exists.

If you click Details from the top submenu, you'll be brought to the optional but potentially useful fields Priority, Final Priority, Time Estimated, Time Worked, Time Left, fields for dates (Starts and Due), and fields for each link (Depends on, Depended on by, Parents, Children, Refers to, Referred to by). These, too, are explained in [[ManualIntroduction#RT_concepts|RT Concepts]].

When you're done filling in fields, click the Create button to make the ticket.

== Replying and commenting ==

There are two ways you can respond to a ticket. By default, a reply is public and a comment is hidden from the requestor. Comments and replies are listed permanently under the ticket's History.

To say something about a ticket, first make sure you are within one of the ticket's pages (Display, History, Basics...) then click Comment or Reply in the Actions menu at the upper right of the page. To quote the text of an existing comment or reply inline, click Reply or Comment next to an existing reply/comment, from within the ticket's History (see screenshot).

[[File:Ticket-Txn.png|Reply, Comment or Forward in Ticket History|thumb|500px]]

On the resulting Ticket Update page, you'll see drop-down menus for Status and Owner. You probably won't need to change the defaults here.

There will also be a text box for how many minutes the ticket has been worked on. Fill this in if you want to or if you are supposed to be logging your time.

The Update Type drop-down menu will be automatically set to Comments (Not sent to requestors) or Response to requestors, depending on whether you clicked Comment or Reply as your first step. You can select the other option if you've changed your mind. As a visual aid, the message box will be yellow for comments and red for replies.

As for the other fields, we'll assume you have a working knowledge of email. RT correspondence has some fields that should be familiar to email users, such as Subject, CC, BCC, Attachments, and Message. The Subject field may be automatically filled in with the name of the ticket.

'''NOTE:''' email addresses in the CC and BCC fields of replies and comments will not automatically receive future updates.

Enter your comment or reply in the Message field, and when everything's done, click the Submit button.

You'll be brought back to the ticket's Display page, with a status message on top that says your comment or reply has been sent/recorded, or that there is a problem and it hasn't.

To add a signature that will appear by default at the bottom of all your comments and replies:
<ul>
# click Logged in as -> Settings -> About Me from the top navigation bar
# type your (preferably short) signature in the Signature field
# click the Save Preference
</ul>

=== Reply and comment with Articles ===

[[File:Ticket-Update-Articles.png|Add Articles to Reply/Comment|thumb|500px]]

Articles is RT's knowledgebase system. If you are using Articles, you should know that when you reply to or comment on tickets in RT, you can search for and include (editable) Articles in the reply or comment. The ticket will now have a new link: Refers To (article of your choice). This screen shot shows the relevant part of the Reply or Comment screen, located above the Message box of the page:

To find an Article to include in the reply or comment, enter a search term in the "Search for Articles matching" text box and click the Go button. Assuming there are search results, click the Go button next to the article you'd like to include.

If you know the name or id of the article you'd like to include, enter it in the Include Article text box and click the Go button.

== Modifying a ticket ==

Listed alphabetically by item that could be changed:

* dates:
:# click on the Dates portlet or menu item on ticket display
:# type the new date in the <code>Starts</code> or <code>Due</code> text box, <code>Started</code> and <code>Last Contact</code> can also be manually updated
:# click the Save Changes button
* history: a ticket's history cannot be changed.
* owner:
:# from within a ticket's People page, change <code>Owner</code> in drop-down menu to the person of your choice
:# click the Save Changes button
* priorities:
:# from within a ticket's Basics page, type a new number in the <code>Priority</code>/<code>Final Priority</code> fields
:# click the Save Changes button
* queue:
:# from within a ticket's Basics page, select a new item from the <code>Queue</code> drop-down menu
:# click the Save Changes button
:# '''NOTE:''' that when you change a ticket's queue, queue-specific values such as custom fields will disappear. They will not be deleted, but they will be hidden.
* status:
:# from within a ticket's Basics page, select a value from the <code>Status</code> drop-down menu
:# click the Save Changes button
* subject:
:# from within a ticket's Basics page, type new data in the <code>Subject</code> field
:# click the Save Changes button
* time fields:
:# from within a ticket's Basics page, type a new number in the <code>Time Estimated</code>/<code>Time Worked</code>/<code>Time Left</code> fields
:# click the Save Changes button

== Modifying people ==

To assign a ticket or change its owner:

:# from a ticket's People page, change Owner in drop-down menu to the person of your choice
:# click the Save Changes button

To add new watchers:

:# from a ticket's People page, locate the "Add New Watchers" section of the page
:# choose Requestor, Cc, AdminCc or any Custom Role from the Type drop-down menu
:# type the new watcher's email address in the Email text box
:# add up to two more watchers, for a total of up to three
:# click the Save Changes button

To remove a watcher:

:# from a ticket's People page, locate the Current Watchers section of the page
:# check the box next to the watcher(s) to delete
:# click the Save Changes button

== Modifying Links ==

To add a link (Depends on, Depended on by, Parents, Children, Refers to, Referred to by):

:# from within a ticket's Links page, look under New Links
:# enter ticket ids (or other data) into the appropriate fields, separating multiple entries with spaces
:# click the Save Changes button

To delete a link:

:# from within a ticket's Links page, look under Current Links
:# check the box next to the link to delete
:# click the Save Changes button

To merge a duplicate ticket into an identical ticket:

:# from within a ticket's Links page, look under Merge
:# enter only one ticket id in the Merge Into: text box
:# click the Save Changes button

If someone tries to use the ticket ID of a ticket you've merged into another one, RT automatically redirects to the correct, newly-merged ticket. Merging tickets also merges all ticket data such as watchers, links, and history.

== Updating many tickets at once ==

Sometimes, you may need to make a change to several tickets at once. There's an easy way to do this:
:# locate the tickets you want (see [[ManualUsingWebInterface#Searching_for_tickets|Searching for tickets]])
:# from the results page, click "Bulk Update" from the top submenu
:# you'll be sent to a Bulk ticket update page where you can add a comment or reply to all the tickets, or change the tickets' owner, requestors, Cc, Admin Cc, subject, priority, queue, status, and various date fields. The power!
:# click the Update button

== Resolving a ticket ==

If a ticket has been completed and doesn't need any more work, you can resolve it by clicking Resolve in Actions menu of ticket's pages (Display, History, Basics...).

This takes you to a comment form (see [[ManualUsingWebInterface#Replying_and_commenting|Replying and Commenting]]) but sets the Status drop-down menu to Resolved.

You're encouraged to use the Message text box to explain why you're resolving the ticket.

When you're done, click the Update Ticket button.

You'll be brought to the ticket's Display page and told the comment has been recorded and ticket has been resolved (or not, if there is a problem).

== Changing your own user information ==

[[File:About-Me.png|About Me Page|thumb|500px]]

To change your own name, email address, phone numbers, location, signature or password:

:# in the upper right of the screen, click Logged in as -> Settings -> About Me
:# type new information in the desired fields
:# click the Save Preferences button

'''NOTE:''' You'll need the right "ModifySelf" to view this page and make changes.

== Groups ==

Users can grant their rights to others by creating a group and delegating the rights to the members of that group. This is convenient if you're going on vacation or need to pass the buck for any reason.

To view existing groups, go to Admin -> Groups -> Select -> [select group name]

To make a new group:

:# go to Admin -> Groups -> Create
:# type your group's name and description in the <code>Name:</code> and <code>Description:</code> text boxes
:# click the Create button

To add members to a group:

:# click the name of a group
:# click Members from the top submenu
:# select user(s) or group(s) from the Add members are
:# click the Modify Members button

To delete members from a group:

:# click the name of a group
:# click Members from the top submenu
:# check the box next to the user(s) or group(s) to delete
:# click the Modify Members button

To change a group's name or description:

:# click the name of a group
:# make changes
:# click the Save Changes button

To disable a personal group:

:# click the name of a group
:# clear the Enabled checkbox
:# click the Save Changes button

Unlike disabled users and queues, disabled groups will still be visible in listings. That removes a step from the process of re-enabling them when necessary.

To re-enable a group:

:# click the name of a group
:# check the Enabled checkbox
:# click the Save Changes button

== Rights ==
[[File:Group-Rights.png|Group Rights Page|thumb|500px]]

Once you have a group, you can grant rights.

* In order to delegate rights, you'll need to have the right "ShowConfigTab", which allows you to view the Admin menu in the top navigation bar
* If you've been granted a right globally, you can't delegate it for just one queue and vice versa.

To grant rights to a group:

:# go to Admin -> Global -> Group Rights
:# on the left side of the page, select a system group, role, or user group listed, or search for a group under "Add Group"
:# rights are grouped by "General Rights", "Rights for Staff" and "Rights for Administrators", these are suggested rights, but you may grant whichever from any of the tabs
:# check the box(es) next to the right(s) you'd like to grant
:# click the Save Changes button

To revoke rights on a group:

:# go to Admin -> Global -> Group Rights
:# on the left side of the page, select a system group, role, or user group listed, or search for a group under "Add Group"
:# uncheck the box(es) next to the right(s) you'd like to revoke
:# click the Save Changes button

== Logging out ==

You can leave yourself logged into RT without breaking anything, but logging out is a good habit to get into for security purposes. Logging out is standard:

* click Logged in as -> Logout in the top navigation bar

Some RT configurations don't have a Logout button, so don't panic if you don't see one.

----

Prev: [[ManualBasicAdministration]] --- Up: [[UserManual]] --- Next: [[ManualAdministration]]
[[Category:RT User Manual]]

Ticket

2019-03-28T20:28:33Z

Jbrandt:

A '''Ticket''' (or '''Request''') is a collection of information concerning some subject to be tracked.

RT keeps track of everything that happens to a ticket, including internal discussions and discussions with the originator.

A ticket has the following:

* A [[Requestor]] - the [[User]] that is waiting for the issue to be resolved. In some cases there may be no requestor on a ticket or more than one.

* An [[Owner]] - the [[User]] that is currently responsible for resolving the issue.

* Zero or more [[CC]]s who are treated like co-requestors.

* Zero or more [[AdminCC]]s who are treated like co-owners.

* A Status which tracks where the ticket is in the current workflow. Status and workflow can be customized using RT's [https://docs.bestpractical.com/rt/latest/customizing/lifecycles.html Lifecycle] feature.

* A ticket belongs to a [[Queue]]. A Queue can be used to hold a certain "class" of tickets, e.g. those that should be handled by a particular group of Users.

* A [[Priority]]

* A [[DueDate]], the date it was Created, the LastUpdated date, and the date it was Resolved, if it is complete.

* A record of how much time has been spent on a ticket.

* [[Relationships]] to other tickets as links.

[[Category:RT44]]

Demo

2019-03-28T20:26:21Z

Jbrandt:

If you want to try RT, you can find demonstration sites here:

* http://rt.easter-eggs.org/demos/
* https://demo.bestpractical.com/

[[Category:RT44]]

Category:RT44

2019-03-28T20:24:23Z

Jbrandt: Created page with "The RT44 category contains pages that have been updated after the release of RT 4.4. These categories provide a way to assess how current a page is."

The RT44 category contains pages that have been updated after the release of RT 4.4. These categories provide a way to assess how current a page is.

UserManual

2019-03-28T20:22:41Z

Jbrandt:

= Introduction =

* [[ManualIntroduction]]

= Installation =

* [[ManualRequirements]]
* [[ManualInstallation]]

= Initial configuration and basic administration =

* [[ManualApacheConfig]]
* [[ManualEmailConfig]]
* [[ManualBasicAdministration]]

= Using web interface and RT in general =

* [[ManualUsingWebInterface]] and its subchapters:
:* [[ManualTicketDates]]
:* [[ManualDashboards]]
:* [[ManualSearchTickets]]
:** [[ManualSimpleSearch]]

= Advanced administration =

* [[ManualAdministration]]
* [[ManualProblems]]

= Appendices =

* [[ManualRights]]
* [[ManualScrips]]
* [[ManualApache]]
* [[ManualApprovals]]

= Glossary =

* [[RTGlossary]]

= History of this manual =

In April 2003, [[BestPractical]] released a draft user manual for RT as a downloadable PDF. That manual became a starting point for this part of the wiki to be updated and extended by the community. Documentation for [https://docs.bestpractical.com/rt/latest RT] and [https://docs.bestpractical.com/rtir/latest RTIR] is also available on the [https://bestpractical.com/docs Best Practical] website.

[[Category:RT User Manual]]
[[Category:RT44]]

UpdateTheWiki

2019-03-28T20:18:55Z

Jbrandt:

Updating the wiki is very easy.

== To edit existing pages ==

* Click the Edit link at the top of the page or on any section.
* Edit the page contents and click save.
* If presented with a simple question about RT, answer it. This helps us keep the wiki spam to a minimum.

== To add new pages ==

* Click the edit link on the page where you want to add the first link to the new page.
* Add [[CamelCaseNameOfNewPage]] to the text of the page and click save. ([http://en.wikipedia.org/wiki/CamelCase What's CamelCase?]).
* You should see [[CamelCaseNameOfNewPage]] as a red link.
* Click this link and you will see a create box for the new page.

If name of the new page doesn't match [[CamelCase]] notation, like REST or Ticket use [[REST]] or [[Ticket]].

You can use the following trick as well:

* In the URL string of your browser write https://rt-wiki.bestpractical.com/wiki/NameOfNewPage
* Hit enter and you'll seeing a page that already exists or a page that gives you the option to create a new page. Click the links to do that.
* This trick has a trade-off, as a new page is not linked to from any other page. People can only find it with the search box, so you have to add links later.

Additional information:

* [[WikiWishList]] - wish list for the RT Wiki
* [[LowHangingFruit]] - improvements to wiki formatting which do not require extensive knowledge of RT.

Main Page

2019-03-28T20:01:19Z

Jbrandt:

== RT ==

RT is an open source issue tracking and workflow platform developed and supported by [https://bestpractical.com Best Practical Solutions]. This wiki site is a free resource for the RT community to share ideas, configurations, and customizations to RT, RTIR, and related products.

Please: [[UpdateTheWiki]], post your hints, tricks, tips and tools about how to get the most out of RT. If you currently use RT, please head over to [[RTUsers]] and add yourself and your organization to the user list.

== About RT Documentation ==

In addition to the information found here, you can find RT's documentation in your install of RT on the server and also [https://bestpractical.com/resources/ on the web at the Best Practical website]. The [https://bestpractical.com/blog Best Practical blog] and the [https://forum.bestpractical.com Community Forum] are also great resources for RT information. Best Practical also offers commercial support services to help get the most out of RT and RTIR.

== Getting Started with RT ==

If you're new to RT, start with the [[UserManual]].

== Current Sections ==

You can go through these pretty much in order if you're starting from scratch, but please plan to spend some quality time with the [[UserManual]] before you try to go live; RT is big and full of tons of features, and you probably can't get your head around all of it in one sitting.

* [[Demo]]

== Historical Sections ==

RT has been in development for over 20 years, so information on this wiki dates back to many different versions. These sections may contain information on older versions of RT that is no longer completely accurate for modern RT. Pages known to be updated should be moved up to the Current Section.

* [[FAQ]], [[FindingAnswersAboutRT]] and "Common Problems" below.
* [[BugReporting]]
* [[HowToHelp]], [[Translation]]

* [[RTGlossary]] & [[Documentation]]
* [[InstallationGuides]], [[RTTutorials]]
* [[RT Config|RT_Config]] & [[RT SiteConfig|RT_SiteConfig]]

* [[Extensions]] to RT available as installable plugins
* [[Contributions]] by the community to customize RT
* [[RTIR]] RT for Incident Response
* [[RTFM]] RT FAQ Manager

* [[RTHistory]]
* [[InThePress]]
* [[REST]] API
* Customizing with [[CustomizingWithCallbacks|Callbacks]]

=== Common problems ===

* [[CantLocateObject]] - Can't locate object method "new" via package "<code>RT::Handle</code>" at rt3/lib/RT.pm
* [[NoConnectionToSyslog]] - no connection to syslog
* [[NoRecipFound]] - No recipients found. Not sending
* Getting information out of RT3 for [[reporting]] or inclusion elsewhere.
* [[PermissionDenied]] emails|
* Getting RT4.x to play nice with [[certbot]] to obtain free SSL certificates from [http://letsencrypt.org LetsEncrypt].

== Wish lists ==

* [[WikiWishList]] - wish list for this wiki
* [[WishList]] - wish list for the RT
* [[RT3StatisticsPackageWishList]]

== Getting started with MediaWiki ==

To learn more about how to edit wiki pages, click the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents Help] link here or in the navigation on the left.

We have installed the Markdown plugin, so you can edit pages in Markdown.

Several years ago, we moved the wiki from Wikia as noted on the [[Wikia Move]] page.

Demo

2019-03-28T20:00:43Z

Jbrandt:

If you want to try RT, you can find demonstration sites here:

* http://rt.easter-eggs.org/demos/
* https://demo.bestpractical.com/

[[Category:New category]]

UpdateTheWiki

2019-03-28T19:56:07Z

Jbrandt:

Updating the wiki is very easy.

== To edit existing pages ==

* Click the Edit link at the top of the page or on any section.
* Edit the page contents and click save.
* If presented with a simple question about RT, answer it. This helps us keep the wiki spam to a minimum.

== To add new pages ==

* Click the edit link on the page where you want to add the first link to the new page.
* Add [[CamelCaseNameOfNewPage]] to the text of the page and click save. ([http://en.wikipedia.org/wiki/CamelCase What's CamelCase?]).
* You should see [[CamelCaseNameOfNewPage]] as a red link.
* Click this link and you will see a create box for the new page.

If name of the new page doesn't match [[CamelCase]] notation, like REST or Ticket use [[REST]] or [[Ticket]].

You can use the following trick as well:

* In the URL string of your browser write https://rt-wiki.bestpractical.com/index.php?title=NameOfNewPage
* Hit enter and you'll seeing a page that already exists or a page that gives you the option to create a new page. Click the links to do that.
* This trick has a trade-off, as a new page is not linked to from any other page. People can only find it with the search box, so you have to add links later.

Additional information:

* [[WikiWishList]] - wish list for the RT Wiki
* [[LowHangingFruit]] - improvements to wiki formatting which do not require extensive knowledge of RT.

Main Page

2019-03-28T19:51:22Z

Jbrandt:

== RT ==

RT is an open source issue tracking and workflow platform developed and supported by [https://bestpractical.com Best Practical Solutions]. This wiki site is a free resource for the RT community to share ideas, configurations, and customizations to RT, RTIR, and related products.

Please: [[UpdateTheWiki]], post your hints, tricks, tips and tools about how to get the most out of RT. If you currently use RT, please head over to [[RTUsers]] and add yourself and your organization to the user list.

== About RT Documentation ==

In addition to the information found here, you can find RT's documentation in your install of RT on the server and also [https://bestpractical.com/resources/ on the web at the Best Practical website]. The [https://bestpractical.com/blog Best Practical blog] and the [https://forum.bestpractical.com Community Forum] are also great resources for RT information. Best Practical also offers commercial support services to help get the most out of RT and RTIR.

== Getting Started with RT ==

If you're new to RT, start with the [[UserManual]].

== Current Sections ==

You can go through these pretty much in order if you're starting from scratch, but please plan to spend some quality time with the [[UserManual]] before you try to go live; RT is big and full of tons of features, and you probably can't get your head around all of it in one sitting.

== Historical Sections ==

RT has been in development for over 20 years, so information on this wiki dates back to many different versions. These sections may contain information on older versions of RT that is no longer completely accurate for modern RT. Pages known to be updated should be moved up to the Current Section.

* [[FAQ]], [[FindingAnswersAboutRT]] and "Common Problems" below.
* [[BugReporting]]
* [[HowToHelp]], [[Translation]]
* [[Demo]]
* [[RTGlossary]] & [[Documentation]]
* [[InstallationGuides]], [[RTTutorials]]
* [[RT Config|RT_Config]] & [[RT SiteConfig|RT_SiteConfig]]

* [[Extensions]] to RT available as installable plugins
* [[Contributions]] by the community to customize RT
* [[RTIR]] RT for Incident Response
* [[RTFM]] RT FAQ Manager

* [[RTHistory]]
* [[InThePress]]
* [[REST]] API
* Customizing with [[CustomizingWithCallbacks|Callbacks]]

=== Common problems ===

* [[CantLocateObject]] - Can't locate object method "new" via package "<code>RT::Handle</code>" at rt3/lib/RT.pm
* [[NoConnectionToSyslog]] - no connection to syslog
* [[NoRecipFound]] - No recipients found. Not sending
* Getting information out of RT3 for [[reporting]] or inclusion elsewhere.
* [[PermissionDenied]] emails|
* Getting RT4.x to play nice with [[certbot]] to obtain free SSL certificates from [http://letsencrypt.org LetsEncrypt].

== Wish lists ==

* [[WikiWishList]] - wish list for this wiki
* [[WishList]] - wish list for the RT
* [[RT3StatisticsPackageWishList]]

== Getting started with MediaWiki ==

To learn more about how to edit wiki pages, click the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents Help] link here or in the navigation on the left.

We have installed the Markdown plugin, so you can edit pages in Markdown.

Several years ago, we moved the wiki from Wikia as noted on the [[Wikia Move]] page.

UserManual

2019-03-22T14:35:53Z

Jbrandt:

BestPractical

2019-03-21T12:32:44Z

Jbrandt:

[http://bestpractical.com/ Best Practical Solutions LLC] are the creators of [https://bestpractical.com/request-tracker/ Request Tracker], [https://bestpractical.com/rtir Request Tracker for Incident Response] and other products. We also provide commercial support, custom development, hosting, and install and upgrade services for RT and RTIR.

UserManual

2019-03-20T15:37:56Z

Jbrandt:

= About this manual =

In April 2003, [[BestPractical]] released a draft user manual for RT as a downloadable PDF. That manual is now part of this wiki to be updated and extended by the community.

= Introduction =

* [[ManualIntroduction]]

= Installation =

* [[ManualRequirements]]
* [[ManualInstallation]]

= Initial configuration and basic administration =

* [[ManualApacheConfig]]
* [[ManualEmailConfig]]
* [[ManualBasicAdministration]]

= Using web interface and RT in general =

* [[ManualUsingWebInterface]] and its subchapters:
** [[ManualTicketDates]]
** [[ManualDashboards]]
** [[ManualSearchTickets]]
*** [[ManualSimpleSearch]]

= Advanced administration =

* [[ManualAdministration]]
* [[ManualProblems]]

= Appendices =

* [[ManualRights]]
* [[ManualScrips]]
* [[ManualApache]]
* [[ManualApprovals]]

= Glossary =

* [[RTGlossary]]

[[Category:RT User Manual]]

ManualIntroduction

2019-03-20T15:35:34Z

Jbrandt:

Up: [[UserManual]] --- Next: [[ManualRequirements]]

Welcome to Request Tracker (RT), your new favorite ticketing system. This introduction explains what ticketing is and what RT is. If you're already familiar with RT, you can skip ahead.

= About Ticketing =

In some contexts, when people think about a "ticket," they're talking about a code on their phone or a physical piece of paper that gets them into an event or on an airplane for a flight. The RT type of ticketing is a way for organizations to keep track of their to-do lists, who is working on which tasks, what's already been done, and when tasks were completed. You will also hear the phrase "trouble ticketing" bandied about, though there does not have to be a problem for ticketing to be useful. "Issue tracking" is another common phrase used for general ticketing.

Ticketing can make life easier for many people and departments in an organization -- basically anyone who needs to keep track of a list of tasks. And it can be used with a variety of tasks, like fixing software bugs, answering customer service requests, or tracking security issues.

Tickets can be a simple record of work done, like "Applied software patches on server," or detailed records with many custom fields and a long history. How you use tickets in RT will depend on your use case and can differ from queue to queue. Whatever your approach, it's good to communicate with users so everyone understands why and how they should interact with the system.

= About RT =

RT is a ticketing system for all sizes of organizations. It is available under the terms of the GNU General Public License (GPL), so it doesn't cost anything to set up and use. Managed hosting plans and commercial support are also available from [https://bestpractical.com Best Practical Solutions]. We'll get into the technical features later, but for now, let's look at how RT might work:

* Billy has a problem with his Bananamaster 3000, so he sends email to help@example.com
* RT records the new issue in its database and sends Billy an electronic "ticket stub" containing the new ticket's ID number and, ideally, some helpful information. He can refer to the ticket stub if he needs to send another email later.
* RT forwards Billy's email to a set of staff members.
* One of the staff members, Jane, is the company's Bananamaster expert. So Jane takes over Billy's issue and drafts a reply to Billy, which RT automatically records and forwards to him.
* Billy is a happy customer; Jane resolves the issue and heads down to the pub for a pint.

This workflow is flexible, can be customized for your organization, and need not involve bananas.

= RT concepts =

There are some words and phrases you should understand in the context of RT before you begin. See [[RTGlossary]] for more definitions.

A [[Ticket]] is the central object in RT, the thing that needs to get done. Tickets have metadata attached to them such as an owner, status, and queue - we'll get to all that in a minute.

A [[Queue]] is the central administrative domain of RT; it keeps things organized. As the name implies, it's a line of tickets waiting to be worked on, but it's also, to some extent, the ticket's category. For instance, you might have the right to create, delete, and comment on tickets in the Foo queue, but only the right to comment on tickets in the Bar queue.

A ticket's history is what it sounds like: everything that's happened to a ticket. Facets of ticket history could include when the ticket was created, how it has changed, and any comments about it or replies to it. Like real history, ticket history typically is not changed. However, new laws related to user privacy like [https://docs.bestpractical.com/rt/latest/GDPR.html GDPR] in the EU require some organizations to evaluate their auditing policies and decide how to handle requests to remove personal user data. This can require ticket data to be modified or removed completely.

Ticket updates can take one of two forms. A reply is a public remark that a requestor can see. A comment is a private note for staff not visible to the requestor. This is useful when you want to be tactful but still convey important information, like, "This requestor is an investor, so be nice" or "This user's request mentioned his 'PC' but he really has a Mac."

Priority, how important a ticket is, is represented as numerical scale from 0-99, with 99 being the highest priority. By setting a final priority, you can make a ticket's priority increase or decrease as its due date draws closer. The difference between 20, 50, and 75 may vary from organization to organization, but there should be an organizational policy or every ticket will get rated 99 by anxious users. [[ManualAdministration]] contains a useful model for setting organizational policy for priority. You can also install the [https://metacpan.org/pod/RT::Extension::PriorityAsString PriorityAsString] extension to manage priority with terms like "high" and "low".

The status drop-down menu offers several choices for classifying each ticket. Here's what they mean:

* new: the ticket has just been created and hasn't been touched yet.
* open: the ticket is getting worked on
* stalled: due to circumstances beyond your control (waiting for the requestor to respond, waiting for the owner to return from Sri Lanka), the ticket isn't getting worked on right now. It will open again when someone adds a comment or reply.
* resolved: hooray! Work on the ticket has been completed and is out of everyone's hair.
* rejected: the ticket is not the staff's problem and is not going to be resolved, but is, for some reason, worth recording in the system. For instance, if an employee asks approval for something ridiculous, you can reject the ticket, but it will stay in the database as evidence that the employee makes silly requests.
* deleted: the ticket never should have been in the system (maybe it was spam, a list of passwords, etc) -- and is now being zapped for good.

A watcher is someone who is interested in a ticket. You'll find these filed under "People" when you're looking at a ticket. A watcher of a ticket normally gets email-copies of all the replies to the ticket. The watchers who are staff-members get copies of the comments too. There are several types, or roles, of watchers:

* Owner: the person responsible for the ticket and its resolution. Each ticket can have only one owner. As a ticket is worked on, it may be passed from one owner to another.
* Requestor: the person or people who asked for something to get done; the ticket's reason for being. The Requestor normally gets copies of all replies to the ticket, but no comments.
* Cc: someone (or someones) who should get copies of any '''replies''' that go to the requestor. This might be the requestor's boss, sales rep, etc. This person will see the emails but doesn't necessarily have the right to work on the ticket.
* AdminCc: a Cc or Ccs that also gets copies of '''comments''' and generally are allowed to work on the ticket.

We're hedging with words like "generally" and "necessarily" because any role can be assigned any right.

You can also, as you work on a ticket, define its relationship to something. Relationships in RT can be ticket-to-ticket, but can also link tickets to external items like URLs or FedEx shipping numbers. For the sake of simplicity, we'll refer only to tickets in the following explanation of relationship types:

* DEPENDS ON: the ticket can't be resolved unless another ticket is also resolved. The converse is depended on by.
* REFERS TO: the ticket doesn't need the other ticket, but it would sure be useful for you to look at it. The converse is referred to by.
* PARENT: a big, general ticket ("Move house.")
* CHILD: a subproject of a parent ("Hire movers." "Pack." "Eat pizza.")

[[CustomField]]s are, yes, database fields that your organization can make up according to its needs. For details, see the Custom Fields section in [[ManualAdministration]]. An example custom field might be '''Resolution''': FIXED, WORKSFORME, WONTFIX, UPSTREAM, etc.

[[Scrip]]s are custom events that will automatically take Action X in response to Condition Y. You could have RT notify the Requestor when a ticket is resolved, for instance, or have RT page you when your boss submits a request. RT comes with many standard scrips, and you can define your own. For details, see the Scrips section in [[ManualAdministration]]. And no, we didn't misspell "scripts." We made up a new word. Try it, it's fun.

Now that you are (we hope) clear on the concepts, you're ready to start using RT.

Up: [[UserManual]] --- Next: [[ManualRequirements]]
[[Category:RT User Manual]]

ManualIntroduction

2019-03-19T14:47:15Z

Jbrandt:

Up: [[UserManual]] --- Next: [[ManualRequirements]]

Welcome to Request Tracker (RT), your new favorite ticketing system. This introduction explains what ticketing is and what RT is. If you're already familiar with RT, you can skip ahead.

= About Ticketing =

In some contexts, when people think about a "ticket," they're talking about a code on their phone or a physical piece of paper that gets them into an event or on an airplane for a flight. The RT type of ticketing is a way for organizations to keep track of their to-do lists, who is working on which tasks, what's already been done, and when tasks were completed. You will also hear the phrase "trouble ticketing" bandied about, though there does not have to be a problem for ticketing to be useful. "Issue tracking" is another common phrase used for general ticketing.

Ticketing can make life easier for many people and departments in an organization -- basically anyone who needs to keep track of a list of tasks. And it can be used with a variety of tasks, like fixing software bugs, answering customer service requests, or tracking security issues.

Tickets can be a simple record of work done, like "Applied software patches on server," or detailed records with many custom fields and a long history. How you use tickets in RT will depend on your use case and can differ from queue to queue. Whatever your approach, it's good to communicate with users so everyone understand why and how they should interact with the system.

= About RT =

RT is a ticketing system for all sizes of organizations. It is available under the terms of the GNU General Public License (GPL), so it doesn't cost anything to set up and use. We'll get into the technical features later, but for now, let's look at how RT might work:

* Billy has a problem with his Bananamaster 3000, so he sends email to help@example.com
* RT records the new issue in its database and sends Billy an electronic "ticket stub" containing the new ticket's ID number and, ideally, some helpful information. He can refer to the ticket stub if he needs to send another email later.
* RT forwards Billy's email to a set of staff members.
* One of the staff members, Jane, is the company's Bananamaster expert. So Jane takes over Billy's issue and drafts a reply to Billy, which RT automatically records and forwards to him.
* Billy is a happy customer; Jane resolves the issue and heads down to the pub for a pint.

This workflow is flexible, can be customized for your organization, and need not involve bananas.

= RT concepts =

There are some words and phrases you should understand in the context of RT before you begin. See [[RTGlossary]] for more definitions.

A [[Ticket]] is the central object in RT, the thing that needs to get done. Tickets have metadata attached to them such as an owner, status, and queue - we'll get to all that in a minute.

A [[Queue]] is the central administrative domain of RT; it keeps things organized. As the name implies, it's a line of tickets waiting to be worked on, but it's also, to some extent, the ticket's category. For instance, you might have the right to create, delete, and comment on tickets in the Foo queue, but only the right to comment on tickets in the Bar queue.

A ticket's history is what it sounds like: everything that's happened to a ticket. Facets of ticket history could include when the ticket was created, how it has changed, and any comments about it or replies to it. Like real history, ticket history typically is not changed. However, new laws related to user privacy like [https://docs.bestpractical.com/rt/latest/GDPR.html GDPR] in the EU require some organizations to evaluate their auditing policies and decide how to handle requests to remove personal user data. This can require ticket data to be modified or removed completely.

Ticket updates can take one of two forms. A reply is a public remark that a requestor can see. A comment is a private note for staff not visible to the requestor. This is useful when you want to be tactful but still convey important information, like, "This requestor is an investor, so be nice" or "This user's request mentioned his 'PC' but he really has a Mac."

Priority, how important a ticket is, is represented as numerical scale from 0-99, with 99 being the highest priority. By setting a final priority, you can make a ticket's priority increase or decrease as its due date draws closer. The difference between 20, 50, and 75 may vary from organization to organization, but there should be an organizational policy or every ticket will get rated 99 by anxious users. [[ManualAdministration]] contains a useful model for setting organizational policy for priority. You can also install the [https://metacpan.org/pod/RT::Extension::PriorityAsString PriorityAsString] extension to manage priority with terms like "high" and "low".

The status drop-down menu offers several choices for classifying each ticket. Here's what they mean:

* new: the ticket has just been created and hasn't been touched yet.
* open: the ticket is getting worked on
* stalled: due to circumstances beyond your control (waiting for the requestor to respond, waiting for the owner to return from Sri Lanka), the ticket isn't getting worked on right now. It will open again when someone adds a comment or reply.
* resolved: hooray! Work on the ticket has been completed and is out of everyone's hair.
* rejected: the ticket is not the staff's problem and is not going to be resolved, but is, for some reason, worth recording in the system. For instance, if an employee asks approval for something ridiculous, you can reject the ticket, but it will stay in the database as evidence that the employee makes silly requests.
* deleted: the ticket never should have been in the system (maybe it was spam, a list of passwords, etc) -- and is now being zapped for good.

A watcher is someone who is interested in a ticket. You'll find these filed under "People" when you're looking at a ticket. A watcher of a ticket normally gets email-copies of all the replies to the ticket. The watchers who are staff-members get copies of the comments too. There are several types, or roles, of watchers:

* Owner: the person responsible for the ticket and its resolution. Each ticket can have only one owner. As a ticket is worked on, it may be passed from one owner to another.
* Requestor: the person or people who asked for something to get done; the ticket's reason for being. The Requestor normally gets copies of all replies to the ticket, but no comments.
* Cc: someone (or someones) who should get copies of any '''replies''' that go to the requestor. This might be the requestor's boss, sales rep, etc. This person will see the emails but doesn't necessarily have the right to work on the ticket.
* AdminCc: a Cc or Ccs that also gets copies of '''comments''' and generally are allowed to work on the ticket.

We're hedging with words like "generally" and "necessarily" because any role can be assigned any right.

You can also, as you work on a ticket, define its relationship to something. Relationships in RT can be ticket-to-ticket, but can also link tickets to external items like URLs or FedEx shipping numbers. For the sake of simplicity, we'll refer only to tickets in the following explanation of relationship types:

* DEPENDS ON: the ticket can't be resolved unless another ticket is also resolved. The converse is depended on by.
* REFERS TO: the ticket doesn't need the other ticket, but it would sure be useful for you to look at it. The converse is referred to by.
* PARENT: a big, general ticket ("Move house.")
* CHILD: a subproject of a parent ("Hire movers." "Pack." "Eat pizza.")

[[CustomField]]s are, yes, database fields that your organization can make up according to its needs. For details, see the Custom Fields section in [[ManualAdministration]]. An example custom field might be '''Resolution''': FIXED, WORKSFORME, WONTFIX, UPSTREAM, etc.

[[Scrip]]s are custom events that will automatically take Action X in response to Condition Y. You could have RT notify the Requestor when a ticket is resolved, for instance, or have RT page you when your boss submits a request. RT comes with many standard scrips, and you can define your own. For details, see the Scrips section in [[ManualAdministration]]. And no, we didn't misspell "scripts." We made up a new word. Try it, it's fun.

Now that you are (we hope) clear on the concepts, you're ready to start using RT.

Up: [[UserManual]] --- Next: [[ManualRequirements]]
[[Category:RT User Manual]]

REST

2018-11-01T14:25:33Z

Jbrandt:

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, Best Practice indicates that the REST stuff has not changed in any significant way in 4.x as of, at least, 1/2012.

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server

You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

'''fields'''

A list of fields you would like included in the result set.

Example:
<code>/REST/1.0/search/ticket?query=id=42&format=l&fields=Subject,Status,Priority,CF.\{Category\}</code>

Note that you may need to escape characters like the curly braces for CFs.

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===

* History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).

* Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.

* Comments in response body starts with with a hash (<code>#</code>) symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/rt-client rt-client]
|[https://github.com/uidzip/rt-client GitHub]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/Rickerd0613/rtapi rtapi]
|[https://github.com/Rickerd0613/rtapi GitHub]
|<code>pip install rtapi</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/z4r/python-rtkit GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://github.com/CZ-NIC/python-rt python-rt]
|[https://github.com/CZ-NIC/python-rt Github]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}

NotificationsTuning

2018-05-23T18:50:18Z

Jbrandt: /* Patch to send less notifications */

= NotificationsTuning =

This page describes a team organization example, and how we send notifications. We talk about an IT team, managing servers and applications.

= Introduction =

We have in our RT many queues, and from 2 to 4 adminccs per queue. The incoming tickets arrive in an INCOMING queue and are dispatched by some people to the appropriate queue. When a ticket enters a queue, it belongs to nobody and one of the adminccs takes the ticket (depending on the workload of each others, holidays etc...). Then the ticket lives and is resolved. I describe here the notifications we use, hoping it will help people. Any comments/optimizations/etc are welcome at the end of the file.

= Summary =

When a new ticket is created :

* notify requestor with an autoreply
* notify owner he has a new ticket (if the ticket was created and assigned at the same time)
* notify adminccs of the queue that a new ticket is available in their queue

When there is an owner change :

* notify (new) owner
* notify other adminccs that the ticket is taken by one of them (so they don't have to take care of it)

When there is a queue change :

* notify adminccs of the new queue there is a new ticket

When there is a correspondance on a ticket (reply):

* notify requestors, ccs
* notify other recipients
* notify owner
* notify adminccs

When there is a comment on a ticket :

* notify owner
* notify admincc

When a ticket is resolved :

* notify requestor
* notify adminccs someone (one of them) resolved the ticket

I created new templates starting with "MY" and associated them to scrips. I put in these templates what makes sense to me, and I added a line explaining the reason why you receive this mail.

= Patch to send less notifications =

But with this configuration (and with the default one), we had a problem : we received too many emails for the same thing : For example :

* a (privilieged) user sends a request to RT for a task he has to do.
* people managing tickets assign it to him, and put it in a queue he is admincc for

So this user is requestor, owner, and admincc : he gets 3 emails on each correspondance.

This is the patch (ugly patch but it works) I applied to lib/RT/Action/Notify.pm (well, I created a new file local/lib/RT/Action/Notify.pm) . It has been tested on RT 3.8.2 and 3.8.7 :

<source lang="perl">

# cat Notify.patch
--- /Notify.pm.orig 2010-01-06 16:03:20.000000000 +0100
+++ Notify.pm 2010-02-01 16:36:00.000000000 +0100
@@ -85,6 +85,11 @@
$arg =~ s/\bAll\b/Owner,Requestor,AdminCc,Cc/;

my ( @To, @PseudoTo, @Cc, @Bcc );
+ my $requestor_emails = join(' ',($ticket->Requestors->MemberEmailAddresses));
+ my $admincc_emails = join(' ',($ticket->AdminCc->MemberEmailAddresses));
+ my $owner_email = join(' ',($ticket->OwnerObj->EmailAddress));
+ my $queueadmincc_emails = join(' ',($ticket->QueueObj->AdminCc->MemberEmailAddresses));
+ my @requestor_emails_array = split(/ /,$requestor_emails);

if ( $arg =~ /\bOtherRecipients\b/ ) {
@@ -115,7 +120,7 @@
}
}

- if ( $arg =~ /\bOwner\b/ && $ticket->OwnerObj->id != $RT::Nobody->id ) {
+ if ( $arg =~ /\bOwner\b/ && $ticket->OwnerObj->id != $RT::Nobody->id && $requestor_emails !~ $owner_email ){
# If we're not sending to Ccs or requestors,
# then the Owner can be the To.
if (@To) {
@@ -128,8 +133,18 @@
}

if ( $arg =~ /\bAdminCc\b/ ) {
- push ( @Bcc, $ticket->AdminCc->MemberEmailAddresses );
- push ( @Bcc, $ticket->QueueObj->AdminCc->MemberEmailAddresses );
+ # Notification already sent for requestor
+ foreach (@requestor_emails_array){
+ $admincc_emails =~ s/$_//g;
+ $queueadmincc_emails =~ s/$_//g;
+ }
+ # Notification already sent for owner
+ $admincc_emails =~ s/$owner_email//g;
+ $queueadmincc_emails =~ s/$owner_email//g;
+
+ push ( @Bcc, $admincc_emails );
+ push ( @Bcc, $queueadmincc_emails );
+
}

if ( RT->Config->Get('UseFriendlyToLine') ) {

</source>

This is what the patch does :

* always send an email to the requestor for a correspondance ("Reply")
* if user is requestor and owner, do not send to the owner (an email has already been sent to the requestor)
* if a user is requestor or owner and admincc, remove him from the list of admincc (as he has already been notified either because he's a requestor or a owner) and send the email to this list of admincc .

That also means the template received by the user depends on his role (sometimes he will receive the requestor template, sometimes the owner, sometimes the admincc). But as basically it's the same thing, we don't mind.

This is the test matrix :

<nowiki>

ROA | S | P | T
------------------
000 | x | x | x
001 | 1 | 1 | A
010 | 1 | 1 | O
011 | 2 | 1 | O
100 | 1 | 1 | R
101 | 2 | 1 | R
110 | 2 | 1 | R
111 | 3 | 1 | R

</nowiki>

* R : is requestor
* O : is owner
* A : is admincc

* S : Number of emails sent with Standard notify.pm
* P : Number of emails sent with Patched notify.pm
* T : Template used (Requestor, Owner, [[AdminCc]])

I've not managed the Cc part, and the comments because our main problem was the duplicate emails generated by correspondences.

And it works very well. No more useless notifications.

= Details of the Global scrips : =

<nowiki>Id Description Stage Condition Action Template
-------------------------------------------------------------------------------------------------------------------------------------------------
1 Autoreply TransactionCreate User Defined Autoreply To Requestors Autoreply
2 On Create Notify Owner TransactionCreate On Create Notify Owner MY Create Notify Owner template
3 On Create Notify AdminCcs TransactionCreate On Create Notify AdminCcs MY Create Notify AdminCc template

4 On Owner Change Notify Owner TransactionCreate On Owner Change Notify Owner MY Owner Change Notify Owner template
5 On Owner Change Notify AdminCc TransactionCreate On Owner Change Notify AdminCcs as Comment MY Comment ChangeOwner
6 On Queue Change Notify AdminCcs TransactionCreate On Queue Change Notify AdminCcs MY Queue Change Notify AdminCcs

7 On Correspond Open Tickets TransactionCreate On Correspond Open Tickets Blank
8 On Correspond Notify Requestors and Ccs TransactionCreate On Correspond Notify Requestors and Ccs MY Correspond Notify Requestor and Ccs
9 On Correspond Notify Other Recipients TransactionCreate On Correspond Notify Other Recipients MY Correspond Notify Other recipients
10 On Correspond Notify Owner TransactionCreate On Correspond Notify Owner MY Correspond Notify Owner
11 On Correspond Notify AdminCcs TransactionCreate On Correspond Notify AdminCcs MY Correspond Notify AdminCc

12 On Comment Notify AdminCcs as Comment TransactionCreate On Comment Notify AdminCcs as Comment MY Comment AdminCc
13 On Comment Notify Owner as Comment TransactionCreate On Comment Notify Owner as Comment MY Comment Owner

14 On Resolve Notify Requestors TransactionCreate On Resolve Notify Requestors MY Ticket Resolved
15 On Resolve Notify AdminCcs TransactionCreate On Resolve Notify AdminCcs as Comment MY Comment AdminCc Resolved

</nowiki>

= Templates =

Here are the templates :

1) Default

2) MY Create Notify Owner template

<nowiki>RT-Attach-Message: yes

You receive this email because you are owner of a new ticket.

This new ticket has been created and assigned to you:

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

3) MY Create Notify [[AdminCc]] template

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc of {$Ticket->QueueObj->Name} queue.

A new ticket has been created in this queue.

Click here to take it :{$RT::WebURL}Ticket/Display.html?Action=Take&id={$Ticket->id}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

4) MY Owner Change Notify Owner template

<nowiki>You receive this email because you become owner of this ticket.

You are now the owner of ticket #{$Ticket->id}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"
=====================================================================

</nowiki>

5) MY Comment [[ChangeOwner]]

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc on {$Ticket->QueueObj->Name} queue.

Ticket taken by {$Ticket->OwnerObj->Name}.

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"
=====================================================================

</nowiki>

6) MY Queue Change Notify [[AdminCcs]]

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc of {$Ticket->QueueObj->Name} queue.

{$Transaction->Description}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"
=====================================================================

</nowiki>

7) Default

8) MY Correspond Notify Requestor and Ccs

<nowiki>RT-Attach-Message: yes

You receive this email because you are Requestor or Cc on this ticket.

{$Transaction->Description}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

9) MY Correspond Notify Other recipients

<nowiki>RT-Attach-Message: yes

You receive this email because you are in the list of recipients of this ticket.

{$Transaction->Description}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

10) MY Correspond Notify Owner

<nowiki>RT-Attach-Message: yes

You receive this email because you are owner of this ticket.

{$Transaction->Description}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

11) MY Correspond Notify [[AdminCc]]

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc on {$Ticket->QueueObj->Name} queue.

{$Transaction->Description}

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

12) MY Comment [[AdminCc]]

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc on {$Ticket->QueueObj->Name} queue.

{$Transaction->Description}. This message is not sent to the requestors.

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

13) MY Comment Owner

<nowiki>RT-Attach-Message: yes

You receive this email because you are Owner of this ticket.

{$Transaction->Description}. This message is not sent to the requestors.

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"

{$Transaction->Content()}
=====================================================================

</nowiki>

14) MY Ticket Resolved

Subject: Resolved: {$Ticket->Subject}

Request {$Ticket->id} was acted upon.

Subject: {$Transaction->Subject || $Ticket->Subject || "(No subject given)"}

According to our tests, your request has been resolved. If you have any
further questions or concerns, please open a new ticket or reopen this one by replying to this email.

{$Transaction->CreatedAsString}: {$Transaction->Description}
Queue: {$Ticket->QueueObj->Name}
Owner: {$Ticket->OwnerObj->Name}
Requestors: {$Ticket->RequestorAddresses}

Ticket <URL: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id} >

15) MY Comment [[AdminCc]] Resolved

<nowiki>RT-Attach-Message: yes

You receive this email because you are AdminCc on {$Ticket->QueueObj->Name} queue.

Ticket resolved by {$Ticket->OwnerObj->Name}.

=====================================================================
Ticket: {$RT::WebURL}Ticket/Display.html?id={$Ticket->id}
Queue: {$Ticket->QueueObj->Name}
Requestors: {$Ticket->RequestorAddresses}
Owner: {$Ticket->OwnerObj->Name}
Status: {$Ticket->Status}
Subject: "{$Transaction->Subject || $Ticket->Subject || "(No subject given)"}"
=====================================================================
</nowiki>

= Discussions/remarks/etc... =

Christophe {dot} Sahut {at} sgs {dot} com

REST

2017-03-23T20:41:21Z

Jbrandt: /* Convenience libraries */

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, Best Practice indicates that the REST stuff has not changed in any significant way in 4.x as of, at least, 1/2012.

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server

You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

'''fields'''

A list of fields you would like included in the result set.

Example:
<code>/REST/1.0/search/ticket?query=id=42&format=l&fields=Subject,Status,Priority,CF.\{Category\}</code>

Note that you may need to escape characters like the curly braces for CFs.

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===
History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).
Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.
Comments in response body starts with <code> </code>
#symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rt-client.rubyforge.org RT-Client]
|[http://rubygems.org/gems/rt-client RubyGems]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/z4r/python-rtkit GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://github.com/CZ-NIC/python-rt python-rt]
|[https://github.com/CZ-NIC/python-rt Github]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}

RT3BatchAddUsers

2017-03-21T19:19:50Z

Jbrandt:

<syntaxhighlight lang="perl" line="1" >
#!/usr/bin/perl -w
#
# rtadduser: Batch add local users to RT based on a csv file named users_data.csv located # in the same directory
# Mohamed El Erian <mohamed.elerian@britishcouncil.org.eg,melerian@gmail.com>
# Partly based on script provided by David Maze <dmaze@cag.lcs.mit.edu>
# File format is username,realname,email_address,organization,address1,city,country
# $Id$
#

use lib "/usr/lib";
use strict;
use English;
use RT::Interface::CLI qw(CleanEnv);
use RT::User;

CleanEnv();
RT::LoadConfig();
RT::Init();
my @raw_data;
my $bc_user = '';
my $username = '';
my $realname = '';
my $email_address = '';
my $organization = '';
my $address1 = '';
my $city = '';
my $country = '';

open(USERS_DATA, "./users_data.csv") || die("Could not open file!");
@raw_data=<USERS_DATA>;
close(USERS_DATA);
foreach $bc_user (@raw_data)
{
chop($bc_user);
($username,$realname,$email_address,$organization,$address1,$city,$country)=split(/\,/,$bc_user);

my $UserObj = new RT::User(RT::SystemUser);
$UserObj->Create(Name => $username,
RealName => $realname,
EmailAddress => $email_address,
Password => 'Passw0rd',
Organization => $organization,
Address1 => $address1,
City => $city,
Country => $country,
Privileged => 1);
}

</syntaxhighlight>

RT3BatchAddUsers

2017-03-21T19:15:33Z

Jbrandt:

REST

2017-03-07T13:42:00Z

Jbrandt: /* Ticket Search */

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, Best Practice indicates that the REST stuff has not changed in any significant way in 4.x as of, at least, 1/2012.

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server

You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

'''fields'''

A list of fields you would like included in the result set.

Example:
<code>/REST/1.0/search/ticket?query=id=42&format=l&fields=Subject,Status,Priority,CF.\{Category\}</code>

Note that you may need to escape characters like the curly braces for CFs.

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===
History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).
Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.
Comments in response body starts with <code> </code>
#symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rt-client.rubyforge.org RT-Client]
|[http://rubygems.org/gems/rt-client RubyGems]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/ GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://gitlab.labs.nic.cz/labs/python-rt python-rt]
|[https://gitlab.labs.nic.cz GitLab]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}

REST

2017-01-04T17:41:07Z

Jbrandt:

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, Best Practice indicates that the REST stuff has not changed in any significant way in 4.x as of, at least, 1/2012.

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server

You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===
History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).
Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.
Comments in response body starts with <code> </code>
#symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rt-client.rubyforge.org RT-Client]
|[http://rubygems.org/gems/rt-client RubyGems]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/ GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://gitlab.labs.nic.cz/labs/python-rt python-rt]
|[https://gitlab.labs.nic.cz GitLab]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}

REST

2016-10-20T14:52:48Z

Jbrandt:

== Abstract ==

The REST Interface gives you access to your RT Database. The complete communication is encapsulated in the HTTP protocol. The interface should be accessible in your installation.

Though you may see references to older 3.x releases of RT below, Best Practice indicates that the REST stuff has not changed in any significant way in 4.x as of, at least, 1/2012.

[{{SERVER}}/index.php?search={{TALKPAGENAME}}&title=Special:Search Legacy Comments] are available from the previous Wikia instance.

== Interface ==

Base URL: <code>.../REST/1.0/</code>. The default response should be:

RT/3.4.5 200 Ok

# Invalid object specification: 'index.html'

id: index.html

=== Authentication ===

The REST Interface does not support HTTP-Authentication. So you must get a valid Session-Token and submit the cookie each request. You usually get a Session-Cookie by submitting the default login form. Use variables "<code>user</code>" for login and "<code>pass</code>" for password values. wget doesn't escape any characters in the --post-data option so make sure you properly escape any special characters in the password.

See the wget invocation line below:

wget --keep-session-cookies \
--save-cookies cookies.txt \
--post-data 'user=UUUU&pass=PPPP' \
http://my.rt.server
You need the -keep-session-cookies option to make wget save session cookies.

=== Ticket ===

==== Ticket Properties ====

Gets the data for a single ticket, not including the history and comments.

Request: <code>/REST/1.0/ticket/<ticket-id>/show</code>

RT/3.4.5 200 Ok

id: ticket/<ticket-id>
Queue: <...>
Owner: <...>
Creator: <...>
Subject: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
Requestors: <...>
Cc: <...>
AdminCc: <...>
Created: <...>
Starts: <...>
Started: <...>
Due: <...>
Resolved: <...>
Told: <...>
TimeEstimated: <...>
TimeWorked: <...>
TimeLeft: <...>

==== Ticket Links ====

Gets the ticket links for a single ticket.

Request: <code>REST/1.0/ticket/<ticket-id>/links/show</code>

RT/3.8.2 200 Ok

id: ticket/<ticket-id>/links
HasMember: fsck.com-rt://your.server.com/ticket/<another-id>
ReferredToBy: fsck.com-rt://your.server.com/ticket/<another-id>
DependedOnBy: fsck.com-rt://your.server.com/ticket/<another-id>
MemberOf: fsck.com-rt://your.server.com/ticket/<another-id>
RefersTo: fsck.com-rt://your.server.com/ticket/<another-id>
DependsOn: fsck.com-rt://your.server.com/ticket/<another-id>

==== Ticket Attachments ====

Gets a list of all attachments related to the ticket

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments</code>

==== Ticket Attachment ====
Gets the metadata and content of a specific attachment.

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id></code>

<pre>
RT/3.8.0 200 Ok

id: <attachment-id>
Subject:
Creator: <user-id>
Created: <timestamp>
Transaction: <transaction-id>
Parent: <parent-id>
MessageId:
Filename: <filename>
ContentType: application/octet-stream
ContentEncoding: none

Headers: MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: application/octet-stream;
name="<filename>"
Content-Disposition: inline; filename="<filename>"
Content-Transfer-Encoding: base64
Content-Length: <length in bytes>

Content: ...
...
...
</pre>

''NOTE: RT returns the content indented with 9 spaces on each line, so that it lines up with the "Content:" header. Even if you strip this out with a regexp, the content is still UTF-8, which is probably not what you want. To get the original binary data back, strip out the 9 spaces with a regexp, strip off the 3 carriage returns at the end, and then convert the whole thing from UTF-8 to the native character encoding of the attachment, whatever that is. RT doesn't tell you, so you have know. If the attachments were uploaded by a U.S. Windows system, odds are that Windows-1252 is what you want. If you can't get the binary back intact, see the next method below.''

==== Ticket Attachment Content ====

Gets the attachment data content without additional metadata or whitespace characters

Request: <code>/REST/1.0/ticket/<ticket-id>/attachments/<attachment-id>/content</code>

RT/3.8.0 200 Ok

...
...
...

So to get the original content you still have to strip the first 2 lines of the response.

==== Ticket History ====
Gets a list of all the history items for a given ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history</code>

<pre>
RT/3.4.5 200 Ok

# <history-count>/<history-count> (/total)

<history-id>: <history-name>
<history-id>: <history-name>
...
</pre>

You will get an additional row, for each history entry found. The first entry is usually: "<code>Ticket created by ...</code>".

There are two ways to get history item detail: you can do one of these and then recursively perform <code>ticket/history/id/<history-id></code> for each history-id from this REST call, but that is extremely wasteful and will scale horribly. What you really want to do is one REST call but get the long format:

Request: <code>/REST/1.0/ticket/<ticket-id>/history?format=l</code>

<pre>
RT/3.8.2 200 Ok

# <n>/<n> (id/<history-id>/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>
Content: <...>
Creator: <...>

Created: <...>

Attachments:
<attachment-id>: <filename> (<size>)
<attachment-id>: <filename> (<size>)

--

# <n>/<n> (id/<history-id>/total)
...
</pre>

''NOTE: the double dash "--" will occur in the long format between each history item. You can split the output on "--" and iterate over it, parsing out the data with an RFC822 parser, such as an email handling library.''

==== Ticket History Entry ====
Gets the history information for a single history item. Note that the history item must actually correspond to the ticket.

Request: <code>/REST/1.0/ticket/<ticket-id>/history/id/<history-id></code>

<pre>
RT/3.4.5 200 Ok

# 70/70 (id/114856/total)

id: <history-id>
Ticket: <ticket-id>
TimeTaken: <...>
Type: <...>
Field: <...>
OldValue: <...>
NewValue: <...>
Data: <...>
Description: <...>

Content: <lin1-0>
<line-1>
...
<line-n>

Creator: <...>
Created: <...>
Attachments: <...>
</pre>

''IMPORTANT NOTE: At least with RT 3.8.0, when you request a history item with this method AND you have attached a file that has Mime type text/plain to the same item (eg. a comment with an attachement), RT will return the complete content of the attachment for the key "Content:" and not your real comment that you can see in the web frontend. This may lead to some problems if the requestor does not expect to get a comment content that is for example 1.8 MB of text. With other Mime type attachments this however seems to work. I don't know if this is a feature or a bug.''

==== '''Ticket Search''' ====
Request: <code>/REST/1.0/search/ticket?query=<query>&orderby=<sort-order>&format=<format></code>

'''Parameters'''

'''query'''

You can use any query generated by the query builder - or feel free to write your own. Here an example that will do the following: Find all tickets that have no owner and the status new or open

<code>query= Owner = 'Nobody' AND ( Status = 'new' OR Status = 'open' )</code>

Example: to get all the tickets in "fooQueue" you'd access:

<code>/REST/1.0/search/ticket?query=Queue='fooQueue'</code>

Example: to get the tickets for a custom field "Contact Name" you'd access:

<code>/REST/1.0/search/ticket?query='CF.{Contact Name}'='Shaun Wallace'</code>

'''orderby'''

By this parameter you can change the sort field and order of the search result. To sort a list ascending just put a + before the fieldname, otherwise a -. Eg: -Created (will put the newest tickets at the beginning).

Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created</code>

'''format'''

* i: ticket/<ticket-id>
* s: <ticket-id>: <ticket-subject>
* l: a multi-line format
Example:
<code>/REST/1.0/search/ticket?query=Queue='fooQueue'&orderby=+Created&format=i</code>

==== '''Ticket Create''' ====

To create a new ticket: post on <code>/REST/1.0/ticket/new</code> with a variable named "<code>content</code>",

containing "<code>key: value</code>" line by line, example:

Testing the new ticket section

<pre>
id: ticket/new
Queue: <queue name>
Requestor: <requestor email address>
Subject: <subject>
Cc: <...>
AdminCc: <...>
Owner: <...>
Status: <...>
Priority: <...>
InitialPriority: <...>
FinalPriority: <...>
TimeEstimated: <...>
Starts: <...>
Due: <...>
Text: <The ticket content>
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

If there are any "special" characters (Umlauts, dash, ...?) in a custom field's name, you can still access it via its ID:
CF-$id: <Value>
If you want to have a multiline Text, prefix every line with a blank.

<pre>
Due: <...>
Text: This is
a
multiline Text
!!!
CF-<CustomFieldName>: <CustomFieldValue>
</pre>

The response should look like:
<pre>
RT/4.0.6 200 Ok

# Ticket 775 created.
</pre>

===== curl example =====

* Create a file containing the ticket form:
<pre>
id: ticket/new
Queue: queue1
Requestor: requestor@email
Priority: 4
CF-Type of request: Demande
Subject: Test REST
Text: Multi line
test with
special chars: é
</pre>

* Submit using curl:
<pre>
curl --data-urlencode content@file.name 'https://HOSTNAME/REST/1.0/ticket/new?user=USER&pass=PASSWORD'
</pre>
==== Ticket Edit ====
To update an existing ticket: post on <code>/REST/1.0/ticket/<ticket-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>ticket/<ticket-id>/show</code>). Example:

<pre>
Priority: 5
TimeWorked: 15
</pre>
*PHP
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/edit?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
$post_data=array("content"=>"AdminCc: userX\nText: This is a REST test edit ticket\n");

// add the post fields
$request->addPostFields($postData);
// response from RT
$response = $request->send()->getBody();
print_r($response);
</pre>

==== Tickets History Reply ====
Same as comment: post on <code>/REST/1.0/ticket/<ticket-id>/comment</code> with a variable name <code>content</code>, containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: correspond
Text: the text comment
Cc: <...>
Bcc: <...>
TimeWorked: <...>
Attachment: an attachment filename/path
</pre>

<code>Cc</code> and <code>Bcc</code> are for this reply only (''I think'').

==== Ticket History Comment ====
To add a comment to an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/comment</code>" with a variable name "<code>content</code>", containing "<code>key: value</code>" line by line:

<pre>
id: <ticket-id>
Action: comment
Text: the text comment
Attachment: an attachment filename/path
</pre>

Action can be "<code>comment</code>" or "<code>correspond</code>". For a list of fields you can use in correspondence, try "<code>/opt/rt3/bin/rt correspond ticket/1</code>"

If your comment contains multiple lines, each new line must be preceded by a space (e.g. "line 1\n line 2").

If you want to use HTML replies, use <pre>Content-Type: text/html</pre>

If you used "<code>Attachment</code>", you must add to your POST a variable "<code>attachment_1</code>" that contains the raw attachment in multi-part file object.

You can upload more attachments as well, in this case you have to separate the file names in the "<code style="border-style: initial; border-color: initial; ">Attachment</code>" with "\n "(a newline and space, without quotes) and add a new variable "attachment_$i" to your POST where $i is the index of attachment.

You need to send header to post comments

==== Ticket Links Edit ====
To update links on an existing ticket: POST on "<code>/REST/1.0/ticket/<ticket-id>/links</code>" with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line (like the one displayed when issuing "<code>ticket/<ticket-id>/links</code>"). Example:

<pre>
DependsOn: 54354
RefersTo: http://some.external/link
</pre>

=== User Properties ===

Gets the data for a single user.

Request: <code>/REST/1.0/user/<user-id></code>

RT/3.8.4 200 Ok

id: user/<user-id>
Name: <...>
Password: ********
EmailAddress: <...>
RealName: <...>
Organization: <...>
Privileged: <...>
Disabled: <...>

Also you can use user login instead of user ID.

=== ===

==== User Create ====

To create a new user: post on <code>/REST/1.0/user/new</code> with a variable named "<code>content</code>", containing "<code>key: value</code>" line by line, like the response to <code>/user/<ticket-id></code>

==== User Edit ====
To update an existing user: post on <code>/REST/1.0/user/<user-id>/edit</code> with a variable named "content", containing "key: value" line by line (like the one displayed when issuing <code>user/<user-id>/show</code>).

=== Queue Properties ===

Gets the data for a single queue.

Request: <code>/REST/1.0/queue/<queue-id></code>

RT/3.8.4 200 Ok

id: queue/<queue-id>
Name: <...>
Description: <...>
CorrespondAddress: <...>
CommentAddress: <...>
InitialPriority: <...>
FinalPriority: <...>
DefaultDueIn: <...>

=== Logout ===

To logout: post on <code>/REST/1.0/logout</code> with empty content.

== Types ==

*new
*open
*stalled
*resolved
*rejected
*deleted
+ other custom values defined in you local RT portal.

=== History entry type ===
* Create
* CustomField
* EmailRecord
* Status
* CommentEmailRecord
* Correspond
* Comment
* Priority
* Give
* Steal
* Take
* Untake
* AddWatcher
* DeleteWatcher
* AddLink
* DeleteLink
* AddReminder
* OpenReminder
* ResolveReminder
* Set
* Force
* Subject
* Told
* PurgeTransaction

== Miscellaneous ==
=== Data format ===
History entries time returns in UTC, boolean returns as <code>1</code> (true) and <code>0</code>(false).
Use only <code>"\n"</code>, not <code>"\r\n"</code>in post content.
Comments in response body starts with <code> </code>
#symbol.

=== Request status ===
To get real request/post status you need to check status code in first line of server response.

== Examples ==

=== Perl ===
To get the results of a single request (without setting the Session-Cookie) - assuming you've set:

* $uri to your RT REST URL
* $access_user to your username
* $access_password to your password
* $ticketNumber to the ticket you want to see

<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->agent("YOURUSERAGENTHERE");

my $response = $ua->post($uri."ticket/$ticketNumber",
['user' => $access_user, 'pass' => $access_password],
'Content_Type' => 'form-data');

if ($response->is_success) {
print $response->decoded_content;
}
</pre>

=== Java ===
<pre>
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class RtTicketCreator {
static final String BASE_URI = "http://rt.xxx.com/REST/1.0";

public static void main(String[] args) throws IOException {

PostMethod mPost = new PostMethod(BASE_URI + "/ticket/new?user=username&pass=password");
Part[] parts = { new StringPart("content", "Queue: General\nSubject: 123") };
mPost.setRequestEntity(new MultipartRequestEntity(parts, mPost.getParams()));
HttpClient cl = new HttpClient();
cl.executeMethod(mPost);
System.out.println(mPost.getResponseBodyAsString());
}
}
</pre>
=== Java ( Based on new Apache HttpComponents library ) ===
<pre>
/*
* RT ticket creator based on the current Apache HttpComponents library 4.1.3
* Created by Koustubha Kale, kmkale at youtility dot in
*/
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class NewApacheHttpcomponentsRtTicketCreator {

public static void main(String[] args) throws Exception {

DefaultHttpClient httpclient = new DefaultHttpClient();
try {

HttpPost httppost = new HttpPost("http://rt.xxx.com/rt/REST/1.0" +
"/ticket/new?user=username&pass=password");
StringBody content = new StringBody("Queue: General\nSubject: 123");
MultipartEntity reqEntity = new MultipartEntity();
reqEntity.addPart("content", content);
httppost.setEntity(reqEntity);
System.out.println("executing request " + httppost.getRequestLine());
HttpResponse response = httpclient.execute(httppost);
HttpEntity resEntity = response.getEntity();

System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (resEntity != null) {
System.out.println("Response content length: " + resEntity.getContentLength());
}
EntityUtils.consume(resEntity);
} finally {
try { httpclient.getConnectionManager().shutdown(); } catch (Exception ignore) {}
}
}

}
</pre>

=== Python ===
<pre>
import cookielib
import urllib
import urllib2

# creates a cookie for the rtserver with the credentials given at initialization.
# define your credentials here
access_user = 'your_login'
access_password = 'your_password'

# here is the RequestTracker URI we try to access
uri = 'http://your-rt-instance.com/REST/1.0/'

# trying login on rt server
cj = cookielib.LWPCookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
urllib2.install_opener(opener)
data = {'user': access_user, 'pass': access_password}
ldata = urllib.urlencode(data)
login = urllib2.Request(uri, ldata)
try:
response = urllib2.urlopen(login)
print response.read()
print "login successful"
except urllib2.URLError:
# could not connect to server
print "Not able to login"
</pre>

=== Ruby ===
<pre>
#!/usr/bin/env ruby
require 'net/http'

user = 'username'
pass = 'password'
uri = URI('https://rt.example.com/REST/1.0/ticket/123/show')

req = Net::HTTP::Post.new(uri.path)
req.set_form_data('user' => user, 'pass' => pass)

res = Net::HTTP.start(uri.hostname, uri.port,
:use_ssl => uri.scheme == 'https',
:set_debug_output => $stderr) do |http|
http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
# OK
puts "HTTP response code: #{res.code}"
puts "HTTP message: #{res.message}"
puts "Response:"

res.each do |key,val|
puts "#{key} => #{val}"
end

puts "Data:"
puts res.body
else
res.value
end
</pre>

=== PHP ===
<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/<ticket id>/show?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_GET);
/* if you want's to pass additional parameters */
$request->addQueryData(array());
$response = $request->send();
print_r($response);
</pre> OR<pre>
$username = rt_user;
$password = rt_pass;
$url = "http://server.domain.tld/REST/1.0/ticket/new?user=$username&pass=$password";
$request = new HttpRequest($url, HTTP_METH_POST);
// Note : to add data in custom fields you need to add element like below example
// in $post_data array
// Example : \nCF-customfield1:testdata
$post_data=array("content"=>"Queue: General\nRequestor: user@domain\nSubject: REST test 1\nOwner: userX\nAdminCc: userX\nText: This is a REST test\n");
$request->addPostFields($post_data);
try
{
response = $request->send()->getBody();
print_r($response);
}catch (HttpException $ex) {
echo $ex;
}</pre>

=== C# ===

<pre>
// Using "WCF REST Starter Kit" (http://msdn.microsoft.com/en-us/netframework/cc950529.aspx)
using (var client = new HttpClient("http://rt.site.com/REST/1.0/"))
{
client.TransportSettings.Cookies = new CookieContainer();

var form = new HttpUrlEncodedForm();
form.Add("user", "LOGIN");
form.Add("pass", "PASSWORD");

client.Post(string.Empty, form.CreateHttpContent());

// 1. Get ticket data
using (var request = client.Get("ticket/1234/show"))
{
string content = request.Content.ReadAsString();
// Some logic
}

// 2. Post ticket reply with attachment
var formPost = new HttpMultipartMimeForm();
byte[] attachment = new byte[];
string content = string.Empty;

// Store data in attachment
// Store data in content string ("Field: Value" line by line)
// ...

formPost.Add("content", content);
formPost.Add("attachment_1", "attachment_1", HttpContent.Create(attachment, "application/octet-stream"));

using (var post = client.Post("ticket/1234/comment"), formPost.CreateHttpContent()))
// Some logic
}</pre>

===Powershell (v3)===
* Escape Powershell reserved chars in user/pass
* If connecting via SSL, use fqdn of server, not cname
*Use `n (newline) when composing new ticket structure
Read RT queue based on query:
<pre>
$servername="Your Servername here"
$u="user=Username"
$p="pass=Password"
$q="search/ticket?query=(Status='open' OR Status='new') AND (Queue='GENERAL' OR Queue='FOO') AND Owner='Nobody'"
$uri="https://" + $servername + "/rt/REST/1.0/" + $q + "&" + $u + "&" + $p
$RT=Invoke-WebRequest -Uri $uri -SessionVariable sess
$rt.Content
</pre>

===VB.NET===
<pre>
Public Sub AddAttachmentToRT(ByVal url As String, ByVal fileName As String, ByVal filePath As String)

Dim dataBoundary As String = "--xYzZY"
Dim request As HttpWebRequest
Dim fileType As String = "image/jpeg"

'Create a POST web request to the REST interface using the passed URL
request = CType(WebRequest.Create(url), HttpWebRequest)
request.ContentType = "multipart/form-data; boundary=xYzZY"
request.Method = "POST"
request.KeepAlive = True

'Write the request to the requestStream
Using requestStream As IO.Stream = request.GetRequestStream()

'Create a variable "attachment_1" in the POST, specify the file name and file type
Dim preAttachment As String = dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""attachment_1""; filename=""" + fileName + """" + vbCrLf _
+ "Content-Type: " + fileType + vbCrLf _
+ vbCrLf

'Convert this preAttachment string to bytes
Dim preAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(preAttachment)

'Write this preAttachment string to the stream
requestStream.Write(preAttachmentBytes, 0, preAttachmentBytes.Length)

'Write the file as bytes to the stream by passing its exact location
Using fileStream As New IO.FileStream(Server.MapPath(filePath + fileName), IO.FileMode.Open, IO.FileAccess.Read)

Dim buffer(4096) As Byte
Dim bytesRead As Int32 = fileStream.Read(buffer, 0, buffer.Length)

Do While (bytesRead > 0)

requestStream.Write(buffer, 0, bytesRead)
bytesRead = fileStream.Read(buffer, 0, buffer.Length)

Loop

End Using

'Create a variable named content in the POST, specify the attachment name and comment text
Dim postAttachment As String = vbCrLf _
+ dataBoundary + vbCrLf _
+ "Content-Disposition: form-data; name=""content""" + vbCrLf _
+ vbCrLf _
+ "Action: comment" + vbLf _
+ "Attachment: " + fileName + vbCrLf _
+ "Text: Whatever You Want" + vbCrLf _
+ vbCrLf _
+ "--xYzZY--"

'Convert postAttachment string to bytes
Dim postAttachmentBytes As Byte() = System.Text.Encoding.UTF8.GetBytes(postAttachment)

'Write the postAttachment string to the stream
requestStream.Write(postAttachmentBytes, 0, postAttachmentBytes.Length)

End Using

Dim response As Net.WebResponse = Nothing

'Get the response from our REST request to RT
'Required to capture response, without this Try-Catch attaching will fail
Try
response = request.GetResponse()

Using responseStream As IO.Stream = response.GetResponseStream()

Using responseReader As New IO.StreamReader(responseStream)

Dim responseText = responseReader.ReadToEnd()

End Using

End Using

Catch exception As Net.WebException

response = exception.Response

If (response IsNot Nothing) Then

Using reader As New IO.StreamReader(response.GetResponseStream())

Dim responseText = reader.ReadToEnd()

End Using

response.Close()

End If

Finally

request = Nothing

End Try

End Sub
</pre>
===JavaScript===
This is an example of updating the RefersTo field for a ticket. Assuming Zepto/jQuery is also being used.
function link_back(url, ticket_num, rt) {
var data, link;
link = "refersto: " + url;
data = {"content": link};

$.ajax({
type: "POST",
url: rt + ticket_num + "/links",
data: data,
success: function (reply) {
console.log(reply);
}
});
}

var url = "https://www.wikipedia.org/";
var ticket_num = "123456";
var rt = "https://some.rt.url/REST/1.0/ticket/";

link_back(url, ticket_num, rt);

== Convenience libraries ==

There are libraries which do much of the low-level work shown in the examples below for you, and provide an easier programming interface for dealing with RT:
{| class="wikitable"
!Language
!Package/Module
!Source
!Example
!Note
|-
|'''Perl'''
|[http://metacpan.org/module/RT::Client::REST RT::Client::REST]
|[http://rt-client-rest.googlecode.com/svn/trunk/ Google Code]
|<code>"perl -MCPAN -e install RT::Client::REST"</code>
|
|-
|'''Ruby'''
|[http://rt-client.rubyforge.org RT-Client]
|[http://rubygems.org/gems/rt-client RubyGems]
|<code>gem install rt-client</code>
|
|-
|'''Ruby'''
|[http://rubygems.org/gems/roart Roart]
|[https://github.com/pjdavis/roart GitHub]
|<code>gem install roart</code>
|
|-
|'''Python'''
|[https://github.com/z4r/python-rtkit rtkit]
|[https://github.com/ GitHub]
|<code>pip install python-rtkit</code>
|
|-
|'''Python'''
|[https://gitlab.labs.nic.cz/labs/python-rt python-rt]
|[https://gitlab.labs.nic.cz GitLab]
|<code>pip install rt</code>
|
|-
|'''Java'''
|[http://projects.boksa.de/RT-REST/ RT-REST]
|[https://github.com/bboksa/RT-REST GitHub]
|<code>N/A</code>
|
|-
|'''PHP'''
|[https://github.com/dersam/RTPHPLib RTPHPLib]
|[https://github.com/dersam/RTPHPLib GitHub]
|composer require dersam/rt-php-lib
|
|}