.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "RT::Extension::CommandByMail 3pm" .TH RT::Extension::CommandByMail 3pm "2023-03-05" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" RT::Extension::CommandByMail \- Change ticket metadata via email .SH "RT VERSION" .IX Header "RT VERSION" Works with \s-1RT 4.0, 4.2, 4.4, 5.0\s0 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& (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 .Ve .SH "IMPORTANT" .IX Header "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 \&\f(CW$CommandByMailErrorOnUnknown\fR under \*(L"Configuration\*(R" for more information. .SH "INSTALLATION" .IX Header "INSTALLATION" .ie n .IP """perl Makefile.PL""" 4 .el .IP "\f(CWperl Makefile.PL\fR" 4 .IX Item "perl Makefile.PL" .PD 0 .ie n .IP """make""" 4 .el .IP "\f(CWmake\fR" 4 .IX Item "make" .ie n .IP """make install""" 4 .el .IP "\f(CWmake install\fR" 4 .IX Item "make install" .PD May need root permissions .IP "Edit your \fI/opt/rt5/etc/RT_SiteConfig.pm\fR" 4 .IX Item "Edit your /opt/rt5/etc/RT_SiteConfig.pm" If you are using \s-1RT 4.2\s0 or greater, add this line: .Sp .Vb 1 \& Plugin(\*(AqRT::Extension::CommandByMail\*(Aq); .Ve .Sp For \s-1RT 4.0,\s0 add this line: .Sp .Vb 1 \& Set(@Plugins, qw(RT::Extension::CommandByMail)); .Ve .Sp or add \f(CW\*(C`RT::Extension::CommandByMail\*(C'\fR to your existing \f(CW@Plugins\fR line. .Sp For \s-1RT 4.2\s0 or older, also add \f(CW\*(C`Filter::TakeAction\*(C'\fR to your \&\f(CW@MailPlugins\fR configuration, as follows: .Sp .Vb 1 \& Set(@MailPlugins, qw(Auth::MailFrom Filter::TakeAction)); .Ve .Sp For \s-1RT 4.4\s0 or newer, the plugin code is in \f(CW\*(C`Action::CommandByMail\*(C'\fR, so add this: .Sp .Vb 1 \& Set(@MailPlugins, qw(Auth::MailFrom Action::CommandByMail)); .Ve .Sp Be sure to include \f(CW\*(C`Auth::MailFrom\*(C'\fR in the list as well. .Sp \&\fBNote:\fR The plugin name has changed for \s-1RT 4.4,\s0 so after upgrading you must also update your \f(CW\*(C`RT_SiteConfig.pm\*(C'\fR file to change \&\f(CW\*(C`Filter::TakeAction\*(C'\fR to the new \f(CW\*(C`Action::CommandByMail\*(C'\fR. .IP "Patch \s-1RT\s0" 4 .IX Item "Patch RT" For \s-1RT 4.4.0,\s0 apply the included patch: .Sp .Vb 2 \& cd /opt/rt4 # Your location may be different \& patch \-p1 < /download/dir/RT\-Extension\-CommandByMail/etc/handle_action_pass_currentuser.patch .Ve .IP "Restart your webserver" 4 .IX Item "Restart your webserver" .SH "CONFIGURATION" .IX Header "CONFIGURATION" In addition to adding the configuration above to activate the extension in \&\s-1RT,\s0 the following options are available. .ie n .SS "$CommandByMailGroup" .el .SS "\f(CW$CommandByMailGroup\fP" .IX Subsection "$CommandByMailGroup" You may set a \f(CW$CommandByMailGroup\fR to a particular group \s-1ID\s0 in RT_SiteConfig. If set, only members of this group may perform commands by mail. .ie n .SS "$CommandByMailHeader" .el .SS "\f(CW$CommandByMailHeader\fP" .IX Subsection "$CommandByMailHeader" You may set this configuration value to the name of a header to examine as well. For example: .PP .Vb 1 \& Set($CommandByMailHeader, "X\-RT\-Command"); .Ve .ie n .SS "$CommandByMailOnlyHeaders" .el .SS "\f(CW$CommandByMailOnlyHeaders\fP" .IX Subsection "$CommandByMailOnlyHeaders" If set, the body will not be examined, only the header defined by the previous configuration option. .ie n .SS "$CommandByMailErrorOnUnknown" .el .SS "\f(CW$CommandByMailErrorOnUnknown\fP" .IX Subsection "$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. .SH "CAVEATS" .IX Header "CAVEATS" This extension is incompatible with \f(CW\*(C`UnsafeEmailCommands\*(C'\fR \s-1RT\s0 option. .SH "DESCRIPTION" .IX Header "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. .PP \&\fB\s-1CAVEAT:\s0\fR 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 \s-1HTML.\s0 .SS "\s-1FORMAT\s0" .IX Subsection "FORMAT" This extension parses the body, and optionally a header, in incoming messages for commands to update ticket metadata. The format of commands is: .PP .Vb 3 \& Command: value \& Command: value \& ... .Ve .PP You can find list of \*(L"\s-1COMMANDS\*(R"\s0 below. .PP 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 \f(CW\*(C`Add\*(C'\fR and \f(CW\*(C`Del\*(C'\fR prefixes to add/delete values from the current list of the ticket you reply to or comment on. .SS "\s-1COMMANDS\s0" .IX Subsection "COMMANDS" \fIBasic\fR .IX Subsection "Basic" .IP "Queue: " 4 .IX Item "Queue: " Set new queue for the ticket .IP "Subject: " 4 .IX Item "Subject: " Set new subject to the given string .IP "Status: " 4 .IX Item "Status: " Set new status, one of new, open, stalled, resolved, rejected or deleted .IP "Owner: " 4 .IX Item "Owner: " Set new owner using the given username .IP "Priority: <#>" 4 .IX Item "Priority: <#>" Set new priority to the given value .IP "FinalPriority: <#>" 4 .IX Item "FinalPriority: <#>" Set new final priority to the given value .PP \fIDates\fR .IX Subsection "Dates" .PP Set new date/timestamp, or 0 to unset: .PP .Vb 3 \& Due: \& Starts: \& Started: .Ve .PP \fITime\fR .IX Subsection "Time" .PP Set new times to the given value in minutes. Note that on correspond/comment \fB\f(CB\*(C`TimeWorked\*(C'\fB add time\fR to the current value. .PP .Vb 3 \& TimeWorked: \& TimeEstimated: \& TimeLeft: .Ve .PP \fIWatchers\fR .IX Subsection "Watchers" .PP Manage watchers: requestors, ccs and admin ccs. This commands can be used several times and/or with \f(CW\*(C`Add\*(C'\fR and \f(CW\*(C`Del\*(C'\fR prefixes, for example \f(CW\*(C`Requestor\*(C'\fR command set requestor(s) and the current requestors would be deleted, but \f(CW\*(C`AddRequestor\*(C'\fR command adds to the current list. .PP .Vb 9 \& Requestor:
Set requestor(s) using the email address \& AddRequestor:
Add new requestor using the email address \& DelRequestor:
Remove email address as requestor \& Cc:
Set Cc watcher(s) using the email address \& AddCc:
Add new Cc watcher using the email address \& DelCc:
Remove email address as Cc watcher \& AdminCc:
Set AdminCc watcher(s) using the email address \& AddAdminCc:
Add new AdminCc watcher using the email address \& DelAdminCc:
Remove email address as AdminCc watcher .Ve .PP \fILinks\fR .IX Subsection "Links" .PP Manage links. These commands are also could be used several times in one message. .PP .Vb 6 \& DependsOn: \& DependedOnBy: \& RefersTo: \& ReferredToBy: \& Members: \& MemberOf: .Ve .PP \fICustom field values\fR .IX Subsection "Custom field values" .PP Manage custom field values. Could be used multiple times. (The curly braces are literal.) .PP .Vb 3 \& CustomField.{}: \& AddCustomField.{}: \& DelCustomField.{}: .Ve .PP Short forms: .PP .Vb 3 \& CF.{}: \& AddCF.{}: \& DelCF.{}: .Ve .PP \fITransaction Custom field values\fR .IX Subsection "Transaction Custom field values" .PP Manage custom field values of transactions. Could be used multiple times. (The curly braces are literal.) .PP .Vb 1 \& TransactionCustomField.{}: .Ve .PP Short forms: .PP .Vb 3 \& TxnCustomField.{}: \& TransactionCF.{}: \& TxnCF.{}: .Ve .SH "SECURITY" .IX Header "SECURITY" This extension has no extended auth system; so all security issues that apply to the \s-1RT\s0 in general also apply to the extension. .SH "METHODS" .IX Header "METHODS" .SS "ProcessCommands" .IX Subsection "ProcessCommands" This method provides the main email processing functionality. It supports both \s-1RT 4.2\s0 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. .PP For 4.4, returning \f(CW\*(C`{ DeferToRT => 1 }\*(C'\fR invokes the normal \s-1RT\s0 mail processing flow. This allows CommandByMail to pass on processing an email message for cases like a user not being a member of \f(CW\*(C`CommandByMailGroup\*(C'\fR. .SS "ParseCcAddressesFromHead \s-1HASH\s0" .IX Subsection "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 the current Queue's email addresses, the CurrentUser's email address and anything that the configuration sub RT::IsRTAddress matches. .SH "AUTHOR" .IX Header "AUTHOR" Best Practical Solutions, \s-1LLC\s0 .SH "BUGS" .IX Header "BUGS" All bugs should be reported via email to .PP .Vb 1 \& L .Ve .PP or via the web at .PP .Vb 1 \& L. .Ve .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" This software is Copyright (c) 2014\-2020 by Best Practical Solutions .PP This is free software, licensed under: .PP .Vb 1 \& The GNU General Public License, Version 2, June 1991 .Ve