13a4b7d7d5946381eb625150d1eb462c257001bc
[usit-rt.git] / lib / RT / Scrips.pm
1 # BEGIN BPS TAGGED BLOCK {{{
2 #
3 # COPYRIGHT:
4 #
5 # This software is Copyright (c) 1996-2012 Best Practical Solutions, LLC
6 #                                          <sales@bestpractical.com>
7 #
8 # (Except where explicitly superseded by other copyright notices)
9 #
10 #
11 # LICENSE:
12 #
13 # This work is made available to you under the terms of Version 2 of
14 # the GNU General Public License. A copy of that license should have
15 # been provided with this software, but in any event can be snarfed
16 # from www.gnu.org.
17 #
18 # This work is distributed in the hope that it will be useful, but
19 # WITHOUT ANY WARRANTY; without even the implied warranty of
20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 # General Public License for more details.
22 #
23 # You should have received a copy of the GNU General Public License
24 # along with this program; if not, write to the Free Software
25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26 # 02110-1301 or visit their web page on the internet at
27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
28 #
29 #
30 # CONTRIBUTION SUBMISSION POLICY:
31 #
32 # (The following paragraph is not intended to limit the rights granted
33 # to you to modify and distribute this software under the terms of
34 # the GNU General Public License and is only of importance to you if
35 # you choose to contribute your changes and enhancements to the
36 # community by submitting them to Best Practical Solutions, LLC.)
37 #
38 # By intentionally submitting any modifications, corrections or
39 # derivatives to this work, or any other work intended for use with
40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
41 # you are the copyright holder for those contributions and you grant
42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
43 # royalty-free, perpetual, license to use, copy, create derivative
44 # works based on those contributions, and sublicense and distribute
45 # those contributions and any derivatives thereof.
46 #
47 # END BPS TAGGED BLOCK }}}
48
49 =head1 NAME
50
51   RT::Scrips - a collection of RT Scrip objects
52
53 =head1 SYNOPSIS
54
55   use RT::Scrips;
56
57 =head1 DESCRIPTION
58
59
60 =head1 METHODS
61
62
63
64 =cut
65
66
67 package RT::Scrips;
68
69 use strict;
70 use warnings;
71
72 use RT::Scrip;
73
74 use base 'RT::SearchBuilder';
75
76 sub Table { 'Scrips'}
77
78
79 =head2 LimitToQueue
80
81 Takes a queue id (numerical) as its only argument. Makes sure that 
82 Scopes it pulls out apply to this queue (or another that you've selected with
83 another call to this method
84
85 =cut
86
87 sub LimitToQueue  {
88    my $self = shift;
89   my $queue = shift;
90  
91   $self->Limit (ENTRYAGGREGATOR => 'OR',
92                 FIELD => 'Queue',
93                 VALUE => "$queue")
94       if defined $queue;
95   
96 }
97
98
99 =head2 LimitToGlobal
100
101 Makes sure that 
102 Scopes it pulls out apply to all queues (or another that you've selected with
103 another call to this method or LimitToQueue
104
105 =cut
106
107
108 sub LimitToGlobal  {
109    my $self = shift;
110  
111   $self->Limit (ENTRYAGGREGATOR => 'OR',
112                 FIELD => 'Queue',
113                 VALUE => 0);
114   
115 }
116
117 # {{{ sub Next 
118
119 =head2 Next
120
121 Returns the next scrip that this user can see.
122
123 =cut
124   
125 sub Next {
126     my $self = shift;
127     
128     
129     my $Scrip = $self->SUPER::Next();
130     if ((defined($Scrip)) and (ref($Scrip))) {
131
132         if ($Scrip->CurrentUserHasRight('ShowScrips')) {
133             return($Scrip);
134         }
135         
136         #If the user doesn't have the right to show this scrip
137         else {  
138             return($self->Next());
139         }
140     }
141     #if there never was any scrip
142     else {
143         return(undef);
144     }   
145     
146 }
147
148 =head2 Apply
149
150 Run through the relevant scrips.  Scrips will run in order based on 
151 description.  (Most common use case is to prepend a number to the description,
152 forcing the scrips to run in ascending alphanumerical order.)
153
154 =cut
155
156 sub Apply {
157     my $self = shift;
158
159     my %args = ( TicketObj      => undef,
160                  Ticket         => undef,
161                  Transaction    => undef,
162                  TransactionObj => undef,
163                  Stage          => undef,
164                  Type           => undef,
165                  @_ );
166
167     $self->Prepare(%args);
168     $self->Commit();
169
170 }
171
172 =head2 Commit
173
174 Commit all of this object's prepared scrips
175
176 =cut
177
178 sub Commit {
179     my $self = shift;
180
181     # RT::Scrips->_SetupSourceObjects will clobber
182     # the CurrentUser, but we need to keep this ticket
183     # so that the _TransactionBatch cache is maintained
184     # and doesn't run twice.  sigh.
185     $self->_StashCurrentUser( TicketObj => $self->{TicketObj} ) if $self->{TicketObj};
186
187     #We're really going to need a non-acled ticket for the scrips to work
188     $self->_SetupSourceObjects( TicketObj      => $self->{'TicketObj'},
189                                 TransactionObj => $self->{'TransactionObj'} );
190     
191     foreach my $scrip (@{$self->Prepared}) {
192         $RT::Logger->debug(
193             "Committing scrip #". $scrip->id
194             ." on txn #". $self->{'TransactionObj'}->id
195             ." of ticket #". $self->{'TicketObj'}->id
196         );
197
198         $scrip->Commit( TicketObj      => $self->{'TicketObj'},
199                         TransactionObj => $self->{'TransactionObj'} );
200     }
201
202     # Apply the bandaid.
203     $self->_RestoreCurrentUser( TicketObj => $self->{TicketObj} ) if $self->{TicketObj};
204 }
205
206
207 =head2 Prepare
208
209 Only prepare the scrips, returning an array of the scrips we're interested in
210 in order of preparation, not execution
211
212 =cut
213
214 sub Prepare { 
215     my $self = shift;
216     my %args = ( TicketObj      => undef,
217                  Ticket         => undef,
218                  Transaction    => undef,
219                  TransactionObj => undef,
220                  Stage          => undef,
221                  Type           => undef,
222                  @_ );
223
224     # RT::Scrips->_SetupSourceObjects will clobber
225     # the CurrentUser, but we need to keep this ticket
226     # so that the _TransactionBatch cache is maintained
227     # and doesn't run twice.  sigh.
228     $self->_StashCurrentUser( TicketObj => $args{TicketObj} ) if $args{TicketObj};
229
230     #We're really going to need a non-acled ticket for the scrips to work
231     $self->_SetupSourceObjects( TicketObj      => $args{'TicketObj'},
232                                 Ticket         => $args{'Ticket'},
233                                 TransactionObj => $args{'TransactionObj'},
234                                 Transaction    => $args{'Transaction'} );
235
236
237     $self->_FindScrips( Stage => $args{'Stage'}, Type => $args{'Type'} );
238
239
240     #Iterate through each script and check it's applicability.
241     while ( my $scrip = $self->Next() ) {
242
243           unless ( $scrip->IsApplicable(
244                                      TicketObj      => $self->{'TicketObj'},
245                                      TransactionObj => $self->{'TransactionObj'}
246                    ) ) {
247                    $RT::Logger->debug("Skipping Scrip #".$scrip->Id." because it isn't applicable");
248                    next;
249                }
250
251         #If it's applicable, prepare and commit it
252           unless ( $scrip->Prepare( TicketObj      => $self->{'TicketObj'},
253                                     TransactionObj => $self->{'TransactionObj'}
254                    ) ) {
255                    $RT::Logger->debug("Skipping Scrip #".$scrip->Id." because it didn't Prepare");
256                    next;
257                }
258         push @{$self->{'prepared_scrips'}}, $scrip;
259
260     }
261
262     # Apply the bandaid.
263     $self->_RestoreCurrentUser( TicketObj => $args{TicketObj} ) if $args{TicketObj};
264
265
266     return (@{$self->Prepared});
267
268 };
269
270 =head2 Prepared
271
272 Returns an arrayref of the scrips this object has prepared
273
274
275 =cut
276
277 sub Prepared {
278     my $self = shift;
279     return ($self->{'prepared_scrips'} || []);
280 }
281
282 =head2 _StashCurrentUser TicketObj => RT::Ticket
283
284 Saves aside the current user of the original ticket that was passed to these scrips.
285 This is used to make sure that we don't accidentally leak the RT_System current user
286 back to the calling code.
287
288 =cut
289
290 sub _StashCurrentUser {
291     my $self = shift;
292     my %args = @_;
293
294     $self->{_TicketCurrentUser} = $args{TicketObj}->CurrentUser;
295 }
296
297 =head2 _RestoreCurrentUser TicketObj => RT::Ticket
298
299 Uses the current user saved by _StashCurrentUser to reset a Ticket object
300 back to the caller's current user and avoid leaking an RT_System ticket to
301 calling code.
302
303 =cut
304
305 sub _RestoreCurrentUser {
306     my $self = shift;
307     my %args = @_;
308     unless ( $self->{_TicketCurrentUser} ) {
309         RT->Logger->debug("Called _RestoreCurrentUser without a stashed current user object");
310         return;
311     }
312     $args{TicketObj}->CurrentUser($self->{_TicketCurrentUser});
313
314 }
315
316 =head2  _SetupSourceObjects { TicketObj , Ticket, Transaction, TransactionObj }
317
318 Setup a ticket and transaction for this Scrip collection to work with as it runs through the 
319 relevant scrips.  (Also to figure out which scrips apply)
320
321 Returns: nothing
322
323 =cut
324
325
326 sub _SetupSourceObjects {
327
328     my $self = shift;
329     my %args = ( 
330             TicketObj => undef,
331             Ticket => undef,
332             Transaction => undef,
333             TransactionObj => undef,
334             @_ );
335
336
337     if ( $self->{'TicketObj'} = $args{'TicketObj'} ) {
338         # This clobbers the passed in TicketObj by turning it into one
339         # whose current user is RT_System.  Anywhere in the Web UI
340         # currently calling into this is thus susceptable to a privilege
341         # leak; the only current call site is ->Apply, which bandaids
342         # over the top of this by re-asserting the CurrentUser
343         # afterwards.
344         $self->{'TicketObj'}->CurrentUser( $self->CurrentUser );
345     }
346     else {
347         $self->{'TicketObj'} = RT::Ticket->new( $self->CurrentUser );
348         $self->{'TicketObj'}->Load( $args{'Ticket'} )
349           || $RT::Logger->err("$self couldn't load ticket $args{'Ticket'}");
350     }
351
352     if ( ( $self->{'TransactionObj'} = $args{'TransactionObj'} ) ) {
353         $self->{'TransactionObj'}->CurrentUser( $self->CurrentUser );
354     }
355     else {
356         $self->{'TransactionObj'} = RT::Transaction->new( $self->CurrentUser );
357         $self->{'TransactionObj'}->Load( $args{'Transaction'} )
358           || $RT::Logger->err( "$self couldn't load transaction $args{'Transaction'}");
359     }
360
361
362
363
364 =head2 _FindScrips
365
366 Find only the apropriate scrips for whatever we're doing now.  Order them 
367 by their description.  (Most common use case is to prepend a number to the
368 description, forcing the scrips to display and run in ascending alphanumerical 
369 order.)
370
371 =cut
372
373 sub _FindScrips {
374     my $self = shift;
375     my %args = (
376                  Stage => undef,
377                  Type => undef,
378                  @_ );
379
380
381     $self->LimitToQueue( $self->{'TicketObj'}->QueueObj->Id )
382       ;    #Limit it to  $Ticket->QueueObj->Id
383     $self->LimitToGlobal();
384       # or to "global"
385
386     $self->Limit( FIELD => "Stage", VALUE => $args{'Stage'} );
387
388     my $ConditionsAlias = $self->NewAlias('ScripConditions');
389
390     $self->Join(
391         ALIAS1 => 'main',
392         FIELD1 => 'ScripCondition',
393         ALIAS2 => $ConditionsAlias,
394         FIELD2 => 'id'
395     );
396
397     #We only want things where the scrip applies to this sort of transaction
398     # TransactionBatch stage can define list of transaction
399     foreach( split /\s*,\s*/, ($args{'Type'} || '') ) {
400         $self->Limit(
401             ALIAS           => $ConditionsAlias,
402             FIELD           => 'ApplicableTransTypes',
403             OPERATOR        => 'LIKE',
404             VALUE           => $_,
405             ENTRYAGGREGATOR => 'OR',
406         )
407     }
408
409     # Or where the scrip applies to any transaction
410     $self->Limit(
411         ALIAS           => $ConditionsAlias,
412         FIELD           => 'ApplicableTransTypes',
413         OPERATOR        => 'LIKE',
414         VALUE           => "Any",
415         ENTRYAGGREGATOR => 'OR',
416     );
417
418     # Promise some kind of ordering
419     $self->OrderBy( FIELD => 'Description' );
420
421     # we call Count below, but later we always do search
422     # so just do search and get count from results
423     $self->_DoSearch if $self->{'must_redo_search'};
424
425     $RT::Logger->debug(
426         "Found ". $self->Count ." scrips for $args{'Stage'} stage"
427         ." with applicable type(s) $args{'Type'}"
428         ." for txn #".$self->{TransactionObj}->Id
429         ." on ticket #".$self->{TicketObj}->Id
430     );
431 }
432
433
434
435
436 =head2 NewItem
437
438 Returns an empty new RT::Scrip item
439
440 =cut
441
442 sub NewItem {
443     my $self = shift;
444     return(RT::Scrip->new($self->CurrentUser));
445 }
446 RT::Base->_ImportOverlays();
447
448 1;