5 use FS::UID qw( getotaker dbh );
6 use FS::Record qw( qsearch qsearchs );
12 use FS::cust_bill_pkg;
14 # need to 'use' these instead of 'require' in sub { cancel, suspend, unsuspend,
16 # because they load configuraion by setting FS::UID::callback (see TODO)
22 @ISA = qw( FS::Record );
26 my ( $hashref, $cache ) = @_;
27 #if ( $hashref->{'pkgpart'} ) {
28 if ( $hashref->{'pkg'} ) {
29 # #@{ $self->{'_pkgnum'} } = ();
30 # my $subcache = $cache->subcache('pkgpart', 'part_pkg');
31 # $self->{'_pkgpart'} = $subcache;
32 # #push @{ $self->{'_pkgnum'} },
33 # FS::part_pkg->new_or_cached($hashref, $subcache);
34 $self->{'_pkgpart'} = FS::part_pkg->new($hashref);
36 if ( exists $hashref->{'svcnum'} ) {
37 #@{ $self->{'_pkgnum'} } = ();
38 my $subcache = $cache->subcache('svcnum', 'cust_svc', $hashref->{pkgnum});
39 $self->{'_svcnum'} = $subcache;
40 #push @{ $self->{'_pkgnum'} },
41 FS::cust_svc->new_or_cached($hashref, $subcache) if $hashref->{svcnum};
47 FS::cust_pkg - Object methods for cust_pkg objects
53 $record = new FS::cust_pkg \%hash;
54 $record = new FS::cust_pkg { 'column' => 'value' };
56 $error = $record->insert;
58 $error = $new_record->replace($old_record);
60 $error = $record->delete;
62 $error = $record->check;
64 $error = $record->cancel;
66 $error = $record->suspend;
68 $error = $record->unsuspend;
70 $part_pkg = $record->part_pkg;
72 @labels = $record->labels;
74 $seconds = $record->seconds_since($timestamp);
76 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
77 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
81 An FS::cust_pkg object represents a customer billing item. FS::cust_pkg
82 inherits from FS::Record. The following fields are currently supported:
86 =item pkgnum - primary key (assigned automatically for new billing items)
88 =item custnum - Customer (see L<FS::cust_main>)
90 =item pkgpart - Billing item definition (see L<FS::part_pkg>)
94 =item bill - date (next bill date)
102 =item otaker - order taker (assigned automatically if null, see L<FS::UID>)
104 =item manual_flag - If this field is set to 1, disables the automatic
105 unsuspension of this package when using the B<unsuspendauto> config file.
109 Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps;
110 see L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for
111 conversion functions.
119 Create a new billing item. To add the item to the database, see L<"insert">.
123 sub table { 'cust_pkg'; }
127 Adds this billing item to the database ("Orders" the item). If there is an
128 error, returns the error, otherwise returns false.
135 # custnum might not have have been defined in sub check (for one-shot new
136 # customers), so check it here instead
137 # (is this still necessary with transactions?)
139 my $error = $self->ut_number('custnum');
140 return $error if $error;
142 my $cust_main = $self->cust_main;
143 return "Unknown customer ". $self->custnum unless $cust_main;
145 my $agent = qsearchs( 'agent', { 'agentnum' => $cust_main->agentnum } );
146 my $pkgpart_href = $agent->pkgpart_hashref;
147 return "agent ". $agent->agentnum. " can't purchase pkgpart ". $self->pkgpart
148 unless $pkgpart_href->{ $self->pkgpart };
150 $self->SUPER::insert;
156 This method now works but you probably shouldn't use it.
158 You don't want to delete billing items, because there would then be no record
159 the customer ever purchased the item. Instead, see the cancel method.
164 # return "Can't delete cust_pkg records!";
167 =item replace OLD_RECORD
169 Replaces the OLD_RECORD with this one in the database. If there is an error,
170 returns the error, otherwise returns false.
172 Currently, custnum, setup, bill, susp, expire, and cancel may be changed.
174 Changing pkgpart may have disasterous effects. See the order subroutine.
176 setup and bill are normally updated by calling the bill method of a customer
177 object (see L<FS::cust_main>).
179 suspend is normally updated by the suspend and unsuspend methods.
181 cancel is normally updated by the cancel method (and also the order subroutine
187 my( $new, $old ) = ( shift, shift );
189 #return "Can't (yet?) change pkgpart!" if $old->pkgpart != $new->pkgpart;
190 return "Can't change otaker!" if $old->otaker ne $new->otaker;
193 #return "Can't change setup once it exists!"
194 # if $old->getfield('setup') &&
195 # $old->getfield('setup') != $new->getfield('setup');
197 #some logic for bill, susp, cancel?
199 $new->SUPER::replace($old);
204 Checks all fields to make sure this is a valid billing item. If there is an
205 error, returns the error, otherwise returns false. Called by the insert and
214 $self->ut_numbern('pkgnum')
215 || $self->ut_numbern('custnum')
216 || $self->ut_number('pkgpart')
217 || $self->ut_numbern('setup')
218 || $self->ut_numbern('bill')
219 || $self->ut_numbern('susp')
220 || $self->ut_numbern('cancel')
222 return $error if $error;
224 if ( $self->custnum ) {
225 return "Unknown customer ". $self->custnum unless $self->cust_main;
228 return "Unknown pkgpart: ". $self->pkgpart
229 unless qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
231 $self->otaker(getotaker) unless $self->otaker;
232 $self->otaker =~ /^([\w\.\-]{0,16})$/ or return "Illegal otaker";
235 if ( $self->dbdef_table->column('manual_flag') ) {
236 $self->manual_flag =~ /^([01]?)$/ or return "Illegal manual_flag";
237 $self->manual_flag($1);
245 Cancels and removes all services (see L<FS::cust_svc> and L<FS::part_svc>)
246 in this package, then cancels the package itself (sets the cancel field to
249 If there is an error, returns the error, otherwise returns false.
257 local $SIG{HUP} = 'IGNORE';
258 local $SIG{INT} = 'IGNORE';
259 local $SIG{QUIT} = 'IGNORE';
260 local $SIG{TERM} = 'IGNORE';
261 local $SIG{TSTP} = 'IGNORE';
262 local $SIG{PIPE} = 'IGNORE';
264 my $oldAutoCommit = $FS::UID::AutoCommit;
265 local $FS::UID::AutoCommit = 0;
268 foreach my $cust_svc (
269 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
271 my $error = $cust_svc->cancel;
274 $dbh->rollback if $oldAutoCommit;
275 return "Error cancelling cust_svc: $error";
280 unless ( $self->getfield('cancel') ) {
281 my %hash = $self->hash;
282 $hash{'cancel'} = time;
283 my $new = new FS::cust_pkg ( \%hash );
284 $error = $new->replace($self);
286 $dbh->rollback if $oldAutoCommit;
291 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
298 Suspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
299 package, then suspends the package itself (sets the susp field to now).
301 If there is an error, returns the error, otherwise returns false.
309 local $SIG{HUP} = 'IGNORE';
310 local $SIG{INT} = 'IGNORE';
311 local $SIG{QUIT} = 'IGNORE';
312 local $SIG{TERM} = 'IGNORE';
313 local $SIG{TSTP} = 'IGNORE';
314 local $SIG{PIPE} = 'IGNORE';
316 my $oldAutoCommit = $FS::UID::AutoCommit;
317 local $FS::UID::AutoCommit = 0;
320 foreach my $cust_svc (
321 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
323 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
325 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
326 $dbh->rollback if $oldAutoCommit;
327 return "Illegal svcdb value in part_svc!";
330 require "FS/$svcdb.pm";
332 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
334 $error = $svc->suspend;
336 $dbh->rollback if $oldAutoCommit;
343 unless ( $self->getfield('susp') ) {
344 my %hash = $self->hash;
345 $hash{'susp'} = time;
346 my $new = new FS::cust_pkg ( \%hash );
347 $error = $new->replace($self);
349 $dbh->rollback if $oldAutoCommit;
354 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
361 Unsuspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
362 package, then unsuspends the package itself (clears the susp field).
364 If there is an error, returns the error, otherwise returns false.
372 local $SIG{HUP} = 'IGNORE';
373 local $SIG{INT} = 'IGNORE';
374 local $SIG{QUIT} = 'IGNORE';
375 local $SIG{TERM} = 'IGNORE';
376 local $SIG{TSTP} = 'IGNORE';
377 local $SIG{PIPE} = 'IGNORE';
379 my $oldAutoCommit = $FS::UID::AutoCommit;
380 local $FS::UID::AutoCommit = 0;
383 foreach my $cust_svc (
384 qsearch('cust_svc',{'pkgnum'=> $self->pkgnum } )
386 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
388 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
389 $dbh->rollback if $oldAutoCommit;
390 return "Illegal svcdb value in part_svc!";
393 require "FS/$svcdb.pm";
395 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
397 $error = $svc->unsuspend;
399 $dbh->rollback if $oldAutoCommit;
406 unless ( ! $self->getfield('susp') ) {
407 my %hash = $self->hash;
409 my $new = new FS::cust_pkg ( \%hash );
410 $error = $new->replace($self);
412 $dbh->rollback if $oldAutoCommit;
417 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
424 Returns the last bill date, or if there is no last bill date, the setup date.
425 Useful for billing metered services.
431 my $cust_bill_pkg = qsearchs('cust_bill_pkg', { 'pkgnum' => $self->pkgnum,
432 'edate' => $self->bill, } );
433 $cust_bill_pkg ? $cust_bill_pkg->sdate : $self->setup || 0;
438 Returns the definition for this billing item, as an FS::part_pkg object (see
445 #exists( $self->{'_pkgpart'} )
447 ? $self->{'_pkgpart'}
448 : qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
453 Returns the services for this package, as FS::cust_svc objects (see
460 if ( $self->{'_svcnum'} ) {
461 values %{ $self->{'_svcnum'}->cache };
463 qsearch ( 'cust_svc', { 'pkgnum' => $self->pkgnum } );
469 Returns a list of lists, calling the label method for all services
470 (see L<FS::cust_svc>) of this billing item.
476 map { [ $_->label ] } $self->cust_svc;
481 Returns the parent customer object (see L<FS::cust_main>).
487 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
490 =item seconds_since TIMESTAMP
492 Returns the number of seconds all accounts (see L<FS::svc_acct>) in this
493 package have been online since TIMESTAMP, according to the session monitor.
495 TIMESTAMP is specified as a UNIX timestamp; see L<perlfunc/"time">. Also see
496 L<Time::Local> and L<Date::Parse> for conversion functions.
501 my($self, $since) = @_;
504 foreach my $cust_svc (
505 grep { $_->part_svc->svcdb eq 'svc_acct' } $self->cust_svc
507 $seconds += $cust_svc->seconds_since($since);
514 =item seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END DATASRC DB_USERNAME DB_PASSWORD
516 Returns the numbers of seconds all accounts (see L<FS::svc_acct>) in this
517 package have been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END
518 (exclusive), according to an external SQL radacct table, such as those
519 generated by ICRADIUS or FreeRADIUS. Sessions which started in the specified
520 range but are still open are counted from session start to the end of the
521 range. Also, sessions which end in the range but started earlier are counted
522 from the start of the range to session end. Finally, sessions which start
523 before the range but end after (or are still open) are counted for the entire
526 TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see
527 L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for conversion
533 sub seconds_since_sqlradacct {
534 my($self, $start, $end, $datasrc, $db_user, $db_pass) = @_;
536 my $dbh = DBI->connect($datasrc, $db_user, $db_pass)
537 or die "can't connect to $datasrc: ". $DBI::errstr;
541 foreach my $cust_svc (
542 grep { $_->part_svc->svcdb eq 'svc_acct' } $self->cust_svc
544 $seconds += $cust_svc->seconds_since_sqlradacct($start, $end, $dbh);
557 =item order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]
559 CUSTNUM is a customer (see L<FS::cust_main>)
561 PKGPARTS is a list of pkgparts specifying the the billing item definitions (see
562 L<FS::part_pkg>) to order for this customer. Duplicates are of course
565 REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to
566 remove for this customer. The services (see L<FS::cust_svc>) are moved to the
567 new billing items. An error is returned if this is not possible (see
568 L<FS::pkg_svc>). An empty arrayref is equivalent to not specifying this
571 RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the
572 newly-created cust_pkg objects.
577 my($custnum, $pkgparts, $remove_pkgnums, $return_cust_pkg) = @_;
578 $remove_pkgnums = [] unless defined($remove_pkgnums);
580 my $oldAutoCommit = $FS::UID::AutoCommit;
581 local $FS::UID::AutoCommit = 0;
585 # $part_pkg{$pkgpart} is true iff $custnum may purchase $pkgpart
587 my($cust_main)=qsearchs('cust_main',{'custnum'=>$custnum});
588 my($agent)=qsearchs('agent',{'agentnum'=> $cust_main->agentnum });
589 my %part_pkg = %{ $agent->pkgpart_hashref };
593 # for those packages being removed:
594 #@{ $svcnum{$svcpart} } goes from a svcpart to a list of FS::cust_svc objects
596 foreach $pkgnum ( @{$remove_pkgnums} ) {
597 foreach my $cust_svc (qsearch('cust_svc',{'pkgnum'=>$pkgnum})) {
598 push @{ $svcnum{$cust_svc->getfield('svcpart')} }, $cust_svc;
604 # for those packages the customer is purchasing:
605 # @{$pkgparts} is a list of said packages, by pkgpart
606 # @cust_svc is a corresponding list of lists of FS::Record objects
607 foreach my $pkgpart ( @{$pkgparts} ) {
608 unless ( $part_pkg{$pkgpart} ) {
609 $dbh->rollback if $oldAutoCommit;
610 return "Customer not permitted to purchase pkgpart $pkgpart!";
614 ( $svcnum{$_} && @{ $svcnum{$_} } ) ? shift @{ $svcnum{$_} } : ();
615 } map { $_->svcpart }
616 qsearch('pkg_svc', { pkgpart => $pkgpart,
617 quantity => { op=>'>', value=>'0', } } )
621 #special-case until this can be handled better
622 # move services to new svcparts - even if the svcparts don't match (svcdb
624 # looks like they're moved in no particular order, ewwwwwwww
625 # and looks like just one of each svcpart can be moved... o well
627 #start with still-leftover services
628 #foreach my $svcpart ( grep { scalar(@{ $svcnum{$_} }) } keys %svcnum ) {
629 foreach my $svcpart ( keys %svcnum ) {
630 next unless @{ $svcnum{$svcpart} };
632 my $svcdb = $svcnum{$svcpart}->[0]->part_svc->svcdb;
634 #find an empty place to put one
636 foreach my $pkgpart ( @{$pkgparts} ) {
638 qsearch('pkg_svc', { pkgpart => $pkgpart,
639 quantity => { op=>'>', value=>'0', } } );
641 # grep { $_->quantity > 0 } qsearch('pkg_svc', { pkgpart=>$pkgpart } );
642 if ( ! @{$cust_svc[$i]} #find an empty place to put them with
643 && grep { $svcdb eq $_->part_svc->svcdb } #with appropriate svcdb
647 ( grep { $svcdb eq $_->part_svc->svcdb } @pkg_svc )[0]->svcpart;
648 my $cust_svc = shift @{$svcnum{$svcpart}};
649 $cust_svc->svcpart($new_svcpart);
650 #warn "changing from $svcpart to $new_svcpart!!!\n";
651 $cust_svc[$i] = [ $cust_svc ];
658 #check for leftover services
659 foreach (keys %svcnum) {
660 next unless @{ $svcnum{$_} };
661 $dbh->rollback if $oldAutoCommit;
662 return "Leftover services, svcpart $_: svcnum ".
663 join(', ', map { $_->svcnum } @{ $svcnum{$_} } );
666 #no leftover services, let's make changes.
668 local $SIG{HUP} = 'IGNORE';
669 local $SIG{INT} = 'IGNORE';
670 local $SIG{QUIT} = 'IGNORE';
671 local $SIG{TERM} = 'IGNORE';
672 local $SIG{TSTP} = 'IGNORE';
673 local $SIG{PIPE} = 'IGNORE';
675 #first cancel old packages
676 foreach my $pkgnum ( @{$remove_pkgnums} ) {
677 my($old) = qsearchs('cust_pkg',{'pkgnum'=>$pkgnum});
679 $dbh->rollback if $oldAutoCommit;
680 return "Package $pkgnum not found to remove!";
682 my(%hash) = $old->hash;
683 $hash{'cancel'}=time;
684 my($new) = new FS::cust_pkg ( \%hash );
685 my($error)=$new->replace($old);
687 $dbh->rollback if $oldAutoCommit;
688 return "Couldn't update package $pkgnum: $error";
692 #now add new packages, changing cust_svc records if necessary
694 while ($pkgpart=shift @{$pkgparts} ) {
696 my $new = new FS::cust_pkg {
697 'custnum' => $custnum,
698 'pkgpart' => $pkgpart,
700 my $error = $new->insert;
702 $dbh->rollback if $oldAutoCommit;
703 return "Couldn't insert new cust_pkg record: $error";
705 push @{$return_cust_pkg}, $new if $return_cust_pkg;
706 my $pkgnum = $new->pkgnum;
708 foreach my $cust_svc ( @{ shift @cust_svc } ) {
709 my(%hash) = $cust_svc->hash;
710 $hash{'pkgnum'}=$pkgnum;
711 my $new = new FS::cust_svc ( \%hash );
713 #avoid Record diffing missing changed svcpart field from above.
714 my $old = qsearchs('cust_svc', { 'svcnum' => $cust_svc->svcnum } );
716 my $error = $new->replace($old);
718 $dbh->rollback if $oldAutoCommit;
719 return "Couldn't link old service to new package: $error";
724 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
733 $Id: cust_pkg.pm,v 1.26 2002-10-14 06:17:14 ivan Exp $
737 sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?
739 In sub order, the @pkgparts array (passed by reference) is clobbered.
741 Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard
742 method to pass dates to the recur_prog expression, it should do so.
744 FS::svc_acct, FS::svc_domain, FS::svc_www and FS::svc_forward are loaded via
745 'use' at compile time, rather than via 'require' in sub
746 { setup, suspend, unsuspend, cancel } because they use %FS::UID::callback to
747 load configuration values. Probably need a subroutine which decides what to
748 do based on whether or not we've fetched the user yet, rather than a hash.
749 See FS::UID and the TODO.
751 Now that things are transactional should the check in the insert method be
756 L<FS::Record>, L<FS::cust_main>, L<FS::part_pkg>, L<FS::cust_svc>,
757 L<FS::pkg_svc>, schema.html from the base documentation