Upgrade to 4.0.8 with mod of ExternalAuth + absolute paths to ticket-menu.
[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     foreach my $scrip (@{$self->Prepared}) {
182         $RT::Logger->debug(
183             "Committing scrip #". $scrip->id
184             ." on txn #". $self->{'TransactionObj'}->id
185             ." of ticket #". $self->{'TicketObj'}->id
186         );
187
188         $scrip->Commit( TicketObj      => $self->{'TicketObj'},
189                         TransactionObj => $self->{'TransactionObj'} );
190     }
191
192 }
193
194
195 =head2 Prepare
196
197 Only prepare the scrips, returning an array of the scrips we're interested in
198 in order of preparation, not execution
199
200 =cut
201
202 sub Prepare { 
203     my $self = shift;
204     my %args = ( TicketObj      => undef,
205                  Ticket         => undef,
206                  Transaction    => undef,
207                  TransactionObj => undef,
208                  Stage          => undef,
209                  Type           => undef,
210                  @_ );
211
212     #We're really going to need a non-acled ticket for the scrips to work
213     $self->_SetupSourceObjects( TicketObj      => $args{'TicketObj'},
214                                 Ticket         => $args{'Ticket'},
215                                 TransactionObj => $args{'TransactionObj'},
216                                 Transaction    => $args{'Transaction'} );
217
218
219     $self->_FindScrips( Stage => $args{'Stage'}, Type => $args{'Type'} );
220
221
222     #Iterate through each script and check it's applicability.
223     while ( my $scrip = $self->Next() ) {
224
225           unless ( $scrip->IsApplicable(
226                                      TicketObj      => $self->{'TicketObj'},
227                                      TransactionObj => $self->{'TransactionObj'}
228                    ) ) {
229                    $RT::Logger->debug("Skipping Scrip #".$scrip->Id." because it isn't applicable");
230                    next;
231                }
232
233         #If it's applicable, prepare and commit it
234           unless ( $scrip->Prepare( TicketObj      => $self->{'TicketObj'},
235                                     TransactionObj => $self->{'TransactionObj'}
236                    ) ) {
237                    $RT::Logger->debug("Skipping Scrip #".$scrip->Id." because it didn't Prepare");
238                    next;
239                }
240         push @{$self->{'prepared_scrips'}}, $scrip;
241
242     }
243
244     return (@{$self->Prepared});
245
246 };
247
248 =head2 Prepared
249
250 Returns an arrayref of the scrips this object has prepared
251
252
253 =cut
254
255 sub Prepared {
256     my $self = shift;
257     return ($self->{'prepared_scrips'} || []);
258 }
259
260 =head2  _SetupSourceObjects { TicketObj , Ticket, Transaction, TransactionObj }
261
262 Setup a ticket and transaction for this Scrip collection to work with as it runs through the 
263 relevant scrips.  (Also to figure out which scrips apply)
264
265 Returns: nothing
266
267 =cut
268
269
270 sub _SetupSourceObjects {
271
272     my $self = shift;
273     my %args = ( 
274             TicketObj => undef,
275             Ticket => undef,
276             Transaction => undef,
277             TransactionObj => undef,
278             @_ );
279
280
281     if ( $args{'TicketObj'} ) {
282         # This loads a clean copy of the Ticket object to ensure that we
283         # don't accidentally escalate the privileges of the passed in
284         # ticket (this function can be invoked from the UI).
285         # We copy the TransactionBatch transactions so that Scrips
286         # running against the new Ticket will have access to them. We
287         # use RanTransactionBatch to guard against running
288         # TransactionBatch Scrips more than once.
289         $self->{'TicketObj'} = RT::Ticket->new( $self->CurrentUser );
290         $self->{'TicketObj'}->Load( $args{'TicketObj'}->Id );
291         if ( $args{'TicketObj'}->TransactionBatch ) {
292             # try to ensure that we won't infinite loop if something dies, triggering DESTROY while 
293             # we have the _TransactionBatch objects;
294             $self->{'TicketObj'}->RanTransactionBatch(1);
295             $self->{'TicketObj'}->{'_TransactionBatch'} = $args{'TicketObj'}->{'_TransactionBatch'};
296         }
297     }
298     else {
299         $self->{'TicketObj'} = RT::Ticket->new( $self->CurrentUser );
300         $self->{'TicketObj'}->Load( $args{'Ticket'} )
301           || $RT::Logger->err("$self couldn't load ticket $args{'Ticket'}");
302     }
303
304     if ( ( $self->{'TransactionObj'} = $args{'TransactionObj'} ) ) {
305         $self->{'TransactionObj'}->CurrentUser( $self->CurrentUser );
306     }
307     else {
308         $self->{'TransactionObj'} = RT::Transaction->new( $self->CurrentUser );
309         $self->{'TransactionObj'}->Load( $args{'Transaction'} )
310           || $RT::Logger->err( "$self couldn't load transaction $args{'Transaction'}");
311     }
312
313
314
315
316 =head2 _FindScrips
317
318 Find only the apropriate scrips for whatever we're doing now.  Order them 
319 by their description.  (Most common use case is to prepend a number to the
320 description, forcing the scrips to display and run in ascending alphanumerical 
321 order.)
322
323 =cut
324
325 sub _FindScrips {
326     my $self = shift;
327     my %args = (
328                  Stage => undef,
329                  Type => undef,
330                  @_ );
331
332
333     $self->LimitToQueue( $self->{'TicketObj'}->QueueObj->Id )
334       ;    #Limit it to  $Ticket->QueueObj->Id
335     $self->LimitToGlobal();
336       # or to "global"
337
338     $self->Limit( FIELD => "Stage", VALUE => $args{'Stage'} );
339
340     my $ConditionsAlias = $self->NewAlias('ScripConditions');
341
342     $self->Join(
343         ALIAS1 => 'main',
344         FIELD1 => 'ScripCondition',
345         ALIAS2 => $ConditionsAlias,
346         FIELD2 => 'id'
347     );
348
349     #We only want things where the scrip applies to this sort of transaction
350     # TransactionBatch stage can define list of transaction
351     foreach( split /\s*,\s*/, ($args{'Type'} || '') ) {
352         $self->Limit(
353             ALIAS           => $ConditionsAlias,
354             FIELD           => 'ApplicableTransTypes',
355             OPERATOR        => 'LIKE',
356             VALUE           => $_,
357             ENTRYAGGREGATOR => 'OR',
358         )
359     }
360
361     # Or where the scrip applies to any transaction
362     $self->Limit(
363         ALIAS           => $ConditionsAlias,
364         FIELD           => 'ApplicableTransTypes',
365         OPERATOR        => 'LIKE',
366         VALUE           => "Any",
367         ENTRYAGGREGATOR => 'OR',
368     );
369
370     # Promise some kind of ordering
371     $self->OrderBy( FIELD => 'Description' );
372
373     # we call Count below, but later we always do search
374     # so just do search and get count from results
375     $self->_DoSearch if $self->{'must_redo_search'};
376
377     $RT::Logger->debug(
378         "Found ". $self->Count ." scrips for $args{'Stage'} stage"
379         ." with applicable type(s) $args{'Type'}"
380         ." for txn #".$self->{TransactionObj}->Id
381         ." on ticket #".$self->{TicketObj}->Id
382     );
383 }
384
385
386
387
388 =head2 NewItem
389
390 Returns an empty new RT::Scrip item
391
392 =cut
393
394 sub NewItem {
395     my $self = shift;
396     return(RT::Scrip->new($self->CurrentUser));
397 }
398 RT::Base->_ImportOverlays();
399
400 1;