1 package FS::part_event;
4 use base qw( FS::m2name_Common FS::option_Common );
7 use FS::Record qw( dbh qsearch qsearchs );
10 use FS::part_event_option;
11 use FS::part_event_condition;
18 FS::part_event - Object methods for part_event records
24 $record = new FS::part_event \%hash;
25 $record = new FS::part_event { 'column' => 'value' };
27 $error = $record->insert( { 'option' => 'value' } );
28 $error = $record->insert( \%options );
30 $error = $new_record->replace($old_record);
32 $error = $record->delete;
34 $error = $record->check;
36 $error = $record->do_event( $direct_object );
40 An FS::part_event object represents an event definition - a billing, collection
41 or other callback which is triggered when certain customer, invoice, package or
42 other conditions are met. FS::part_event inherits from FS::Record. The
43 following fields are currently supported:
47 =item eventpart - primary key
49 =item agentnum - Optional agentnum (see L<FS::agent>)
51 =item event - event name
53 =item eventtable - table name against which this event is triggered: one of "cust_main", "cust_bill", "cust_statement", "cust_pkg", "svc_acct".
55 =item check_freq - how often events of this type are checked; currently "1d" (daily) and "1m" (monthly) are recognized. Note that the apprioriate freeside-daily and/or freeside-monthly cron job needs to be in place.
57 =item weight - ordering for events
59 =item action - event action (like part_bill_event.plan - eventcode plan)
61 =item disabled - Disabled flag, empty or `Y'
71 Creates a new invoice event definition. To add the invoice event definition to
72 the database, see L<"insert">.
74 Note that this stores the hash reference, not a distinct copy of the hash it
75 points to. You can ask the object for a copy with the I<hash> method.
79 # the new method can be inherited from FS::Record, if a table method is defined
81 sub table { 'part_event'; }
83 =item insert [ HASHREF ]
85 Adds this record to the database. If there is an error, returns the error,
86 otherwise returns false.
88 If a list or hash reference of options is supplied, part_export_option records
89 are created (see L<FS::part_event_option>).
93 # the insert method can be inherited from FS::Record
97 Delete this record from the database.
101 # the delete method can be inherited from FS::Record
103 =item replace OLD_RECORD [ HASHREF | OPTION => VALUE ... ]
105 Replaces the OLD_RECORD with this one in the database. If there is an error,
106 returns the error, otherwise returns false.
108 If a list or hash reference of options is supplied, part_event_option
109 records are created or modified (see L<FS::part_event_option>).
113 # the replace method can be inherited from FS::Record
117 Checks all fields to make sure this is a valid invoice event definition. If
118 there is an error, returns the error, otherwise returns false. Called by the
119 insert and replace methods.
123 # the check method should currently be supplied - FS::Record contains some
124 # data checking routines
129 $self->weight(0) unless $self->weight;
132 $self->ut_numbern('eventpart')
133 || $self->ut_text('event')
134 || $self->ut_enum('eventtable', [ $self->eventtables ] )
135 || $self->ut_enum('check_freq', [ '1d', '1m' ])
136 || $self->ut_number('weight')
137 || $self->ut_alpha('action')
138 || $self->ut_enum('disabled', [ '', 'Y' ] )
139 || $self->ut_agentnum_acl('agentnum', 'Edit global billing events')
141 return $error if $error;
143 #XXX check action to make sure a module exists?
144 # well it'll die in _rebless...
151 Reblesses the object into the FS::part_event::Action::ACTION class, where
152 ACTION is the object's I<action> field.
158 my $action = $self->action or return $self;
159 #my $class = ref($self). "::$action";
160 my $class = "FS::part_event::Action::$action";
163 bless($self, $class); # unless $@;
167 =item part_event_condition
169 Returns the conditions associated with this event, as FS::part_event_condition
170 objects (see L<FS::part_event_condition>)
172 =item new_cust_event OBJECT, [ OPTION => VALUE ]
174 Creates a new customer event (see L<FS::cust_event>) for the provided object.
176 The only option allowed is 'time', to set the "current" time for the event.
181 my( $self, $object, %opt ) = @_;
183 confess "**** $object is not a ". $self->eventtable
184 if ref($object) ne "FS::". $self->eventtable;
186 my $pkey = $object->primary_key;
189 'eventpart' => $self->eventpart,
190 'tablenum' => $object->$pkey(),
191 #'_date' => time, #i think we always want the real "now" here.
192 '_date' => ($opt{'time'} || time),
197 #surely this doesn't work
198 sub reasontext { confess "part_event->reasontext deprecated"; }
201 #Returns the text of any reason associated with this event.
207 # my $r = qsearchs('reason', { 'reasonnum' => $self->reason });
217 Returns the associated agent for this event, if any, as an FS::agent object.
221 Returns the alternate invoice template name, if any, or false if there is
222 no alternate template for this event.
229 if ( $self->action =~ /^cust_bill_send_(alternate|agent)$/
230 && ( $self->option('agent_templatename')
231 || $self->option('templatename') )
234 $self->option('agent_templatename')
235 || $self->option('templatename');
242 =item targets OPTIONS
244 Returns all objects (of type C<FS::eventtable>, for this object's
245 C<eventtable>) eligible for processing under this event, as of right now.
246 The L<FS::cust_event> object used to test event conditions will be
247 included in each object as the 'cust_event' pseudo-field.
249 This is not used in normal event processing (which is done on a
250 per-customer basis to control timing of pre- and post-billing events)
251 but can be useful when configuring events.
255 sub targets { # may want to cursor this also
258 my $time = $opt{'time'} ||= time;
260 my $query = $self->_target_query(%opt);
261 my @objects = qsearch($query);
263 foreach my $object ( @objects ) {
264 my $cust_event = $self->new_cust_event($object, 'time' => $time);
265 next unless $cust_event->test_conditions;
267 $object->set('cust_event', $cust_event);
268 push @tested_objects, $object;
276 my $time = $opt{'time'};
278 my $eventpart = $self->eventpart;
279 $eventpart =~ /^\d+$/ or die "bad eventpart $eventpart";
280 my $eventtable = $self->eventtable;
282 # find all objects that meet the conditions for this part_event
284 # this is the 'object' side of the FROM clause
285 if ( $eventtable ne 'cust_main' ) {
287 ($self->eventtables_cust_join->{$eventtable} || '') .
288 ' LEFT JOIN cust_main USING (custnum) ';
291 # this is the 'event' side
292 my $join = FS::part_event_condition->join_conditions_sql( $eventtable,
295 my $where = FS::part_event_condition->where_conditions_sql( $eventtable,
299 " INNER JOIN part_event ON ( part_event.eventpart = $eventpart ) $join";
301 $where .= ' AND cust_main.agentnum = '.$self->agentnum
303 # don't enforce check_freq since this is a special, out-of-order check
304 # and don't enforce disabled because we want to be able to see targets
305 # for a disabled event
308 table => $eventtable,
311 extra_sql => "WHERE $where",
316 =item initialize PARAMS
318 Identify all objects eligible for this event and create L<FS::cust_event>
319 records for each of them, as of the present time, with status "initial". When
320 combined with conditions that prevent an event from running more than once
321 (at all or within some period), this will exclude any objects that met the
322 conditions before the event was created.
324 If an L<FS::part_event> object needs to be initialized, it should be created
325 in a disabled state to avoid running the event prematurely for any existing
326 objects. C<initialize> will enable it once all the cust_event records
329 This may take some time, so it should be run from the job queue.
339 local $FS::UID::AutoCommit = 1;
340 my $cursor = FS::Cursor->new( $self->_target_query('time' => $time) );
341 while (my $object = $cursor->fetch) {
343 my $cust_event = $self->new_cust_event($object, 'time' => $time);
344 next unless $cust_event->test_conditions;
346 $cust_event->status('initial');
347 $error = $cust_event->insert;
348 die $error if $error;
351 # on successful completion only, re-enable the event
352 if ( $self->disabled ) {
354 $error = $self->replace;
355 die $error if $error;
369 =item eventtable_labels
371 Returns a hash reference of labels for eventtable values,
372 i.e. 'cust_main'=>'Customer'
376 sub eventtable_labels {
379 tie my %hash, 'Tie::IxHash',
380 'cust_pkg' => 'Package',
381 'cust_bill' => 'Invoice',
382 'cust_main' => 'Customer',
383 'cust_pay' => 'Payment',
384 'cust_pay_batch' => 'Batch payment',
385 'cust_statement' => 'Statement', #too general a name here? "Invoice group"?
386 'svc_acct' => 'Account service (svc_acct)',
392 =item eventtable_pkey_sql
394 Returns a hash reference of full SQL primary key names for eventtable values,
395 i.e. 'cust_main'=>'cust_main.custnum'
399 sub eventtable_pkey_sql {
402 my $hashref = $class->eventtable_pkey;
404 my %hash = map { $_ => "$_.". $hashref->{$_} } keys %$hashref;
409 =item eventtable_pkey
411 Returns a hash reference of full SQL primary key names for eventtable values,
412 i.e. 'cust_main'=>'custnum'
416 sub eventtable_pkey {
420 'cust_main' => 'custnum',
421 'cust_bill' => 'invnum',
422 'cust_pkg' => 'pkgnum',
423 'cust_pay' => 'paynum',
424 'cust_pay_batch' => 'paybatchnum',
425 'cust_statement' => 'statementnum',
426 'svc_acct' => 'svcnum',
432 Returns a list of eventtable values (default ordering; suited for display).
438 my $eventtables = $class->eventtable_labels;
442 =item eventtables_runorder
444 Returns a list of eventtable values (run order).
448 sub eventtables_runorder {
449 shift->eventtables; #same for now
452 =item eventtables_cust_join
454 Returns a hash reference of SQL expressions to join each eventtable to
455 a table with a 'custnum' field.
459 sub eventtables_cust_join {
461 'svc_acct' => 'LEFT JOIN cust_svc USING (svcnum) LEFT JOIN cust_pkg USING (pkgnum)',
466 =item eventtables_custnum
468 Returns a hash reference of SQL expressions for the 'custnum' field when
469 I<eventtables_cust_join> is in effect. The default is "$eventtable.custnum".
473 sub eventtables_custnum {
475 map({ $_, "$_.custnum" } shift->eventtables),
476 'svc_acct' => 'cust_pkg.custnum'
482 =item check_freq_labels
484 Returns a hash reference of labels for check_freq values,
489 sub check_freq_labels {
499 =item actions [ EVENTTABLE ]
501 Return information about the available actions. If an eventtable is specified,
502 only return information about actions available for that eventtable.
504 Information is returned as key-value pairs. Keys are event names. Values are
505 hashrefs with the following keys:
511 =item eventtable_hashref
521 =head1 ADDING NEW EVENTTABLES
523 To add an eventtable, you must:
527 =item Add the table to "eventtable_labels" (with a label) and to
528 "eventtable_pkey" (with its primary key).
530 =item If the table doesn't have a "custnum" field of its own (such
531 as a svc_x table), add a suitable join expression to
532 eventtables_cust_join and an expression for the final custnum field
533 to eventtables_custnum.
535 =item Create a method named FS::cust_main->$eventtable(): a wrapper
536 around qsearch() to return all records in the new table belonging to
537 the cust_main object. This method must accept 'addl_from' and
538 'extra_sql' arguments in the way qsearch() does. For svc_ tables,
539 wrap the svc_x() method.
541 =item Add it to FS::cust_event->join_sql and search_sql_where so that
542 search/cust_event.html will find it.
544 =item Create a UI link/form to search for events linked to objects
545 in the new eventtable, using search/cust_event.html. Place this
546 somewhere appropriate to the eventtable.
550 See L<FS::part_event::Action> for more information.
554 #false laziness w/part_event_condition.pm
555 #some false laziness w/part_export & part_pkg
557 foreach my $INC ( @INC ) {
558 foreach my $file ( glob("$INC/FS/part_event/Action/*.pm") ) {
559 warn "attempting to load Action from $file\n" if $DEBUG;
560 $file =~ /\/(\w+)\.pm$/ or do {
561 warn "unrecognized file in $INC/FS/part_event/Action/: $file\n";
565 eval "use FS::part_event::Action::$mod;";
567 die "error using FS::part_event::Action::$mod (skipping): $@\n" if $@;
568 #warn "error using FS::part_event::Action::$mod (skipping): $@\n" if $@;
572 ( map { $_ => "FS::part_event::Action::$mod"->$_() }
573 qw( description eventtable_hashref default_weight deprecated )
574 #option_fields_hashref
576 'option_fields' => [ "FS::part_event::Action::$mod"->option_fields() ],
582 my( $class, $eventtable ) = @_;
584 map { $_ => $actions{$_} }
585 sort { $actions{$a}->{'default_weight'}<=>$actions{$b}->{'default_weight'} }
586 # || $actions{$a}->{'description'} cmp $actions{$b}->{'description'} }
587 $class->all_actions( $eventtable )
592 =item all_actions [ EVENTTABLE ]
594 Returns a list of just the action names
599 my ( $class, $eventtable ) = @_;
601 grep { !$eventtable || $actions{$_}->{'eventtable_hashref'}{$eventtable} }
605 =item process_initialize 'eventpart' => EVENTPART
607 Job queue wrapper for "initialize". EVENTPART identifies the
608 L<FS::part_event> object to initialize.
612 sub process_initialize {
615 qsearchs('part_event', { eventpart => $opt{'eventpart'}})
616 or die "eventpart '$opt{eventpart}' not found!\n";
617 $part_event->initialize;
620 sub _upgrade_data { #class method
621 my ($class, %opts) = @_;
623 foreach my $part_event (
624 qsearch('part_event', { 'action' => 'cust_bill_realtime_card' }),
625 qsearch('part_event', { 'action' => 'cust_bill_realtime_check' }),
628 $part_event->action('realtime_auto');
629 my $error = $part_event->replace;
630 die $error if $error;
640 L<FS::part_event_option>, L<FS::part_event_condition>, L<FS::cust_main>,
641 L<FS::cust_pkg>, L<FS::svc_acct>, L<FS::cust_bill>, L<FS::cust_bill_event>,
643 schema.html from the base documentation.