Supported fields

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.

Custom field validation (Input must match [Mandatory])

Not all pages where you can change status are supported

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

Multiple-entry CFs do not play well with "must_be" and "must_not_be"

Requiring Any Value

    Set( %MandatoryOnTransition,
        Helpdesk => {
            '* -> resolved'      => ['TimeWorked', 'CF.Resolution', 'CustomRole.Analyst'],
        },
        '*' => {
            '* -> resolved' => ['CF.Category'],
        },
    );

The transition syntax is similar to that found in RT's Lifecycles. See "perldoc /opt/rt5/etc/RT_Config.pm".

Requiring role values

    Set( %MandatoryOnTransition,
        'General' => {
            '* -> resolved' => ['CustomRole.customer', 'Owner'],
        },
    );

Role Membership in a Group

    Set( %MandatoryOnTransition,
        'General' => {
            'open -> *' => ['Owner'],
            'Owner' => { transition => 'open -> *', group => ['SupportReps', 'Admins'] },
        }
    );

Restrictions on Queue Transitions

    Set( %MandatoryOnTransition,
        Helpdesk => {
            'Engineering' => ['CF.Category'],
        },
    );

The key is the destination queue and the values are the mandatory fields. In this case, before a user can move a ticket from the Helpdesk queue to the Engineering queue, they must provide a value for Category, possibly something like "bug" or "feature request".

Note that this configuration makes the most sense if the custom fields are applied to both queues. Otherwise the users on the destination queue won't be able to see the required values.

Requiring or Restricting Specific Values

    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

    Set($ShowAllCustomFieldsOnMandatoryUpdate, 1);

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

Returns three array refs of required fields for the described status transition. The first is core fields, the second is CF names, the third is roles. Returns empty array refs on error or if nothing is required.

A fourth returned parameter is a hashref of must-have values for custom fields.

The fifth parameter is a hashref of groups a role member must be in.

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. In this case, the From status should be the special flag value of '__CREATE__'.

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.