Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RT::Extension::MandatoUserTContributed)RT::Extension::MandatoryOnTransition(3)

NAME
       RT-Extension-MandatoryOnTransition - Require core fields	and ticket
       custom fields on	status transitions

RT VERSION
       Works with RT 4.0, 4.2, 4.4

       See below for some restrictions on RT 4.0.

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.

   Not all pages where you can change status are supported
       SelfService, for	example.  See "TODO" for others.

       On 4.0, Basics and Jumbo	are not	supported because they do not have the
       needed code, which is present in	4.2.

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::MandatoryOnTransition');

	   For RT 4.0, add this	line:

	       Set(@Plugins, qw(RT::Extension::MandatoryOnTransition));

	   or add "RT::Extension::MandatoryOnTransition" to your existing
	   @Plugins line.

       Clear your mason	cache
	       rm -rf /opt/rt4/var/mason_data/obj

       Restart your webserver

CONFIGURATION
       To define which fields should be	mandatory on certain status changes
       (either globally	or in a	specific queue)	use 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.

   Requiring Any Value
       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".

   Requiring or	Restricting Specific Values
       Sometimes you want to restrict a	transition if a	field has a specific
       value (maybe a ticket can't be resolved if System Status	= down)	or
       require a specific value	to to allow a transition (ticket can't be
       resolved	unless a problem was fixed). To	enforce	specific values, you
       can add the following:

	   Set(	%MandatoryOnTransition,
	       Helpdesk	=> {
		   '* -> resolved' => ['TimeWorked', 'CF.Resolution', 'CF.System Status'],
		   'CF.Resolution' => {	transition => '* -> resolved', must_be => ['fixed', 'not an issue'] },
		   'CF.System Status' => { transition => '* -> resolved', must_not_be => ['reduced', 'down']}
	       },
	   );

       This will then enforce both that	the value is set and that it either
       has one of the required values on the configured	transition or does not
       have one	of the restricted values.

       Note that you need to specify the transition the	rule applies to	since
       a given queue configuration could have multiple transition rules.

   $ShowAllCustomFieldsOnMandatoryUpdate
       By default, this	extension shows	only the mandatory fields on the
       update page to make it easy for users to	fill them out when completing
       an action. If you would like to show all	custom fields rather than just
       the mandatory ones, use this configuration option. You can set it like
       this:

	   Set($ShowAllCustomFieldsOnMandatoryUpdate, 1);

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.

	   If your core	field is called	different things on Update.html	and
	   Modify.html you will	need to	modify the Modify.html/Default
	   callback so the the extension knows what field to use.  Look	at
	   TimeWorked vs UpdateTimeWorked for an example.

       %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

       Full Validation of Configuration
	       Check that all CFs are actually CFs applied to the indicated queues (or global).	Also
	       validate	additional CF's	with "must" configuration are defined in a transition.

       Allow empty values in "must" configuration
	       When defining a list of "must be" or "must not be" values, there	may be use cases where
	       an empty	value could be valid. Provide a	way to specify and allow this.

AUTHOR
       Best Practical Solutions, LLC <modules@bestpractical.com>

BUGS
       All bugs	should be reported via email to

	   L<bug-RT-Extension-MandatoryOnTransition@rt.cpan.org|mailto:bug-RT-Extension-MandatoryOnTransition@rt.cpan.org>

       or via the web at

	   L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-MandatoryOnTransition>.

LICENSE	AND COPYRIGHT
       This software is	Copyright (c) 2012-2014	by Best	Pracical Solutions,
       LLC.

       This is free software, licensed under:

	 The GNU General Public	License, Version 2, June 1991

perl v5.24.1			  2016-RT::Extension::MandatoryOnTransition(3)

NAME | RT VERSION | DESCRIPTION | CAVEATS | INSTALLATION | CONFIGURATION | IMPLEMENTATION DETAILS | TODO | AUTHOR | BUGS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RT::Extension::MandatoryOnTransition&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help