Commit ff4edfd6 authored by Thomas Sibley's avatar Thomas Sibley
Browse files

Add the README to git for github

parent d2bb36fe
......@@ -7,7 +7,6 @@ pm_to_blib*
cover_db
pod2htm*.tmp
/RT-Extension-MandatoryOnTransition*
README
*.bak
*.swp
/MYMETA.*
......
NAME
RT-Extension-MandatoryOnTransition - Require core fields and ticket
custom fields on status transitions
DESCRIPTION
This RT extension enforces that certain fields have values before
tickets are explicitly moved to or from specified statuses. If you list
custom fields which must have a value before a ticket is resolved, those
custom fields will automatically show up on the "Resolve" page. The
reply/comment won't be allowed until a value is provided.
See the configuration example under "INSTALLATION".
Supported fields
This extension only enforces mandatory-ness on defined status
transitions.
Basics
Currently the following are supported:
Content
Requires an update message (reply/comment text) before the
transition.
TimeWorked
Requires the ticket has a non-zero amount of Time Worked recorded
already or that time worked will be recorded with the current
reply/comment in the Worked field on the update page.
TimeTaken
Requires that the Worked field on the update page is non-zero.
A larger set of basic fields may be supported in future releases. If
you'd like to see additional fields added, please email your request to
the bug address at the bottom of this documentation.
Custom fields
Ticket custom fields of all types are supported.
CAVEATS
Custom field validation (*Input must match [Mandatory]*)
The custom fields enforced by this extension are validated by the
standard RT rules. If you've set Validation patterns for your custom
fields, those will be checked before mandatory-ness is checked. Setting
a CFs Validation to "(?#Mandatory)." will not magically make it enforced
by this extension.
Actions menu
This extension does not affect "quick actions" (those without an update
type) configured in your lifecycle (and appearing in the ticket Actions
menu). If you're requiring fields on resolve, for example, and don't
want folks to have a "Quick Resolve" button that skips the required
fields, adjust your lifecycle config to provide an update type (i.e make
it a non-quick action). Quick actions may be supported in a future
release.
Not all pages where you can change status are supported
The ticket Basics page, for example. See "TODO" for others.
INSTALLATION
perl Makefile.PL
make
make install
May need root permissions
patch -p1 < 4.0.8-additional-mobile-callbacks-plus-style.diff
Run the above in your /opt/rt4 directory to patch RT if on version
4.0.8 or older.
Enable and configure this extension
Add this line to </opt/rt4/etc/RT_SiteConfig.pm>:
Set(@Plugins, qw(RT::Extension::MandatoryOnTransition));
or add "RT::Extension::MandatoryOnTransition" to your existing
@Plugins line.
Then configure which fields should be mandatory on certain status
changes (either globally or in a specific queue) using the
%MandatoryOnTransition config option. This option takes the generic
form of:
Set( %MandatoryOnTransition,
'QueueName' => {
'from -> to' => [ 'BasicField', 'CF.MyField', ],
},
);
"from" and "to" are expected to be valid status names. "from" may
also be "*" which will apply to any status and also tickets about to
be created with status "to".
The fallback for queues without specific rules is specified with '*'
where the queue name would normally be.
Below is an example which requires 1) time worked and filling in a
custom field named Resolution before resolving tickets in the
Helpdesk queue and 2) a Category selection before resolving tickets
in every other queue.
Set( %MandatoryOnTransition,
Helpdesk => {
'* -> resolved' => ['TimeWorked', 'CF.Resolution'],
},
'*' => {
'* -> resolved' => 'CF.Category',
},
);
The transition syntax is similar to that found in RT's Lifecycles.
See "perldoc /opt/rt4/etc/RT_Config.pm".
Clear your mason cache
rm -rf /opt/rt4/var/mason_data/obj
Restart your webserver
IMPLEMENTATION DETAILS
If you're just using this module on your own RT instance, you should
stop reading now. You don't need to know about the implementation
details unless you're writing a patch against this extension.
Package variables
@CORE_SUPPORTED
The core (basic) fields supported by the extension. Anything else
configured but not in this list is stripped.
@CORE_TICKET
The core (basic) fields which should be called as methods on ticket
objects to check for current values.
%CORE_FOR_UPDATE
A mapping which translates core fields into their form input names.
For example, Content is submitted as UpdateContent. All fields must
be mapped, even if they are named exactly as listed in
@CORE_SUPPORTED. A supported field which doesn't appear in the
mapping is skipped, the implication being that it isn't available
during update.
%CORE_FOR_CREATE
A mapping similar to %CORE_FOR_UPDATE but consulted during ticket
creation. The same rules and restrictions apply.
If you're looking to add support for other core fields, you'll need to
push into @CORE_SUPPORTED and possibly @CORE_TICKET. You'll also need to
add a pair to %CORE_FOR_UPDATE and/or %CORE_FOR_CREATE.
Methods
RequiredFields
Returns two array refs of required fields for the described status
transition. The first is core fields, the second is CF names. Returns
empty array refs on error or if nothing is required.
Takes a paramhash with the keys Ticket, Queue, From, and To. Ticket
should be an object. Queue should be a name. From and To should be
statuses. If you specify Ticket, only To is otherwise necessary. If you
omit Ticket, From, To, and Queue are all necessary.
The first transition found in the order below is used:
from -> to
* -> to
from -> *
CheckMandatoryFields
Pulls core and custom mandatory fields from the configuration and checks
that they have a value set before transitioning to the requested status.
Accepts a paramhash of values: ARGSRef => Reference to Mason ARGS Ticket
=> ticket object being updated Queue => Queue object for the queue in
which a new ticket is being created From => Ticket status transitioning
from To => Ticket status transitioning to
Works for both create, where no ticket exists yet, and update on an
existing ticket. ARGSRef is required for both.
For create, you must also pass Queue, From, and To.
Update requires only Ticket and To since From can be fetched from the
ticket object.
Config
Takes a queue name. Returns a hashref for the given queue (possibly
using the fallback rules) which contains keys of transitions and values
of arrayrefs of fields.
You shouldn't need to use this directly.
TODO
Enforcement on Create
index.html / QuickCreate - Not yet implemented.
SelfService - Not yet implemented.
Enforcement on other update pages
SelfService - can't do it without patches to <form> POST + additional callbacks
Basics - need to patch callback for skipping (at least)
Jumbo - need to patch callback for skipping (at least)
BUGS
All bugs should be reported via
<http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-Mandatory
OnTransition> or bug-RT-Extension-MandatoryOnTransition@rt.cpan.org.
AUTHOR
Thomas Sibley <trs@bestpractical.com>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2012 by Best Practical Solutions
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment