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.

 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
   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 <[email protected]>

BUGS
   All bugs should be reported via email to

       L<[email protected]|mailto:[email protected]>

   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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.