FS/FS/cust_bill_void.pm

   1 package FS::cust_bill_void;
   2 use base qw( FS::Template_Mixin FS::cust_main_Mixin FS::otaker_Mixin
   3              FS::reason_Mixin FS::Record );
   4
   5 use strict;
   6 use vars qw( $me $DEBUG );
   7 use FS::Record qw( qsearch qsearchs dbh fields );
   8 use FS::cust_statement;
   9 use FS::access_user;
  10 use FS::cust_bill_pkg_void;
  11 use FS::cust_bill;
  12
  13 $me = '[ FS::cust_bill_void ]';
  14 $DEBUG = 0;
  15
  16 =head1 NAME
  17
  18 FS::cust_bill_void - Object methods for cust_bill_void records
  19
  20 =head1 SYNOPSIS
  21
  22   use FS::cust_bill_void;
  23
  24   $record = new FS::cust_bill_void \%hash;
  25   $record = new FS::cust_bill_void { 'column' => 'value' };
  26
  27   $error = $record->insert;
  28
  29   $error = $new_record->replace($old_record);
  30
  31   $error = $record->delete;
  32
  33   $error = $record->check;
  34
  35 =head1 DESCRIPTION
  36
  37 An FS::cust_bill_void object represents a voided invoice.  FS::cust_bill_void
  38 inherits from FS::Record.  The following fields are currently supported:
  39
  40 =over 4
  41
  42 =item invnum
  43
  44 primary key
  45
  46 =item custnum
  47
  48 custnum
  49
  50 =item _date
  51
  52 _date
  53
  54 =item charged
  55
  56 charged
  57
  58 =item invoice_terms
  59
  60 invoice_terms
  61
  62 =item previous_balance
  63
  64 previous_balance
  65
  66 =item billing_balance
  67
  68 billing_balance
  69
  70 =item closed
  71
  72 closed
  73
  74 =item statementnum
  75
  76 statementnum
  77
  78 =item agent_invid
  79
  80 agent_invid
  81
  82 =item promised_date
  83
  84 promised_date
  85
  86 =item void_date
  87
  88 void_date
  89
  90 =item reason
  91
  92 freeform string (deprecated)
  93
  94 =item reasonnum
  95
  96 reason for voiding the payment (see L<FS::reson>)
  97
  98 =item void_usernum
  99
 100 void_usernum
 101
 102
 103 =back
 104
 105 =head1 METHODS
 106
 107 =over 4
 108
 109 =item new HASHREF
 110
 111 Creates a new voided invoice.  To add the voided invoice to the database, see L<"insert">.
 112
 113 Note that this stores the hash reference, not a distinct copy of the hash it
 114 points to.  You can ask the object for a copy with the I<hash> method.
 115
 116 =cut
 117
 118 sub table { 'cust_bill_void'; }
 119 sub notice_name { 'VOIDED Invoice'; }
 120 sub template_conf { 'invoice_'; }
 121
 122 =item insert
 123
 124 Adds this record to the database.  If there is an error, returns the error,
 125 otherwise returns false.
 126
 127 =cut
 128
 129 =item unvoid
 130
 131 "Un-void"s this invoice: Deletes the voided invoice from the database and adds
 132 back a normal invoice (and related tables).
 133
 134 =cut
 135
 136 sub unvoid {
 137   my $self = shift;
 138
 139   local $SIG{HUP} = 'IGNORE';
 140   local $SIG{INT} = 'IGNORE';
 141   local $SIG{QUIT} = 'IGNORE';
 142   local $SIG{TERM} = 'IGNORE';
 143   local $SIG{TSTP} = 'IGNORE';
 144   local $SIG{PIPE} = 'IGNORE';
 145
 146   my $oldAutoCommit = $FS::UID::AutoCommit;
 147   local $FS::UID::AutoCommit = 0;
 148   my $dbh = dbh;
 149
 150   my $cust_bill = new FS::cust_bill ( {
 151     map { $_ => $self->get($_) } fields('cust_bill')
 152   } );
 153   my $error = $cust_bill->insert;
 154   if ( $error ) {
 155     $dbh->rollback if $oldAutoCommit;
 156     return $error;
 157   }
 158
 159   foreach my $cust_bill_pkg_void ( $self->cust_bill_pkg ) {
 160     my $error = $cust_bill_pkg_void->unvoid;
 161     if ( $error ) {
 162       $dbh->rollback if $oldAutoCommit;
 163       return $error;
 164     }
 165   }
 166
 167   $error = $self->delete;
 168   if ( $error ) {
 169     $dbh->rollback if $oldAutoCommit;
 170     return $error;
 171   }
 172
 173   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 174
 175   '';
 176
 177 }
 178
 179 =item delete
 180
 181 Delete this record from the database.
 182
 183 =cut
 184
 185 =item replace OLD_RECORD
 186
 187 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 188 returns the error, otherwise returns false.
 189
 190 =cut
 191
 192 =item check
 193
 194 Checks all fields to make sure this is a valid voided invoice.  If there is
 195 an error, returns the error, otherwise returns false.  Called by the insert
 196 and replace methods.
 197
 198 =cut
 199
 200 sub check {
 201   my $self = shift;
 202
 203   my $error =
 204     $self->ut_number('invnum')
 205     || $self->ut_foreign_key('custnum', 'cust_main', 'custnum' )
 206     || $self->ut_numbern('_date')
 207     || $self->ut_money('charged')
 208     || $self->ut_textn('invoice_terms')
 209     || $self->ut_moneyn('previous_balance')
 210     || $self->ut_moneyn('billing_balance')
 211     || $self->ut_enum('closed', [ '', 'Y' ])
 212     || $self->ut_foreign_keyn('statementnum', 'cust_statement', 'statementnum')
 213     || $self->ut_numbern('agent_invid')
 214     || $self->ut_numbern('promised_date')
 215     || $self->ut_numbern('void_date')
 216     || $self->ut_textn('reason')
 217     || $self->ut_numbern('void_usernum')
 218     || $self->ut_foreign_keyn('reasonnum', 'reason', 'reasonnum')
 219   ;
 220   return $error if $error;
 221
 222   $self->void_date(time) unless $self->void_date;
 223
 224   $self->void_usernum($FS::CurrentUser::CurrentUser->usernum)
 225     unless $self->void_usernum;
 226
 227   $self->SUPER::check;
 228 }
 229
 230 =item display_invnum
 231
 232 Returns the displayed invoice number for this invoice: agent_invid if
 233 cust_bill-default_agent_invid is set and it has a value, invnum otherwise.
 234
 235 =cut
 236
 237 sub display_invnum {
 238   my $self = shift;
 239   my $conf = $self->conf;
 240   if ( $conf->exists('cust_bill-default_agent_invid') && $self->agent_invid ){
 241     return $self->agent_invid;
 242   } else {
 243     return $self->invnum;
 244   }
 245 }
 246
 247 =item void_access_user
 248
 249 Returns the voiding employee object (see L<FS::access_user>).
 250
 251 =cut
 252
 253 sub void_access_user {
 254   my $self = shift;
 255   qsearchs('access_user', { 'usernum' => $self->void_usernum } );
 256 }
 257
 258 =item cust_main
 259
 260 =item cust_bill_pkg
 261
 262 =item reason
 263
 264 Returns the text of the associated void reason (see L<FS::reason>) for this.
 265
 266 =cut
 267
 268 sub cust_bill_pkg { #actually cust_bill_pkg_void objects
 269   my $self = shift;
 270   qsearch('cust_bill_pkg_void', { invnum=>$self->invnum });
 271 }
 272
 273 =back
 274
 275 =item cust_pkg
 276
 277 Returns the packages (see L<FS::cust_pkg>) corresponding to the line items for
 278 this invoice.
 279
 280 =cut
 281
 282 sub cust_pkg {
 283   my $self = shift;
 284   my @cust_pkg = map { $_->pkgnum > 0 ? $_->cust_pkg : () }
 285                  $self->cust_bill_pkg;
 286   my %saw = ();
 287   grep { ! $saw{$_->pkgnum}++ } @cust_pkg;
 288 }
 289
 290 =item search_sql_where HASHREF
 291
 292 Class method which returns an SQL WHERE fragment to search for parameters
 293 specified in HASHREF.  Accepts the following parameters for
 294 L<FS::cust_bill::search_sql_where>: C<_date>, C<invnum_min>, C<invnum_max>,
 295 C<agentnum>, C<custnum>, C<cust_classnum>, C<refnum>.  Also
 296 accepts the following:
 297
 298 =over 4
 299
 300 =item void_date
 301
 302 Arrayref of start and end date to find invoices voided in a date range.
 303
 304 =item void_usernum
 305
 306 User identifier (L<FS::access_user> key) that voided the invoice.
 307
 308 =back
 309
 310 =cut
 311
 312 sub search_sql_where {
 313   my($class, $param) = @_;
 314
 315   my $cust_bill_param = {
 316     map { $_ => $param->{$_} }
 317     grep { exists($param->{$_}) }
 318     qw( _date invnum_min invnum_max agentnum custnum cust_classnum
 319         refnum )
 320   };
 321   my $search_sql = FS::cust_bill->search_sql_where($cust_bill_param);
 322   $search_sql =~ s/cust_bill/cust_bill_void/g;
 323   my @search = ($search_sql);
 324
 325   if ( $param->{void_date} ) {
 326     my($beginning, $ending) = @{$param->{void_date}};
 327     push @search, "cust_bill_void.void_date >= $beginning",
 328                   "cust_bill_void.void_date <  $ending";
 329   }
 330
 331   if ( $param->{void_usernum} =~ /^(\d+)$/ ) {
 332     my $usernum = $1;
 333     push @search, "cust_bill_void.void_usernum = $1";
 334   }
 335
 336   join(" AND ", @search);
 337 }
 338
 339
 340 =item enable_previous
 341
 342 =cut
 343
 344 sub enable_previous { 0 }
 345
 346 # _upgrade_data
 347 #
 348 # Used by FS::Upgrade to migrate to a new database.
 349 sub _upgrade_data {  # class method
 350   my ($class, %opts) = @_;
 351
 352   warn "$me upgrading $class\n" if $DEBUG;
 353
 354   $class->_upgrade_reasonnum(%opts);
 355 }
 356
 357 =back
 358
 359 =head1 BUGS
 360
 361 =head1 SEE ALSO
 362
 363 L<FS::Record>, schema.html from the base documentation.
 364
 365 =cut
 366
 367 1;