4 use vars qw(@ISA $disable_agentcheck);
6 use FS::UID qw( getotaker dbh );
7 use FS::Record qw( qsearch qsearchs );
8 use FS::Misc qw( send_email );
14 use FS::cust_bill_pkg;
16 # need to 'use' these instead of 'require' in sub { cancel, suspend, unsuspend,
18 # because they load configuraion by setting FS::UID::callback (see TODO)
24 # for sending cancel emails in sub cancel
27 @ISA = qw( FS::Record );
29 $disable_agentcheck = 0;
33 my ( $hashref, $cache ) = @_;
34 #if ( $hashref->{'pkgpart'} ) {
35 if ( $hashref->{'pkg'} ) {
36 # #@{ $self->{'_pkgnum'} } = ();
37 # my $subcache = $cache->subcache('pkgpart', 'part_pkg');
38 # $self->{'_pkgpart'} = $subcache;
39 # #push @{ $self->{'_pkgnum'} },
40 # FS::part_pkg->new_or_cached($hashref, $subcache);
41 $self->{'_pkgpart'} = FS::part_pkg->new($hashref);
43 if ( exists $hashref->{'svcnum'} ) {
44 #@{ $self->{'_pkgnum'} } = ();
45 my $subcache = $cache->subcache('svcnum', 'cust_svc', $hashref->{pkgnum});
46 $self->{'_svcnum'} = $subcache;
47 #push @{ $self->{'_pkgnum'} },
48 FS::cust_svc->new_or_cached($hashref, $subcache) if $hashref->{svcnum};
54 FS::cust_pkg - Object methods for cust_pkg objects
60 $record = new FS::cust_pkg \%hash;
61 $record = new FS::cust_pkg { 'column' => 'value' };
63 $error = $record->insert;
65 $error = $new_record->replace($old_record);
67 $error = $record->delete;
69 $error = $record->check;
71 $error = $record->cancel;
73 $error = $record->suspend;
75 $error = $record->unsuspend;
77 $part_pkg = $record->part_pkg;
79 @labels = $record->labels;
81 $seconds = $record->seconds_since($timestamp);
83 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
84 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
88 An FS::cust_pkg object represents a customer billing item. FS::cust_pkg
89 inherits from FS::Record. The following fields are currently supported:
93 =item pkgnum - primary key (assigned automatically for new billing items)
95 =item custnum - Customer (see L<FS::cust_main>)
97 =item pkgpart - Billing item definition (see L<FS::part_pkg>)
101 =item bill - date (next bill date)
109 =item otaker - order taker (assigned automatically if null, see L<FS::UID>)
111 =item manual_flag - If this field is set to 1, disables the automatic
112 unsuspension of this package when using the B<unsuspendauto> config file.
116 Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps;
117 see L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for
118 conversion functions.
126 Create a new billing item. To add the item to the database, see L<"insert">.
130 sub table { 'cust_pkg'; }
134 Adds this billing item to the database ("Orders" the item). If there is an
135 error, returns the error, otherwise returns false.
142 # custnum might not have have been defined in sub check (for one-shot new
143 # customers), so check it here instead
144 # (is this still necessary with transactions?)
146 my $error = $self->ut_number('custnum');
147 return $error if $error;
149 my $cust_main = $self->cust_main;
150 return "Unknown customer ". $self->custnum unless $cust_main;
152 unless ( $disable_agentcheck ) {
153 my $agent = qsearchs( 'agent', { 'agentnum' => $cust_main->agentnum } );
154 my $pkgpart_href = $agent->pkgpart_hashref;
155 return "agent ". $agent->agentnum.
156 " can't purchase pkgpart ". $self->pkgpart
157 unless $pkgpart_href->{ $self->pkgpart };
160 $self->SUPER::insert;
166 This method now works but you probably shouldn't use it.
168 You don't want to delete billing items, because there would then be no record
169 the customer ever purchased the item. Instead, see the cancel method.
174 # return "Can't delete cust_pkg records!";
177 =item replace OLD_RECORD
179 Replaces the OLD_RECORD with this one in the database. If there is an error,
180 returns the error, otherwise returns false.
182 Currently, custnum, setup, bill, susp, expire, and cancel may be changed.
184 Changing pkgpart may have disasterous effects. See the order subroutine.
186 setup and bill are normally updated by calling the bill method of a customer
187 object (see L<FS::cust_main>).
189 suspend is normally updated by the suspend and unsuspend methods.
191 cancel is normally updated by the cancel method (and also the order subroutine
197 my( $new, $old ) = ( shift, shift );
199 #return "Can't (yet?) change pkgpart!" if $old->pkgpart != $new->pkgpart;
200 return "Can't change otaker!" if $old->otaker ne $new->otaker;
203 #return "Can't change setup once it exists!"
204 # if $old->getfield('setup') &&
205 # $old->getfield('setup') != $new->getfield('setup');
207 #some logic for bill, susp, cancel?
209 $new->SUPER::replace($old);
214 Checks all fields to make sure this is a valid billing item. If there is an
215 error, returns the error, otherwise returns false. Called by the insert and
224 $self->ut_numbern('pkgnum')
225 || $self->ut_numbern('custnum')
226 || $self->ut_number('pkgpart')
227 || $self->ut_numbern('setup')
228 || $self->ut_numbern('bill')
229 || $self->ut_numbern('susp')
230 || $self->ut_numbern('cancel')
232 return $error if $error;
234 if ( $self->custnum ) {
235 return "Unknown customer ". $self->custnum unless $self->cust_main;
238 return "Unknown pkgpart: ". $self->pkgpart
239 unless qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
241 $self->otaker(getotaker) unless $self->otaker;
242 $self->otaker =~ /^([\w\.\-]{0,16})$/ or return "Illegal otaker";
245 if ( $self->dbdef_table->column('manual_flag') ) {
246 $self->manual_flag =~ /^([01]?)$/ or return "Illegal manual_flag";
247 $self->manual_flag($1);
255 Cancels and removes all services (see L<FS::cust_svc> and L<FS::part_svc>)
256 in this package, then cancels the package itself (sets the cancel field to
259 If there is an error, returns the error, otherwise returns false.
267 local $SIG{HUP} = 'IGNORE';
268 local $SIG{INT} = 'IGNORE';
269 local $SIG{QUIT} = 'IGNORE';
270 local $SIG{TERM} = 'IGNORE';
271 local $SIG{TSTP} = 'IGNORE';
272 local $SIG{PIPE} = 'IGNORE';
274 my $oldAutoCommit = $FS::UID::AutoCommit;
275 local $FS::UID::AutoCommit = 0;
278 foreach my $cust_svc (
279 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
281 my $error = $cust_svc->cancel;
284 $dbh->rollback if $oldAutoCommit;
285 return "Error cancelling cust_svc: $error";
290 unless ( $self->getfield('cancel') ) {
291 my %hash = $self->hash;
292 $hash{'cancel'} = time;
293 my $new = new FS::cust_pkg ( \%hash );
294 $error = $new->replace($self);
296 $dbh->rollback if $oldAutoCommit;
301 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
303 my $conf = new FS::Conf;
304 my @invoicing_list = grep { $_ ne 'POST' } $self->cust_main->invoicing_list;
305 if ( !$quiet && $conf->exists('emailcancel') && @invoicing_list ) {
306 my $conf = new FS::Conf;
307 my $error = send_email(
308 'from' => $conf->config('invoice_from'),
309 'to' => \@invoicing_list,
310 'subject' => $conf->config('cancelsubject'),
311 'body' => [ map "$_\n", $conf->config('cancelmessage') ],
313 #should this do something on errors?
322 Suspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
323 package, then suspends the package itself (sets the susp field to now).
325 If there is an error, returns the error, otherwise returns false.
333 local $SIG{HUP} = 'IGNORE';
334 local $SIG{INT} = 'IGNORE';
335 local $SIG{QUIT} = 'IGNORE';
336 local $SIG{TERM} = 'IGNORE';
337 local $SIG{TSTP} = 'IGNORE';
338 local $SIG{PIPE} = 'IGNORE';
340 my $oldAutoCommit = $FS::UID::AutoCommit;
341 local $FS::UID::AutoCommit = 0;
344 foreach my $cust_svc (
345 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
347 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
349 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
350 $dbh->rollback if $oldAutoCommit;
351 return "Illegal svcdb value in part_svc!";
354 require "FS/$svcdb.pm";
356 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
358 $error = $svc->suspend;
360 $dbh->rollback if $oldAutoCommit;
367 unless ( $self->getfield('susp') ) {
368 my %hash = $self->hash;
369 $hash{'susp'} = time;
370 my $new = new FS::cust_pkg ( \%hash );
371 $error = $new->replace($self);
373 $dbh->rollback if $oldAutoCommit;
378 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
385 Unsuspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
386 package, then unsuspends the package itself (clears the susp field).
388 If there is an error, returns the error, otherwise returns false.
396 local $SIG{HUP} = 'IGNORE';
397 local $SIG{INT} = 'IGNORE';
398 local $SIG{QUIT} = 'IGNORE';
399 local $SIG{TERM} = 'IGNORE';
400 local $SIG{TSTP} = 'IGNORE';
401 local $SIG{PIPE} = 'IGNORE';
403 my $oldAutoCommit = $FS::UID::AutoCommit;
404 local $FS::UID::AutoCommit = 0;
407 foreach my $cust_svc (
408 qsearch('cust_svc',{'pkgnum'=> $self->pkgnum } )
410 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
412 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
413 $dbh->rollback if $oldAutoCommit;
414 return "Illegal svcdb value in part_svc!";
417 require "FS/$svcdb.pm";
419 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
421 $error = $svc->unsuspend;
423 $dbh->rollback if $oldAutoCommit;
430 unless ( ! $self->getfield('susp') ) {
431 my %hash = $self->hash;
433 my $new = new FS::cust_pkg ( \%hash );
434 $error = $new->replace($self);
436 $dbh->rollback if $oldAutoCommit;
441 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
448 Returns the last bill date, or if there is no last bill date, the setup date.
449 Useful for billing metered services.
455 if ( $self->dbdef_table->column('last_bill') ) {
456 return $self->setfield('last_bill', $_[0]) if @_;
457 return $self->getfield('last_bill') if $self->getfield('last_bill');
459 my $cust_bill_pkg = qsearchs('cust_bill_pkg', { 'pkgnum' => $self->pkgnum,
460 'edate' => $self->bill, } );
461 $cust_bill_pkg ? $cust_bill_pkg->sdate : $self->setup || 0;
466 Returns the definition for this billing item, as an FS::part_pkg object (see
473 #exists( $self->{'_pkgpart'} )
475 ? $self->{'_pkgpart'}
476 : qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
481 Returns the services for this package, as FS::cust_svc objects (see
488 if ( $self->{'_svcnum'} ) {
489 values %{ $self->{'_svcnum'}->cache };
491 qsearch ( 'cust_svc', { 'pkgnum' => $self->pkgnum } );
497 Returns a list of lists, calling the label method for all services
498 (see L<FS::cust_svc>) of this billing item.
504 map { [ $_->label ] } $self->cust_svc;
509 Returns the parent customer object (see L<FS::cust_main>).
515 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
518 =item seconds_since TIMESTAMP
520 Returns the number of seconds all accounts (see L<FS::svc_acct>) in this
521 package have been online since TIMESTAMP, according to the session monitor.
523 TIMESTAMP is specified as a UNIX timestamp; see L<perlfunc/"time">. Also see
524 L<Time::Local> and L<Date::Parse> for conversion functions.
529 my($self, $since) = @_;
532 foreach my $cust_svc (
533 grep { $_->part_svc->svcdb eq 'svc_acct' } $self->cust_svc
535 $seconds += $cust_svc->seconds_since($since);
542 =item seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END
544 Returns the numbers of seconds all accounts (see L<FS::svc_acct>) in this
545 package have been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END
548 TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see
549 L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for conversion
555 sub seconds_since_sqlradacct {
556 my($self, $start, $end) = @_;
560 foreach my $cust_svc (
562 my $part_svc = $_->part_svc;
563 $part_svc->svcdb eq 'svc_acct'
564 && scalar($part_svc->part_export('sqlradius'));
567 $seconds += $cust_svc->seconds_since_sqlradacct($start, $end);
574 =item attribute_since_sqlradacct TIMESTAMP_START TIMESTAMP_END ATTRIBUTE
576 Returns the sum of the given attribute for all accounts (see L<FS::svc_acct>)
577 in this package for sessions ending between TIMESTAMP_START (inclusive) and
581 TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see
582 L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for conversion
587 sub attribute_since_sqlradacct {
588 my($self, $start, $end, $attrib) = @_;
592 foreach my $cust_svc (
594 my $part_svc = $_->part_svc;
595 $part_svc->svcdb eq 'svc_acct'
596 && scalar($part_svc->part_export('sqlradius'));
599 $sum += $cust_svc->attribute_since_sqlradacct($start, $end, $attrib);
612 =item order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]
614 CUSTNUM is a customer (see L<FS::cust_main>)
616 PKGPARTS is a list of pkgparts specifying the the billing item definitions (see
617 L<FS::part_pkg>) to order for this customer. Duplicates are of course
620 REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to
621 remove for this customer. The services (see L<FS::cust_svc>) are moved to the
622 new billing items. An error is returned if this is not possible (see
623 L<FS::pkg_svc>). An empty arrayref is equivalent to not specifying this
626 RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the
627 newly-created cust_pkg objects.
632 my($custnum, $pkgparts, $remove_pkgnums, $return_cust_pkg) = @_;
633 $remove_pkgnums = [] unless defined($remove_pkgnums);
635 my $oldAutoCommit = $FS::UID::AutoCommit;
636 local $FS::UID::AutoCommit = 0;
640 # $part_pkg{$pkgpart} is true iff $custnum may purchase $pkgpart
642 my($cust_main)=qsearchs('cust_main',{'custnum'=>$custnum});
643 my($agent)=qsearchs('agent',{'agentnum'=> $cust_main->agentnum });
644 my %part_pkg = %{ $agent->pkgpart_hashref };
648 # for those packages being removed:
649 #@{ $svcnum{$svcpart} } goes from a svcpart to a list of FS::cust_svc objects
651 foreach $pkgnum ( @{$remove_pkgnums} ) {
652 foreach my $cust_svc (qsearch('cust_svc',{'pkgnum'=>$pkgnum})) {
653 push @{ $svcnum{$cust_svc->getfield('svcpart')} }, $cust_svc;
659 # for those packages the customer is purchasing:
660 # @{$pkgparts} is a list of said packages, by pkgpart
661 # @cust_svc is a corresponding list of lists of FS::Record objects
662 foreach my $pkgpart ( @{$pkgparts} ) {
663 unless ( $part_pkg{$pkgpart} ) {
664 $dbh->rollback if $oldAutoCommit;
665 return "Customer not permitted to purchase pkgpart $pkgpart!";
669 ( $svcnum{$_} && @{ $svcnum{$_} } ) ? shift @{ $svcnum{$_} } : ();
670 } map { $_->svcpart }
671 qsearch('pkg_svc', { pkgpart => $pkgpart,
672 quantity => { op=>'>', value=>'0', } } )
676 #special-case until this can be handled better
677 # move services to new svcparts - even if the svcparts don't match (svcdb
679 # looks like they're moved in no particular order, ewwwwwwww
680 # and looks like just one of each svcpart can be moved... o well
682 #start with still-leftover services
683 #foreach my $svcpart ( grep { scalar(@{ $svcnum{$_} }) } keys %svcnum ) {
684 foreach my $svcpart ( keys %svcnum ) {
685 next unless @{ $svcnum{$svcpart} };
687 my $svcdb = $svcnum{$svcpart}->[0]->part_svc->svcdb;
689 #find an empty place to put one
691 foreach my $pkgpart ( @{$pkgparts} ) {
693 qsearch('pkg_svc', { pkgpart => $pkgpart,
694 quantity => { op=>'>', value=>'0', } } );
696 # grep { $_->quantity > 0 } qsearch('pkg_svc', { pkgpart=>$pkgpart } );
697 if ( ! @{$cust_svc[$i]} #find an empty place to put them with
698 && grep { $svcdb eq $_->part_svc->svcdb } #with appropriate svcdb
702 ( grep { $svcdb eq $_->part_svc->svcdb } @pkg_svc )[0]->svcpart;
703 my $cust_svc = shift @{$svcnum{$svcpart}};
704 $cust_svc->svcpart($new_svcpart);
705 #warn "changing from $svcpart to $new_svcpart!!!\n";
706 $cust_svc[$i] = [ $cust_svc ];
713 #check for leftover services
714 foreach (keys %svcnum) {
715 next unless @{ $svcnum{$_} };
716 $dbh->rollback if $oldAutoCommit;
717 return "Leftover services, svcpart $_: svcnum ".
718 join(', ', map { $_->svcnum } @{ $svcnum{$_} } );
721 #no leftover services, let's make changes.
723 local $SIG{HUP} = 'IGNORE';
724 local $SIG{INT} = 'IGNORE';
725 local $SIG{QUIT} = 'IGNORE';
726 local $SIG{TERM} = 'IGNORE';
727 local $SIG{TSTP} = 'IGNORE';
728 local $SIG{PIPE} = 'IGNORE';
730 #first cancel old packages
731 foreach my $pkgnum ( @{$remove_pkgnums} ) {
732 my($old) = qsearchs('cust_pkg',{'pkgnum'=>$pkgnum});
734 $dbh->rollback if $oldAutoCommit;
735 return "Package $pkgnum not found to remove!";
737 my(%hash) = $old->hash;
738 $hash{'cancel'}=time;
739 my($new) = new FS::cust_pkg ( \%hash );
740 my($error)=$new->replace($old);
742 $dbh->rollback if $oldAutoCommit;
743 return "Couldn't update package $pkgnum: $error";
747 #now add new packages, changing cust_svc records if necessary
749 while ($pkgpart=shift @{$pkgparts} ) {
751 my $new = new FS::cust_pkg {
752 'custnum' => $custnum,
753 'pkgpart' => $pkgpart,
755 my $error = $new->insert;
757 $dbh->rollback if $oldAutoCommit;
758 return "Couldn't insert new cust_pkg record: $error";
760 push @{$return_cust_pkg}, $new if $return_cust_pkg;
761 my $pkgnum = $new->pkgnum;
763 foreach my $cust_svc ( @{ shift @cust_svc } ) {
764 my(%hash) = $cust_svc->hash;
765 $hash{'pkgnum'}=$pkgnum;
766 my $new = new FS::cust_svc ( \%hash );
768 #avoid Record diffing missing changed svcpart field from above.
769 my $old = qsearchs('cust_svc', { 'svcnum' => $cust_svc->svcnum } );
771 my $error = $new->replace($old);
773 $dbh->rollback if $oldAutoCommit;
774 return "Couldn't link old service to new package: $error";
779 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
788 sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?
790 In sub order, the @pkgparts array (passed by reference) is clobbered.
792 Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard
793 method to pass dates to the recur_prog expression, it should do so.
795 FS::svc_acct, FS::svc_domain, FS::svc_www, FS::svc_ip and FS::svc_forward are
796 loaded via 'use' at compile time, rather than via 'require' in sub { setup,
797 suspend, unsuspend, cancel } because they use %FS::UID::callback to load
798 configuration values. Probably need a subroutine which decides what to do
799 based on whether or not we've fetched the user yet, rather than a hash. See
800 FS::UID and the TODO.
802 Now that things are transactional should the check in the insert method be
807 L<FS::Record>, L<FS::cust_main>, L<FS::part_pkg>, L<FS::cust_svc>,
808 L<FS::pkg_svc>, schema.html from the base documentation