NAME
RT::Extension::CommandByMail - Change ticket metadata via email
RT VERSION
Works with RT 4.0, 4.2, 4.4
SYNOPSIS
(Send email with content that looks like the following.)
Status: stalled
Subject: change subject
AddAdminCc: boss@example.com
AddCc: dev1@example.com
AddCc: dev2@example.com
The comment/reply text goes here
IMPORTANT
For users of versions of this extension prior to 3.0: Please note that
now you will not receive an unknown command error email for unknown
commands. There will be a warning in the logs whenever an unknown
command is encountered. A setting was added to restore the previous
behavior. See the setting $CommandByMailErrorOnUnknown under
"Configuration" for more information.
INSTALLATION
perl Makefile.PL
make
make install
May need root permissions
Edit your /opt/rt4/etc/RT_SiteConfig.pm
If you are using RT 4.2 or greater, add this line:
Plugin('RT::Extension::CommandByMail');
For RT 4.0, add this line:
Set(@Plugins, qw(RT::Extension::CommandByMail));
or add RT::Extension::CommandByMail to your existing @Plugins line.
For RT 4.2 or older, also add Filter::TakeAction to your
@MailPlugins configuration, as follows:
Set(@MailPlugins, qw(Auth::MailFrom Filter::TakeAction));
For RT 4.4 or newer, the plugin code is in Action::CommandByMail, so
add this:
Set(@MailPlugins, qw(Auth::MailFrom Action::CommandByMail));
Be sure to include Auth::MailFrom in the list as well.
Note: The plugin name has changed for RT 4.4, so after upgrading you
must also update your RT_SiteConfig.pm file to change
Filter::TakeAction to the new Action::CommandByMail.
Patch RT
For RT 4.4.0, apply the included patch:
cd /opt/rt4 # Your location may be different
patch -p1 < /download/dir/RT-Extension-CommandByMail/etc/handle_action_pass_currentuser.patch
Restart your webserver
CONFIGURATION
In addition to adding the configuration above to activate the extension
in RT, the following options are available.
$CommandByMailGroup
You may set a $CommandByMailGroup to a particular group ID in
RT_SiteConfig. If set, only members of this group may perform commands
by mail.
$CommandByMailHeader
You may set this configuration value to the name of a header to examine
as well. For example:
Set($CommandByMailHeader, "X-RT-Command");
$CommandByMailOnlyHeaders
If set, the body will not be examined, only the header defined by the
previous configuration option.
$CommandByMailErrorOnUnknown
Prior to 2.02, this extension throws an error if it finds an unknown
command. This is no longer the case. Setting this option will restore
that legacy behavior.
CAVEATS
This extension is incompatible with UnsafeEmailCommands RT option.
DESCRIPTION
This extension allows you to manage ticket metadata via email. You may
put commands into the beginning of an email, and the extension will
apply them. The list of commands is detailed below.
CAVEAT: commands are line oriented, so you can't expand to multiple
lines for each command, i.e. values can't contains new lines. The module
also currently expects and parses text, not HTML.
FORMAT
This extension parses the body, and optionally a header, in incoming
messages for commands to update ticket metadata. The format of commands
is:
Command: value
Command: value
...
You can find list of "COMMANDS" below.
Some commands (like Status, Queue and other) can be used only once.
Commands that manage lists can be used multiple times, for example link,
custom fields and watchers commands. Also, the latter can be used with
Add and Del prefixes to add/delete values from the current list of the
ticket you reply to or comment on.
COMMANDS
Basic
Queue: <name>
Set new queue for the ticket
Subject: <string>
Set new subject to the given string
Status: <status>
Set new status, one of new, open, stalled, resolved, rejected or
deleted
Owner: <username>
Set new owner using the given username
Priority: <#>
Set new priority to the given value
FinalPriority: <#>
Set new final priority to the given value
Dates
Set new date/timestamp, or 0 to unset:
Due: <new timestamp>
Starts: <new timestamp>
Started: <new timestamp>
Time
Set new times to the given value in minutes. Note that on
correspond/comment TimeWorked add time to the current value.
TimeWorked: <minutes>
TimeEstimated: <minutes>
TimeLeft: <minutes>
Watchers
Manage watchers: requestors, ccs and admin ccs. This commands can be
used several times and/or with Add and Del prefixes, for example
Requestor comand set requestor(s) and the current requestors would be
deleted, but AddRequestor command adds to the current list.
Requestor: <address> Set requestor(s) using the email address
AddRequestor: <address> Add new requestor using the email address
DelRequestor: <address> Remove email address as requestor
Cc: <address> Set Cc watcher(s) using the email address
AddCc: <address> Add new Cc watcher using the email address
DelCc: <address> Remove email address as Cc watcher
AdminCc: <address> Set AdminCc watcher(s) using the email address
AddAdminCc: <address> Add new AdminCc watcher using the email address
DelAdminCc: <address> Remove email address as AdminCc watcher
Links
Manage links. These commands are also could be used several times in one
message.
DependsOn: <ticket id>
DependedOnBy: <ticket id>
RefersTo: <ticket id>
ReferredToBy: <ticket id>
Members: <ticket id>
MemberOf: <ticket id>
Custom field values
Manage custom field values. Could be used multiple times. (The curly
braces are literal.)
CustomField.{<CFName>}: <custom field value>
AddCustomField.{<CFName>}: <custom field value>
DelCustomField.{<CFName>}: <custom field value>
Short forms:
CF.{<CFName>}: <custom field value>
AddCF.{<CFName>}: <custom field value>
DelCF.{<CFName>}: <custom field value>
Transaction Custom field values
Manage custom field values of transactions. Could be used multiple
times. (The curly braces are literal.)
TransactionCustomField.{<CFName>}: <custom field value>
Short forms:
TxnCustomField.{<CFName>}: <custom field value>
TransactionCF.{<CFName>}: <custom field value>
TxnCF.{<CFName>}: <custom field value>
SECURITY
This extension has no extended auth system; so all security issues that
apply to the RT in general also apply to the extension.
METHODS
ProcessCommands
This method provides the main email processing functionality. It
supports both RT 4.2 and earlier and 4.4 and later. To do this, the
return hashes contain some values used by 4.2 code and some used by 4.4.
The return values coexist and unused values are ignored by the different
versions.
For 4.4, returning { DeferToRT => 1 } invokes the normal RT mail
processing flow. This allows CommandByMail to pass on processing an
email message for cases like a user not being a member of
CommandByMailGroup.
ParseCcAddressesFromHead HASH
Takes a hash containing QueueObj, Head and CurrentUser objects. Returns
a list of all email addresses in the To and Cc headers b<except> the
current Queue's email addresses, the CurrentUser's email address and
anything that the configuration sub RT::IsRTAddress matches.
AUTHOR
Best Practical Solutions, LLC <modules@bestpractical.com>
BUGS
All bugs should be reported via email to
L<bug-RT-Extension-CommandByMail@rt.cpan.org|mailto:bug-RT-Extension-CommandByMail@rt.cpan.org>
or via the web at
L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-CommandByMail>.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2014 by Best Practical Solutions
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991