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::reason>)
  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
 123 =item insert
 124
 125 Adds this record to the database.  If there is an error, returns the error,
 126 otherwise returns false.
 127
 128 =cut
 129
 130 =item unvoid
 131
 132 "Un-void"s this invoice: Deletes the voided invoice from the database and adds
 133 back a normal invoice (and related tables).
 134
 135 =cut
 136
 137 sub unvoid {
 138   my $self = shift;
 139
 140   local $SIG{HUP} = 'IGNORE';
 141   local $SIG{INT} = 'IGNORE';
 142   local $SIG{QUIT} = 'IGNORE';
 143   local $SIG{TERM} = 'IGNORE';
 144   local $SIG{TSTP} = 'IGNORE';
 145   local $SIG{PIPE} = 'IGNORE';
 146
 147   my $oldAutoCommit = $FS::UID::AutoCommit;
 148   local $FS::UID::AutoCommit = 0;
 149   my $dbh = dbh;
 150
 151   my $cust_bill = new FS::cust_bill ( {
 152     map { $_ => $self->get($_) } fields('cust_bill')
 153   } );
 154   my $error = $cust_bill->insert;
 155   if ( $error ) {
 156     $dbh->rollback if $oldAutoCommit;
 157     return $error;
 158   }
 159
 160   foreach my $cust_bill_pkg_void ( $self->cust_bill_pkg ) {
 161     my $error = $cust_bill_pkg_void->unvoid;
 162     if ( $error ) {
 163       $dbh->rollback if $oldAutoCommit;
 164       return $error;
 165     }
 166   }
 167
 168   $error = $self->delete;
 169   if ( $error ) {
 170     $dbh->rollback if $oldAutoCommit;
 171     return $error;
 172   }
 173
 174   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 175
 176   '';
 177
 178 }
 179
 180 =item delete
 181
 182 Delete this record from the database.
 183
 184 =cut
 185
 186 =item replace OLD_RECORD
 187
 188 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 189 returns the error, otherwise returns false.
 190
 191 =cut
 192
 193 =item check
 194
 195 Checks all fields to make sure this is a valid voided invoice.  If there is
 196 an error, returns the error, otherwise returns false.  Called by the insert
 197 and replace methods.
 198
 199 =cut
 200
 201 sub check {
 202   my $self = shift;
 203
 204   my $error =
 205     $self->ut_number('invnum')
 206     || $self->ut_foreign_key('custnum', 'cust_main', 'custnum' )
 207     || $self->ut_numbern('_date')
 208     || $self->ut_money('charged')
 209     || $self->ut_textn('invoice_terms')
 210     || $self->ut_moneyn('previous_balance')
 211     || $self->ut_moneyn('billing_balance')
 212     || $self->ut_enum('closed', [ '', 'Y' ])
 213     || $self->ut_foreign_keyn('statementnum', 'cust_statement', 'statementnum')
 214     || $self->ut_numbern('agent_invid')
 215     || $self->ut_numbern('promised_date')
 216     || $self->ut_numbern('void_date')
 217     || $self->ut_textn('reason')
 218     || $self->ut_numbern('void_usernum')
 219     || $self->ut_foreign_keyn('reasonnum', 'reason', 'reasonnum')
 220   ;
 221   return $error if $error;
 222
 223   $self->void_date(time) unless $self->void_date;
 224
 225   $self->void_usernum($FS::CurrentUser::CurrentUser->usernum)
 226     unless $self->void_usernum;
 227
 228   $self->SUPER::check;
 229 }
 230
 231 =item display_invnum
 232
 233 Returns the displayed invoice number for this invoice: agent_invid if
 234 cust_bill-default_agent_invid is set and it has a value, invnum otherwise.
 235
 236 =cut
 237
 238 sub display_invnum {
 239   my $self = shift;
 240   my $conf = $self->conf;
 241   if ( $conf->exists('cust_bill-default_agent_invid') && $self->agent_invid ){
 242     return $self->agent_invid;
 243   } else {
 244     return $self->invnum;
 245   }
 246 }
 247
 248 =item void_access_user
 249
 250 Returns the voiding employee object (see L<FS::access_user>).
 251
 252 =cut
 253
 254 sub void_access_user {
 255   my $self = shift;
 256   qsearchs('access_user', { 'usernum' => $self->void_usernum } );
 257 }
 258
 259 =item cust_main
 260
 261 =item cust_bill_pkg
 262
 263 =item reason
 264
 265 Returns the text of the associated void reason (see L<FS::reason>) for this.
 266
 267 =cut
 268
 269 sub cust_bill_pkg { #actually cust_bill_pkg_void objects
 270   my $self = shift;
 271   qsearch('cust_bill_pkg_void', { invnum=>$self->invnum });
 272 }
 273
 274 =back
 275
 276 =item cust_pkg
 277
 278 Returns the packages (see L<FS::cust_pkg>) corresponding to the line items for
 279 this invoice.
 280
 281 =cut
 282
 283 sub cust_pkg {
 284   my $self = shift;
 285   my @cust_pkg = map { $_->pkgnum > 0 ? $_->cust_pkg : () }
 286                  $self->cust_bill_pkg;
 287   my %saw = ();
 288   grep { ! $saw{$_->pkgnum}++ } @cust_pkg;
 289 }
 290
 291 =item search_sql_where HASHREF
 292
 293 Class method which returns an SQL WHERE fragment to search for parameters
 294 specified in HASHREF.  Accepts the following parameters for
 295 L<FS::cust_bill/search_sql_where>: C<_date>, C<invnum_min>, C<invnum_max>,
 296 C<agentnum>, C<custnum>, C<cust_classnum>, C<refnum>.  Also
 297 accepts the following:
 298
 299 =over 4
 300
 301 =item void_date
 302
 303 Arrayref of start and end date to find invoices voided in a date range.
 304
 305 =item void_usernum
 306
 307 User identifier (L<FS::access_user> key) that voided the invoice.
 308
 309 =back
 310
 311 =cut
 312
 313 sub search_sql_where {
 314   my($class, $param) = @_;
 315
 316   my $cust_bill_param = {
 317     map { $_ => $param->{$_} }
 318     grep { exists($param->{$_}) }
 319     qw( _date invnum_min invnum_max agentnum custnum cust_classnum
 320         refnum )
 321   };
 322   my $search_sql = FS::cust_bill->search_sql_where($cust_bill_param);
 323   $search_sql =~ s/cust_bill/cust_bill_void/g;
 324   my @search = ($search_sql);
 325
 326   if ( $param->{void_date} ) {
 327     my($beginning, $ending) = @{$param->{void_date}};
 328     push @search, "cust_bill_void.void_date >= $beginning",
 329                   "cust_bill_void.void_date <  $ending";
 330   }
 331
 332   if ( $param->{void_usernum} =~ /^(\d+)$/ ) {
 333     my $usernum = $1;
 334     push @search, "cust_bill_void.void_usernum = $1";
 335   }
 336
 337   join(" AND ", @search);
 338 }
 339
 340
 341 =item enable_previous
 342
 343 =cut
 344
 345 sub enable_previous { 0 }
 346
 347 # _upgrade_data
 348 #
 349 # Used by FS::Upgrade to migrate to a new database.
 350 sub _upgrade_data {  # class method
 351   my ($class, %opts) = @_;
 352
 353   warn "$me upgrading $class\n" if $DEBUG;
 354
 355   $class->_upgrade_reasonnum(%opts);
 356 }
 357
 358 =back
 359
 360 =head1 BUGS
 361
 362 =head1 SEE ALSO
 363
 364 L<FS::Record>, schema.html from the base documentation.
 365
 366 =cut
 367
 368 1;