5 use FS::UID qw( getotaker dbh );
6 use FS::Record qw( qsearch qsearchs );
13 # need to 'use' these instead of 'require' in sub { cancel, suspend, unsuspend,
15 # because they load configuraion by setting FS::UID::callback (see TODO)
21 @ISA = qw( FS::Record );
25 my ( $hashref, $cache ) = @_;
26 #if ( $hashref->{'pkgpart'} ) {
27 if ( $hashref->{'pkg'} ) {
28 # #@{ $self->{'_pkgnum'} } = ();
29 # my $subcache = $cache->subcache('pkgpart', 'part_pkg');
30 # $self->{'_pkgpart'} = $subcache;
31 # #push @{ $self->{'_pkgnum'} },
32 # FS::part_pkg->new_or_cached($hashref, $subcache);
33 $self->{'_pkgpart'} = FS::part_pkg->new($hashref);
35 if ( exists $hashref->{'svcnum'} ) {
36 #@{ $self->{'_pkgnum'} } = ();
37 my $subcache = $cache->subcache('svcnum', 'cust_svc', $hashref->{pkgnum});
38 $self->{'_svcnum'} = $subcache;
39 #push @{ $self->{'_pkgnum'} },
40 FS::cust_svc->new_or_cached($hashref, $subcache) if $hashref->{svcnum};
46 FS::cust_pkg - Object methods for cust_pkg objects
52 $record = new FS::cust_pkg \%hash;
53 $record = new FS::cust_pkg { 'column' => 'value' };
55 $error = $record->insert;
57 $error = $new_record->replace($old_record);
59 $error = $record->delete;
61 $error = $record->check;
63 $error = $record->cancel;
65 $error = $record->suspend;
67 $error = $record->unsuspend;
69 $part_pkg = $record->part_pkg;
71 @labels = $record->labels;
73 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
74 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
78 An FS::cust_pkg object represents a customer billing item. FS::cust_pkg
79 inherits from FS::Record. The following fields are currently supported:
83 =item pkgnum - primary key (assigned automatically for new billing items)
85 =item custnum - Customer (see L<FS::cust_main>)
87 =item pkgpart - Billing item definition (see L<FS::part_pkg>)
99 =item otaker - order taker (assigned automatically if null, see L<FS::UID>)
101 =item manual_flag - If this field is set to 1, disables the automatic
102 unsuspensiond of this package when using the B<unsuspendauto> config file.
106 Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps;
107 see L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for
108 conversion functions.
116 Create a new billing item. To add the item to the database, see L<"insert">.
120 sub table { 'cust_pkg'; }
124 Adds this billing item to the database ("Orders" the item). If there is an
125 error, returns the error, otherwise returns false.
132 # custnum might not have have been defined in sub check (for one-shot new
133 # customers), so check it here instead
134 # (is this still necessary with transactions?)
136 my $error = $self->ut_number('custnum');
137 return $error if $error;
139 return "Unknown customer ". $self->custnum unless $self->cust_main;
141 $self->SUPER::insert;
147 This method now works but you probably shouldn't use it.
149 You don't want to delete billing items, because there would then be no record
150 the customer ever purchased the item. Instead, see the cancel method.
155 # return "Can't delete cust_pkg records!";
158 =item replace OLD_RECORD
160 Replaces the OLD_RECORD with this one in the database. If there is an error,
161 returns the error, otherwise returns false.
163 Currently, custnum, setup, bill, susp, expire, and cancel may be changed.
165 Changing pkgpart may have disasterous effects. See the order subroutine.
167 setup and bill are normally updated by calling the bill method of a customer
168 object (see L<FS::cust_main>).
170 suspend is normally updated by the suspend and unsuspend methods.
172 cancel is normally updated by the cancel method (and also the order subroutine
178 my( $new, $old ) = ( shift, shift );
180 #return "Can't (yet?) change pkgpart!" if $old->pkgpart != $new->pkgpart;
181 return "Can't change otaker!" if $old->otaker ne $new->otaker;
184 #return "Can't change setup once it exists!"
185 # if $old->getfield('setup') &&
186 # $old->getfield('setup') != $new->getfield('setup');
188 #some logic for bill, susp, cancel?
190 $new->SUPER::replace($old);
195 Checks all fields to make sure this is a valid billing item. If there is an
196 error, returns the error, otherwise returns false. Called by the insert and
205 $self->ut_numbern('pkgnum')
206 || $self->ut_numbern('custnum')
207 || $self->ut_number('pkgpart')
208 || $self->ut_numbern('setup')
209 || $self->ut_numbern('bill')
210 || $self->ut_numbern('susp')
211 || $self->ut_numbern('cancel')
213 return $error if $error;
215 if ( $self->custnum ) {
216 return "Unknown customer ". $self->custnum unless $self->cust_main;
219 return "Unknown pkgpart"
220 unless qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
222 $self->otaker(getotaker) unless $self->otaker;
223 $self->otaker =~ /^(\w{0,16})$/ or return "Illegal otaker";
226 if ( $self->dbdef_table->column('manual_flag') ) {
227 $self->manual_flag =~ /^([01]?)$/ or return "Illegal manual_flag";
228 $self->manual_flag($1);
236 Cancels and removes all services (see L<FS::cust_svc> and L<FS::part_svc>)
237 in this package, then cancels the package itself (sets the cancel field to
240 If there is an error, returns the error, otherwise returns false.
248 local $SIG{HUP} = 'IGNORE';
249 local $SIG{INT} = 'IGNORE';
250 local $SIG{QUIT} = 'IGNORE';
251 local $SIG{TERM} = 'IGNORE';
252 local $SIG{TSTP} = 'IGNORE';
253 local $SIG{PIPE} = 'IGNORE';
255 my $oldAutoCommit = $FS::UID::AutoCommit;
256 local $FS::UID::AutoCommit = 0;
259 foreach my $cust_svc (
260 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
262 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
264 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
265 $dbh->rollback if $oldAutoCommit;
266 return "Illegal svcdb value in part_svc!";
269 require "FS/$svcdb.pm";
271 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
273 $error = $svc->cancel;
275 $dbh->rollback if $oldAutoCommit;
276 return "Error cancelling service: $error"
278 $error = $svc->delete;
280 $dbh->rollback if $oldAutoCommit;
281 return "Error deleting service: $error";
285 $error = $cust_svc->delete;
287 $dbh->rollback if $oldAutoCommit;
288 return "Error deleting cust_svc: $error";
293 unless ( $self->getfield('cancel') ) {
294 my %hash = $self->hash;
295 $hash{'cancel'} = time;
296 my $new = new FS::cust_pkg ( \%hash );
297 $error = $new->replace($self);
299 $dbh->rollback if $oldAutoCommit;
304 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
311 Suspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
312 package, then suspends the package itself (sets the susp field to now).
314 If there is an error, returns the error, otherwise returns false.
322 local $SIG{HUP} = 'IGNORE';
323 local $SIG{INT} = 'IGNORE';
324 local $SIG{QUIT} = 'IGNORE';
325 local $SIG{TERM} = 'IGNORE';
326 local $SIG{TSTP} = 'IGNORE';
327 local $SIG{PIPE} = 'IGNORE';
329 my $oldAutoCommit = $FS::UID::AutoCommit;
330 local $FS::UID::AutoCommit = 0;
333 foreach my $cust_svc (
334 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
336 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
338 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
339 $dbh->rollback if $oldAutoCommit;
340 return "Illegal svcdb value in part_svc!";
343 require "FS/$svcdb.pm";
345 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
347 $error = $svc->suspend;
349 $dbh->rollback if $oldAutoCommit;
356 unless ( $self->getfield('susp') ) {
357 my %hash = $self->hash;
358 $hash{'susp'} = time;
359 my $new = new FS::cust_pkg ( \%hash );
360 $error = $new->replace($self);
362 $dbh->rollback if $oldAutoCommit;
367 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
374 Unsuspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
375 package, then unsuspends the package itself (clears the susp field).
377 If there is an error, returns the error, otherwise returns false.
385 local $SIG{HUP} = 'IGNORE';
386 local $SIG{INT} = 'IGNORE';
387 local $SIG{QUIT} = 'IGNORE';
388 local $SIG{TERM} = 'IGNORE';
389 local $SIG{TSTP} = 'IGNORE';
390 local $SIG{PIPE} = 'IGNORE';
392 my $oldAutoCommit = $FS::UID::AutoCommit;
393 local $FS::UID::AutoCommit = 0;
396 foreach my $cust_svc (
397 qsearch('cust_svc',{'pkgnum'=> $self->pkgnum } )
399 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
401 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
402 $dbh->rollback if $oldAutoCommit;
403 return "Illegal svcdb value in part_svc!";
406 require "FS/$svcdb.pm";
408 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
410 $error = $svc->unsuspend;
412 $dbh->rollback if $oldAutoCommit;
419 unless ( ! $self->getfield('susp') ) {
420 my %hash = $self->hash;
422 my $new = new FS::cust_pkg ( \%hash );
423 $error = $new->replace($self);
425 $dbh->rollback if $oldAutoCommit;
430 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
437 Returns the definition for this billing item, as an FS::part_pkg object (see
444 #exists( $self->{'_pkgpart'} )
446 ? $self->{'_pkgpart'}
447 : qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
452 Returns the services for this package, as FS::cust_svc objects (see
459 if ( $self->{'_svcnum'} ) {
460 values %{ $self->{'_svcnum'}->cache };
462 qsearch ( 'cust_svc', { 'pkgnum' => $self->pkgnum } );
468 Returns a list of lists, calling the label method for all services
469 (see L<FS::cust_svc>) of this billing item.
475 map { [ $_->label ] } $self->cust_svc;
480 Returns the parent customer object (see L<FS::cust_main>).
486 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
495 =item order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]
497 CUSTNUM is a customer (see L<FS::cust_main>)
499 PKGPARTS is a list of pkgparts specifying the the billing item definitions (see
500 L<FS::part_pkg>) to order for this customer. Duplicates are of course
503 REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to
504 remove for this customer. The services (see L<FS::cust_svc>) are moved to the
505 new billing items. An error is returned if this is not possible (see
506 L<FS::pkg_svc>). An empty arrayref is equivalent to not specifying this
509 RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the
510 newly-created cust_pkg objects.
515 my($custnum, $pkgparts, $remove_pkgnums, $return_cust_pkg) = @_;
516 $remove_pkgnums = [] unless defined($remove_pkgnums);
518 my $oldAutoCommit = $FS::UID::AutoCommit;
519 local $FS::UID::AutoCommit = 0;
523 # $part_pkg{$pkgpart} is true iff $custnum may purchase $pkgpart
525 my($cust_main)=qsearchs('cust_main',{'custnum'=>$custnum});
526 my($agent)=qsearchs('agent',{'agentnum'=> $cust_main->agentnum });
527 my %part_pkg = %{ $agent->pkgpart_hashref };
531 # for those packages being removed:
532 #@{ $svcnum{$svcpart} } goes from a svcpart to a list of FS::Record
533 # objects (table eq 'cust_svc')
535 foreach $pkgnum ( @{$remove_pkgnums} ) {
537 foreach $cust_svc (qsearch('cust_svc',{'pkgnum'=>$pkgnum})) {
538 push @{ $svcnum{$cust_svc->getfield('svcpart')} }, $cust_svc;
544 # for those packages the customer is purchasing:
545 # @{$pkgparts} is a list of said packages, by pkgpart
546 # @cust_svc is a corresponding list of lists of FS::Record objects
548 foreach $pkgpart ( @{$pkgparts} ) {
549 unless ( $part_pkg{$pkgpart} ) {
550 $dbh->rollback if $oldAutoCommit;
551 return "Customer not permitted to purchase pkgpart $pkgpart!";
555 ( $svcnum{$_} && @{ $svcnum{$_} } ) ? shift @{ $svcnum{$_} } : ();
556 } map { $_->svcpart } qsearch('pkg_svc', { 'pkgpart' => $pkgpart })
560 #check for leftover services
561 foreach (keys %svcnum) {
562 next unless @{ $svcnum{$_} };
563 $dbh->rollback if $oldAutoCommit;
564 return "Leftover services, svcpart $_: svcnum ".
565 join(', ', map { $_->svcnum } @{ $svcnum{$_} } );
568 #no leftover services, let's make changes.
570 local $SIG{HUP} = 'IGNORE';
571 local $SIG{INT} = 'IGNORE';
572 local $SIG{QUIT} = 'IGNORE';
573 local $SIG{TERM} = 'IGNORE';
574 local $SIG{TSTP} = 'IGNORE';
575 local $SIG{PIPE} = 'IGNORE';
577 #first cancel old packages
579 foreach $pkgnum ( @{$remove_pkgnums} ) {
580 my($old) = qsearchs('cust_pkg',{'pkgnum'=>$pkgnum});
582 $dbh->rollback if $oldAutoCommit;
583 return "Package $pkgnum not found to remove!";
585 my(%hash) = $old->hash;
586 $hash{'cancel'}=time;
587 my($new) = new FS::cust_pkg ( \%hash );
588 my($error)=$new->replace($old);
590 $dbh->rollback if $oldAutoCommit;
591 return "Couldn't update package $pkgnum: $error";
595 #now add new packages, changing cust_svc records if necessary
597 while ($pkgpart=shift @{$pkgparts} ) {
599 my $new = new FS::cust_pkg {
600 'custnum' => $custnum,
601 'pkgpart' => $pkgpart,
603 my $error = $new->insert;
605 $dbh->rollback if $oldAutoCommit;
606 return "Couldn't insert new cust_pkg record: $error";
608 push @{$return_cust_pkg}, $new if $return_cust_pkg;
609 my $pkgnum = $new->pkgnum;
611 foreach my $cust_svc ( @{ shift @cust_svc } ) {
612 my(%hash) = $cust_svc->hash;
613 $hash{'pkgnum'}=$pkgnum;
614 my($new) = new FS::cust_svc ( \%hash );
615 my($error)=$new->replace($cust_svc);
617 $dbh->rollback if $oldAutoCommit;
618 return "Couldn't link old service to new package: $error";
623 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
632 $Id: cust_pkg.pm,v 1.13 2001-11-03 17:49:52 ivan Exp $
636 sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?
638 In sub order, the @pkgparts array (passed by reference) is clobbered.
640 Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard
641 method to pass dates to the recur_prog expression, it should do so.
643 FS::svc_acct, FS::svc_acct_sm, and FS::svc_domain are loaded via 'use' at
644 compile time, rather than via 'require' in sub { setup, suspend, unsuspend,
645 cancel } because they use %FS::UID::callback to load configuration values.
646 Probably need a subroutine which decides what to do based on whether or not
647 we've fetched the user yet, rather than a hash. See FS::UID and the TODO.
649 Now that things are transactional should the check in the insert method be
654 L<FS::Record>, L<FS::cust_main>, L<FS::part_pkg>, L<FS::cust_svc>,
655 L<FS::pkg_svc>, schema.html from the base documentation