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
    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.

        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.

        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

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

