update POD documentation left behind from example template
[freeside.git] / FS / FS / part_bill_event.pm
1 package FS::part_bill_event;
2
3 use strict;
4 use vars qw( @ISA );
5 use FS::Record qw( qsearch qsearchs );
6 use FS::Conf;
7
8 @ISA = qw(FS::Record);
9
10 =head1 NAME
11
12 FS::part_bill_event - Object methods for part_bill_event records
13
14 =head1 SYNOPSIS
15
16   use FS::part_bill_event;
17
18   $record = new FS::part_bill_event \%hash;
19   $record = new FS::part_bill_event { 'column' => 'value' };
20
21   $error = $record->insert;
22
23   $error = $new_record->replace($old_record);
24
25   $error = $record->delete;
26
27   $error = $record->check;
28
29 =head1 DESCRIPTION
30
31 An FS::part_bill_event object represents an invoice event definition -
32 a callback which is triggered when an invoice is a certain amount of time
33 overdue.  FS::part_bill_event inherits from
34 FS::Record.  The following fields are currently supported:
35
36 =over 4
37
38 =item eventpart - primary key
39
40 =item payby - CARD, DCRD, CHEK, DCHK, LECB, BILL, or COMP
41
42 =item event - event name
43
44 =item eventcode - event action
45
46 =item seconds - how long after the invoice date events of this type are triggered
47
48 =item weight - ordering for events with identical seconds
49
50 =item plan - eventcode plan
51
52 =item plandata - additional plan data
53
54 =item disabled - Disabled flag, empty or `Y'
55
56 =back
57
58 =head1 METHODS
59
60 =over 4
61
62 =item new HASHREF
63
64 Creates a new invoice event definition.  To add the invoice event definition to
65 the database, see L<"insert">.
66
67 Note that this stores the hash reference, not a distinct copy of the hash it
68 points to.  You can ask the object for a copy with the I<hash> method.
69
70 =cut
71
72 # the new method can be inherited from FS::Record, if a table method is defined
73
74 sub table { 'part_bill_event'; }
75
76 =item insert
77
78 Adds this record to the database.  If there is an error, returns the error,
79 otherwise returns false.
80
81 =cut
82
83 # the insert method can be inherited from FS::Record
84
85 =item delete
86
87 Delete this record from the database.
88
89 =cut
90
91 # the delete method can be inherited from FS::Record
92
93 =item replace OLD_RECORD
94
95 Replaces the OLD_RECORD with this one in the database.  If there is an error,
96 returns the error, otherwise returns false.
97
98 =cut
99
100 # the replace method can be inherited from FS::Record
101
102 =item check
103
104 Checks all fields to make sure this is a valid invoice event definition.  If
105 there is an error, returns the error, otherwise returns false.  Called by the
106 insert and replace methods.
107
108 =cut
109
110 # the check method should currently be supplied - FS::Record contains some
111 # data checking routines
112
113 sub check {
114   my $self = shift;
115
116   $self->weight(0) unless $self->weight;
117
118   my $conf = new FS::Conf;
119   if ( $conf->exists('safe-part_bill_event') ) {
120     my $error = $self->ut_anything('eventcode');
121     return $error if $error;
122
123     my $c = $self->eventcode;
124
125     $c =~ /^\s*\$cust_main\->(suspend|cancel|invoicing_list_addpost|bill|collect)\(\);\s*("";)?\s*$/
126
127       or $c =~ /^\s*\$cust_bill\->(comp|realtime_(card|ach|lec)|batch_card|send)\(\);\s*$/
128
129       or $c =~ /^\s*\$cust_bill\->send(_if_newest)?\(\'[\w\-\s]+\'\s*(,\s*(\d+|\[\s*\d+(,\s*\d+)*\s*\])\s*,\s*'[\w\@\.\-\+]*'\s*)?\);\s*$/
130
131       or $c =~ /^\s*\$cust_main\->apply_payments; \$cust_main->apply_credits; "";\s*$/
132
133       or $c =~ /^\s*\$cust_main\->charge\( \s*\d*\.?\d*\s*,\s*\'[\w \!\@\#\$\%\&\(\)\-\+\;\:\"\,\.\?\/]*\'\s*\);\s*$/
134
135       or $c =~ /^\s*\$cust_main\->suspend_(if|unless)_pkgpart\([\d\,\s]*\);\s*$/
136
137       or $c =~ /^\s*\$cust_bill\->cust_suspend_if_balance_over\([\d\.\s]*\);\s*$/
138
139       or do {
140         #log
141         return "illegal eventcode: $c";
142       };
143
144   }
145
146   my $error = $self->ut_numbern('eventpart')
147     || $self->ut_enum('payby', [qw( CARD DCRD CHEK DCHK LECB BILL COMP )] )
148     || $self->ut_text('event')
149     || $self->ut_anything('eventcode')
150     || $self->ut_number('seconds')
151     || $self->ut_enum('disabled', [ '', 'Y' ] )
152     || $self->ut_number('weight')
153     || $self->ut_textn('plan')
154     || $self->ut_anything('plandata')
155   ;
156     #|| $self->ut_snumber('seconds')
157   return $error if $error;
158
159   #quelle kludge
160   if ( $self->plandata =~ /^(agent_)?templatename\s+(.*)$/m ) {
161     my $name= $2;
162
163     foreach my $file (qw( template
164                           latex latexnotes latexreturnaddress latexfooter
165                             latexsmallfooter
166                           html htmlnotes htmlreturnaddress htmlfooter
167                      ))
168     {
169       unless ( $conf->exists("invoice_${file}_$name") ) {
170         $conf->set(
171           "invoice_${file}_$name" =>
172             join("\n", $conf->config("invoice_$file") )
173         );
174       }
175     }
176   }
177
178   $self->SUPER::check;
179 }
180
181 =item templatename
182
183 Returns the alternate invoice template name, if any, or false if there is
184 no alternate template for this invoice event.
185
186 =cut
187
188 sub templatename {
189   my $self = shift;
190   if (    $self->plan     =~ /^send_(alternate|agent)$/
191        && $self->plandata =~ /^(agent_)?templatename (.*)$/m
192      )
193   {
194     $2;
195   } else {
196     '';
197   }
198 }
199
200
201 =back
202
203 =head1 BUGS
204
205 The whole "eventcode" idea is bunk.  This should be refactored with subclasses
206 like part_pkg/ and part_export/
207
208 =head1 SEE ALSO
209
210 L<FS::cust_bill>, L<FS::cust_bill_event>, L<FS::Record>, schema.html from the
211 base documentation.
212
213 =cut
214
215 1;
216