1NAME
2 RT-Extension-MandatoryOnTransition - Require core fields and ticket
3 custom fields on status transitions
4
5RT VERSION
6 Works with RT 4.0, 4.2, 4.4, 5.0
7
8 See below for some restrictions on RT 4.0.
9
10DESCRIPTION
11 This RT extension enforces that certain fields have values before
12 tickets are explicitly moved to or from specified statuses. If you list
13 custom fields which must have a value before a ticket is resolved, those
14 custom fields will automatically show up on the "Resolve" page. The
15 reply/comment won't be allowed until a value is provided.
16
17 See the configuration example under "INSTALLATION".
18
19 Supported fields
20 This extension only enforces mandatory-ness on defined status
21 transitions. It also supports defining mandatory fields when
22 transitioning a ticket from one queue to another.
23
24 Basics
25 Currently the following are supported:
26
27 Content
28 Requires an update message (reply/comment text) before the
29 transition.
30
31 TimeWorked
32 Requires the ticket has a non-zero amount of Time Worked recorded
33 already or that time worked will be recorded with the current
34 reply/comment in the Worked field on the update page.
35
36 TimeTaken
37 Requires that the Worked field on the update page is non-zero.
38
39 A larger set of basic fields may be supported in future releases. If
40 you'd like to see additional fields added, please email your request to
41 the bug address at the bottom of this documentation.
42
43 Custom fields
44 Ticket custom fields of all types are supported.
45
46CAVEATS
47 Custom field validation (*Input must match [Mandatory]*)
48 The custom fields enforced by this extension are validated by the
49 standard RT rules. If you've set Validation patterns for your custom
50 fields, those will be checked before mandatory-ness is checked. Setting
51 a CFs Validation to (?#Mandatory). will not magically make it enforced
52 by this extension.
53
54 Not all pages where you can change status are supported
55 SelfService, for example. See "TODO" for others.
56
57 On 4.0, Basics and Jumbo are not supported because they do not have the
58 needed code, which is present in 4.2.
59
60 Multiple-entry CFs do not play well with must_be and must_not_be
61 The must_be and must_not_be configurations are currently not
62 well-defined for multiply-valued CFs. At current, only their first value
63 is validated against the configured whitelist or blacklist.
64
65INSTALLATION
66 perl Makefile.PL
67 make
68 make install
69 May need root permissions
70
71 Edit your /opt/rt5/etc/RT_SiteConfig.pm
72 If you are using RT 4.2 or greater, add this line:
73
74 Plugin('RT::Extension::MandatoryOnTransition');
75
76 For RT 4.0, add this line:
77
78 Set(@Plugins, qw(RT::Extension::MandatoryOnTransition));
79
80 or add RT::Extension::MandatoryOnTransition to your existing
81 @Plugins line.
82
83 Clear your mason cache
84 rm -rf /opt/rt5/var/mason_data/obj
85
86 Restart your webserver
87
88CONFIGURATION
89 To define which fields should be mandatory on certain status changes
90 (either globally or in a specific queue) use the %MandatoryOnTransition
91 config option. This option takes the generic form of:
92
93 Set( %MandatoryOnTransition,
94 'QueueName' => {
95 'from -> to' => [ 'BasicField', 'CF.MyField', 'CustomRole.MyRole' ],
96 },
97 );
98
99 from and to are expected to be valid status names. from may also be *
100 which will apply to any status and also tickets about to be created with
101 status to.
102
103 The fallback for queues without specific rules is specified with '*'
104 where the queue name would normally be.
105
106 Requiring Any Value
107 Below is an example which requires 1) time worked and filling in a
108 custom field named Resolution before resolving tickets in the Helpdesk
109 queue and 2) a Category selection before resolving tickets in every
110 other queue.
111
112 Set( %MandatoryOnTransition,
113 Helpdesk => {
114 '* -> resolved' => ['TimeWorked', 'CF.Resolution', 'CustomRole.Analyst'],
115 },
116 '*' => {
117 '* -> resolved' => ['CF.Category'],
118 },
119 );
120
121 The transition syntax is similar to that found in RT's Lifecycles. See
122 perldoc /opt/rt5/etc/RT_Config.pm.
123
124 Requiring role values
125 You can require any core or custom role on a RT::Ticket object, below is
126 an example of requiring a custom role "customer" be set on transition
127 from open and the owner also be set for the ticket on transition from a
128 status of open.
129
130 Set( %MandatoryOnTransition,
131 'General' => {
132 '* -> resolved' => ['CustomRole.customer', 'Owner'],
133 },
134 );
135
136 Role Membership in a Group
137 Roles can require the members of the role to also be a member of a group
138 before satisfying to mandatory condition. Below we require that the
139 Owner role be set and that the member it is set to is a member of the
140 group 'SupportReps' or 'Admins'.
141
142 Set( %MandatoryOnTransition,
143 'General' => {
144 'open -> *' => ['Owner'],
145 'Owner' => { transition => 'open -> *', group => ['SupportReps', 'Admins'] },
146 }
147 );
148
149 Restrictions on Queue Transitions
150 The default behavior for MandatoryOnTransition operates on status
151 transitions, so a change from new to open or from open to resolved. It
152 also supports making fields mandatory when transitioning from one queue
153 to another. To define fields that are required when changing the queue
154 for a ticket, add an entry to the configuration like this:
155
156 Set( %MandatoryOnTransition,
157 Helpdesk => {
158 'Engineering' => ['CF.Category'],
159 },
160 );
161
162 The key is the destination queue and the values are the mandatory
163 fields. In this case, before a user can move a ticket from the Helpdesk
164 queue to the Engineering queue, they must provide a value for Category,
165 possibly something like "bug" or "feature request".
166
167 Note that this configuration makes the most sense if the custom fields
168 are applied to both queues. Otherwise the users on the destination queue
169 won't be able to see the required values.
170
171 Requiring or Restricting Specific Values
172 Sometimes you want to restrict a transition if a field has a specific
173 value (maybe a ticket can't be resolved if System Status = down) or
174 require a specific value to to allow a transition (ticket can't be
175 resolved unless a problem was fixed). To enforce specific values, you
176 can add the following:
177
178 Set( %MandatoryOnTransition,
179 Helpdesk => {
180 '* -> resolved' => ['TimeWorked', 'CF.Resolution', 'CF.System Status'],
181 'CF.Resolution' => { transition => '* -> resolved', must_be => ['fixed', 'not an issue'] },
182 'CF.System Status' => { transition => '* -> resolved', must_not_be => ['reduced', 'down']}
183 },
184 );
185
186 This will then enforce both that the value is set and that it either has
187 one of the required values on the configured transition or does not have
188 one of the restricted values.
189
190 Note that you need to specify the transition the rule applies to since a
191 given queue configuration could have multiple transition rules.
192
193 $ShowAllCustomFieldsOnMandatoryUpdate
194 By default, this extension shows only the mandatory fields on the update
195 page to make it easy for users to fill them out when completing an
196 action. If you would like to show all custom fields rather than just the
197 mandatory ones, use this configuration option. You can set it like this:
198
199 Set($ShowAllCustomFieldsOnMandatoryUpdate, 1);
200
201IMPLEMENTATION DETAILS
202 If you're just using this module on your own RT instance, you should
203 stop reading now. You don't need to know about the implementation
204 details unless you're writing a patch against this extension.
205
206 Package variables
207 @CORE_SUPPORTED
208 The core (basic) fields supported by the extension. Anything else
209 configured but not in this list is stripped.
210
211 @CORE_TICKET
212 The core (basic) fields which should be called as methods on ticket
213 objects to check for current values.
214
215 %CORE_FOR_UPDATE
216 A mapping which translates core fields into their form input names.
217 For example, Content is submitted as UpdateContent. All fields must
218 be mapped, even if they are named exactly as listed in
219 @CORE_SUPPORTED. A supported field which doesn't appear in the
220 mapping is skipped, the implication being that it isn't available
221 during update.
222
223 If your core field is called different things on Update.html and
224 Modify.html you will need to modify the Modify.html/Default callback
225 so the the extension knows what field to use. Look at TimeWorked vs
226 UpdateTimeWorked for an example.
227
228 %CORE_FOR_CREATE
229 A mapping similar to %CORE_FOR_UPDATE but consulted during ticket
230 creation. The same rules and restrictions apply.
231
232 If you're looking to add support for other core fields, you'll need to
233 push into @CORE_SUPPORTED and possibly @CORE_TICKET. You'll also need to
234 add a pair to %CORE_FOR_UPDATE and/or %CORE_FOR_CREATE.
235
236 Methods
237 RequiredFields
238 Returns three array refs of required fields for the described status
239 transition. The first is core fields, the second is CF names, the third
240 is roles. Returns empty array refs on error or if nothing is required.
241
242 A fourth returned parameter is a hashref of must-have values for custom
243 fields.
244
245 The fifth parameter is a hashref of groups a role member must be in.
246
247 Takes a paramhash with the keys Ticket, Queue, From, and To. Ticket
248 should be an object. Queue should be a name. From and To should be
249 statuses. If you specify Ticket, only To is otherwise necessary. If you
250 omit Ticket, From, To, and Queue are all necessary.
251
252 The first transition found in the order below is used:
253
254 from -> to
255 * -> to
256 from -> *
257
258 CheckMandatoryFields
259 Pulls core and custom mandatory fields from the configuration and checks
260 that they have a value set before transitioning to the requested status.
261
262 Accepts a paramhash of values: ARGSRef => Reference to Mason ARGS Ticket
263 => ticket object being updated Queue => Queue object for the queue in
264 which a new ticket is being created From => Ticket status transitioning
265 from To => Ticket status transitioning to
266
267 Works for both create, where no ticket exists yet, and update on an
268 existing ticket. ARGSRef is required for both.
269
270 For create, you must also pass Queue, From, and To.
271
272 Update requires only Ticket and To since From can be fetched from the
273 ticket object.
274
275 Config
276 Takes a queue name. Returns a hashref for the given queue (possibly
277 using the fallback rules) which contains keys of transitions and values
278 of arrayrefs of fields.
279
280 You shouldn't need to use this directly.
281
282TODO
283 Enforcement on Create
284 index.html / QuickCreate - Not yet implemented.
285 SelfService - Not yet implemented.
286
287 Enforcement on other update pages
288 SelfService - can't do it without patches to <form> POST + additional callbacks
289
290 Full Validation of Configuration
291 Check that all CFs are actually CFs applied to the indicated queues (or global). Also
292 validate additional CF's with "must" configuration are defined in a transition.
293
294 Allow empty values in "must" configuration
295 When defining a list of "must be" or "must not be" values, there may be use cases where
296 an empty value could be valid. Provide a way to specify and allow this.
297
298AUTHOR
299 Best Practical Solutions, LLC <modules@bestpractical.com>
300
301BUGS
302 All bugs should be reported via email to
303
304 L<bug-RT-Extension-MandatoryOnTransition@rt.cpan.org|mailto:bug-RT-Extension-MandatoryOnTransition@rt.cpan.org>
305
306 or via the web at
307
308 L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-MandatoryOnTransition>.
309
310LICENSE AND COPYRIGHT
311 This software is Copyright (c) 2012-2020 by Best Pracical Solutions,
312 LLC.
313
314 This is free software, licensed under:
315
316 The GNU General Public License, Version 2, June 1991
317
318