4 use vars qw(@ISA $disable_agentcheck @SVCDB_CANCEL_SEQ $DEBUG);
5 use FS::UID qw( getotaker dbh );
6 use FS::Record qw( qsearch qsearchs );
7 use FS::Misc qw( send_email );
13 use FS::cust_bill_pkg;
15 # need to 'use' these instead of 'require' in sub { cancel, suspend, unsuspend,
17 # because they load configuraion by setting FS::UID::callback (see TODO)
23 # for sending cancel emails in sub cancel
26 @ISA = qw( FS::Record );
30 $disable_agentcheck = 0;
32 # The order in which to unprovision services.
33 @SVCDB_CANCEL_SEQ = qw( svc_external
42 my ( $hashref, $cache ) = @_;
43 #if ( $hashref->{'pkgpart'} ) {
44 if ( $hashref->{'pkg'} ) {
45 # #@{ $self->{'_pkgnum'} } = ();
46 # my $subcache = $cache->subcache('pkgpart', 'part_pkg');
47 # $self->{'_pkgpart'} = $subcache;
48 # #push @{ $self->{'_pkgnum'} },
49 # FS::part_pkg->new_or_cached($hashref, $subcache);
50 $self->{'_pkgpart'} = FS::part_pkg->new($hashref);
52 if ( exists $hashref->{'svcnum'} ) {
53 #@{ $self->{'_pkgnum'} } = ();
54 my $subcache = $cache->subcache('svcnum', 'cust_svc', $hashref->{pkgnum});
55 $self->{'_svcnum'} = $subcache;
56 #push @{ $self->{'_pkgnum'} },
57 FS::cust_svc->new_or_cached($hashref, $subcache) if $hashref->{svcnum};
63 FS::cust_pkg - Object methods for cust_pkg objects
69 $record = new FS::cust_pkg \%hash;
70 $record = new FS::cust_pkg { 'column' => 'value' };
72 $error = $record->insert;
74 $error = $new_record->replace($old_record);
76 $error = $record->delete;
78 $error = $record->check;
80 $error = $record->cancel;
82 $error = $record->suspend;
84 $error = $record->unsuspend;
86 $part_pkg = $record->part_pkg;
88 @labels = $record->labels;
90 $seconds = $record->seconds_since($timestamp);
92 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
93 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
97 An FS::cust_pkg object represents a customer billing item. FS::cust_pkg
98 inherits from FS::Record. The following fields are currently supported:
102 =item pkgnum - primary key (assigned automatically for new billing items)
104 =item custnum - Customer (see L<FS::cust_main>)
106 =item pkgpart - Billing item definition (see L<FS::part_pkg>)
110 =item bill - date (next bill date)
112 =item last_bill - last bill date
120 =item otaker - order taker (assigned automatically if null, see L<FS::UID>)
122 =item manual_flag - If this field is set to 1, disables the automatic
123 unsuspension of this package when using the B<unsuspendauto> config file.
127 Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps;
128 see L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for
129 conversion functions.
137 Create a new billing item. To add the item to the database, see L<"insert">.
141 sub table { 'cust_pkg'; }
145 Adds this billing item to the database ("Orders" the item). If there is an
146 error, returns the error, otherwise returns false.
153 # custnum might not have have been defined in sub check (for one-shot new
154 # customers), so check it here instead
155 # (is this still necessary with transactions?)
157 my $error = $self->ut_number('custnum');
158 return $error if $error;
160 my $cust_main = $self->cust_main;
161 return "Unknown custnum: ". $self->custnum unless $cust_main;
163 unless ( $disable_agentcheck ) {
164 my $agent = qsearchs( 'agent', { 'agentnum' => $cust_main->agentnum } );
165 my $pkgpart_href = $agent->pkgpart_hashref;
166 return "agent ". $agent->agentnum.
167 " can't purchase pkgpart ". $self->pkgpart
168 unless $pkgpart_href->{ $self->pkgpart };
171 $self->SUPER::insert;
177 This method now works but you probably shouldn't use it.
179 You don't want to delete billing items, because there would then be no record
180 the customer ever purchased the item. Instead, see the cancel method.
185 # return "Can't delete cust_pkg records!";
188 =item replace OLD_RECORD
190 Replaces the OLD_RECORD with this one in the database. If there is an error,
191 returns the error, otherwise returns false.
193 Currently, custnum, setup, bill, susp, expire, and cancel may be changed.
195 Changing pkgpart may have disasterous effects. See the order subroutine.
197 setup and bill are normally updated by calling the bill method of a customer
198 object (see L<FS::cust_main>).
200 suspend is normally updated by the suspend and unsuspend methods.
202 cancel is normally updated by the cancel method (and also the order subroutine
208 my( $new, $old ) = ( shift, shift );
210 #return "Can't (yet?) change pkgpart!" if $old->pkgpart != $new->pkgpart;
211 return "Can't change otaker!" if $old->otaker ne $new->otaker;
214 #return "Can't change setup once it exists!"
215 # if $old->getfield('setup') &&
216 # $old->getfield('setup') != $new->getfield('setup');
218 #some logic for bill, susp, cancel?
220 $new->SUPER::replace($old);
225 Checks all fields to make sure this is a valid billing item. If there is an
226 error, returns the error, otherwise returns false. Called by the insert and
235 $self->ut_numbern('pkgnum')
236 || $self->ut_numbern('custnum')
237 || $self->ut_number('pkgpart')
238 || $self->ut_numbern('setup')
239 || $self->ut_numbern('bill')
240 || $self->ut_numbern('susp')
241 || $self->ut_numbern('cancel')
243 return $error if $error;
245 if ( $self->custnum ) {
246 return "Unknown customer ". $self->custnum unless $self->cust_main;
249 return "Unknown pkgpart: ". $self->pkgpart
250 unless qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
252 $self->otaker(getotaker) unless $self->otaker;
253 $self->otaker =~ /^([\w\.\-]{0,16})$/ or return "Illegal otaker";
256 if ( $self->dbdef_table->column('manual_flag') ) {
257 $self->manual_flag('') if $self->manual_flag eq ' ';
258 $self->manual_flag =~ /^([01]?)$/
259 or return "Illegal manual_flag ". $self->manual_flag;
260 $self->manual_flag($1);
266 =item cancel [ OPTION => VALUE ... ]
268 Cancels and removes all services (see L<FS::cust_svc> and L<FS::part_svc>)
269 in this package, then cancels the package itself (sets the cancel field to
272 Available options are: I<quiet>
274 I<quiet> can be set true to supress email cancellation notices.
276 If there is an error, returns the error, otherwise returns false.
281 my( $self, %options ) = @_;
284 local $SIG{HUP} = 'IGNORE';
285 local $SIG{INT} = 'IGNORE';
286 local $SIG{QUIT} = 'IGNORE';
287 local $SIG{TERM} = 'IGNORE';
288 local $SIG{TSTP} = 'IGNORE';
289 local $SIG{PIPE} = 'IGNORE';
291 my $oldAutoCommit = $FS::UID::AutoCommit;
292 local $FS::UID::AutoCommit = 0;
296 foreach my $cust_svc (
297 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
299 push @{ $svc{$cust_svc->part_svc->svcdb} }, $cust_svc;
302 foreach my $svcdb (@SVCDB_CANCEL_SEQ) {
303 foreach my $cust_svc (@{ $svc{$svcdb} }) {
304 my $error = $cust_svc->cancel;
307 $dbh->rollback if $oldAutoCommit;
308 return "Error cancelling cust_svc: $error";
313 unless ( $self->getfield('cancel') ) {
314 my %hash = $self->hash;
315 $hash{'cancel'} = time;
316 my $new = new FS::cust_pkg ( \%hash );
317 $error = $new->replace($self);
319 $dbh->rollback if $oldAutoCommit;
324 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
326 my $conf = new FS::Conf;
327 my @invoicing_list = grep { $_ ne 'POST' } $self->cust_main->invoicing_list;
328 if ( !$options{'quiet'} && $conf->exists('emailcancel') && @invoicing_list ) {
329 my $conf = new FS::Conf;
330 my $error = send_email(
331 'from' => $conf->config('invoice_from'),
332 'to' => \@invoicing_list,
333 'subject' => $conf->config('cancelsubject'),
334 'body' => [ map "$_\n", $conf->config('cancelmessage') ],
336 #should this do something on errors?
345 Suspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
346 package, then suspends the package itself (sets the susp field to now).
348 If there is an error, returns the error, otherwise returns false.
356 local $SIG{HUP} = 'IGNORE';
357 local $SIG{INT} = 'IGNORE';
358 local $SIG{QUIT} = 'IGNORE';
359 local $SIG{TERM} = 'IGNORE';
360 local $SIG{TSTP} = 'IGNORE';
361 local $SIG{PIPE} = 'IGNORE';
363 my $oldAutoCommit = $FS::UID::AutoCommit;
364 local $FS::UID::AutoCommit = 0;
367 foreach my $cust_svc (
368 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
370 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
372 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
373 $dbh->rollback if $oldAutoCommit;
374 return "Illegal svcdb value in part_svc!";
377 require "FS/$svcdb.pm";
379 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
381 $error = $svc->suspend;
383 $dbh->rollback if $oldAutoCommit;
390 unless ( $self->getfield('susp') ) {
391 my %hash = $self->hash;
392 $hash{'susp'} = time;
393 my $new = new FS::cust_pkg ( \%hash );
394 $error = $new->replace($self);
396 $dbh->rollback if $oldAutoCommit;
401 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
408 Unsuspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
409 package, then unsuspends the package itself (clears the susp field).
411 If there is an error, returns the error, otherwise returns false.
419 local $SIG{HUP} = 'IGNORE';
420 local $SIG{INT} = 'IGNORE';
421 local $SIG{QUIT} = 'IGNORE';
422 local $SIG{TERM} = 'IGNORE';
423 local $SIG{TSTP} = 'IGNORE';
424 local $SIG{PIPE} = 'IGNORE';
426 my $oldAutoCommit = $FS::UID::AutoCommit;
427 local $FS::UID::AutoCommit = 0;
430 foreach my $cust_svc (
431 qsearch('cust_svc',{'pkgnum'=> $self->pkgnum } )
433 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
435 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
436 $dbh->rollback if $oldAutoCommit;
437 return "Illegal svcdb value in part_svc!";
440 require "FS/$svcdb.pm";
442 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
444 $error = $svc->unsuspend;
446 $dbh->rollback if $oldAutoCommit;
453 unless ( ! $self->getfield('susp') ) {
454 my %hash = $self->hash;
456 my $new = new FS::cust_pkg ( \%hash );
457 $error = $new->replace($self);
459 $dbh->rollback if $oldAutoCommit;
464 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
471 Returns the last bill date, or if there is no last bill date, the setup date.
472 Useful for billing metered services.
478 if ( $self->dbdef_table->column('last_bill') ) {
479 return $self->setfield('last_bill', $_[0]) if @_;
480 return $self->getfield('last_bill') if $self->getfield('last_bill');
482 my $cust_bill_pkg = qsearchs('cust_bill_pkg', { 'pkgnum' => $self->pkgnum,
483 'edate' => $self->bill, } );
484 $cust_bill_pkg ? $cust_bill_pkg->sdate : $self->setup || 0;
489 Returns the definition for this billing item, as an FS::part_pkg object (see
496 #exists( $self->{'_pkgpart'} )
498 ? $self->{'_pkgpart'}
499 : qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
504 Returns the services for this package, as FS::cust_svc objects (see
511 if ( $self->{'_svcnum'} ) {
512 values %{ $self->{'_svcnum'}->cache };
514 qsearch ( 'cust_svc', { 'pkgnum' => $self->pkgnum } );
520 Returns a list of lists, calling the label method for all services
521 (see L<FS::cust_svc>) of this billing item.
527 map { [ $_->label ] } $self->cust_svc;
532 Returns the parent customer object (see L<FS::cust_main>).
538 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
541 =item seconds_since TIMESTAMP
543 Returns the number of seconds all accounts (see L<FS::svc_acct>) in this
544 package have been online since TIMESTAMP, according to the session monitor.
546 TIMESTAMP is specified as a UNIX timestamp; see L<perlfunc/"time">. Also see
547 L<Time::Local> and L<Date::Parse> for conversion functions.
552 my($self, $since) = @_;
555 foreach my $cust_svc (
556 grep { $_->part_svc->svcdb eq 'svc_acct' } $self->cust_svc
558 $seconds += $cust_svc->seconds_since($since);
565 =item seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END
567 Returns the numbers of seconds all accounts (see L<FS::svc_acct>) in this
568 package have been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END
571 TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see
572 L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for conversion
578 sub seconds_since_sqlradacct {
579 my($self, $start, $end) = @_;
583 foreach my $cust_svc (
585 my $part_svc = $_->part_svc;
586 $part_svc->svcdb eq 'svc_acct'
587 && scalar($part_svc->part_export('sqlradius'));
590 $seconds += $cust_svc->seconds_since_sqlradacct($start, $end);
597 =item attribute_since_sqlradacct TIMESTAMP_START TIMESTAMP_END ATTRIBUTE
599 Returns the sum of the given attribute for all accounts (see L<FS::svc_acct>)
600 in this package for sessions ending between TIMESTAMP_START (inclusive) and
604 TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see
605 L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for conversion
610 sub attribute_since_sqlradacct {
611 my($self, $start, $end, $attrib) = @_;
615 foreach my $cust_svc (
617 my $part_svc = $_->part_svc;
618 $part_svc->svcdb eq 'svc_acct'
619 && scalar($part_svc->part_export('sqlradius'));
622 $sum += $cust_svc->attribute_since_sqlradacct($start, $end, $attrib);
629 =item transfer DEST_PKGNUM
631 Transfers as many services as possible from this package to another package.
632 The destination package must already exist. Services are moved only if
633 the destination allows services with the correct I<svcpart> (not svcdb).
634 Any services that can't be moved remain in the original package.
636 Returns an error, if there is one; otherwise, returns the number of services
637 that couldn't be moved.
642 my ($self, $dest_pkgnum) = @_;
649 if (ref ($dest_pkgnum) eq 'FS::cust_pkg') {
650 $dest = $dest_pkgnum;
651 $dest_pkgnum = $dest->pkgnum;
653 $dest = qsearchs('cust_pkg', { pkgnum => $dest_pkgnum });
656 return ('Package does not exist: '.$dest_pkgnum) unless $dest;
658 foreach $pkg_svc (qsearch('pkg_svc', { pkgpart => $dest->pkgpart })) {
659 $target{$pkg_svc->svcpart} = $pkg_svc->quantity;
664 foreach $cust_svc ($dest->cust_svc) {
665 $target{$cust_svc->svcpart}--;
668 foreach $cust_svc ($self->cust_svc) {
669 if($target{$cust_svc->svcpart} > 0) {
670 $target{$cust_svc->svcpart}--;
671 my $new = new FS::cust_svc {
672 svcnum => $cust_svc->svcnum,
673 svcpart => $cust_svc->svcpart,
674 pkgnum => $dest_pkgnum };
675 my $error = $new->replace($cust_svc);
676 return $error if $error;
686 This method is deprecated. See the I<depend_jobnum> option to the insert and
687 order_pkgs methods in FS::cust_main for a better way to defer provisioning.
694 local $SIG{HUP} = 'IGNORE';
695 local $SIG{INT} = 'IGNORE';
696 local $SIG{QUIT} = 'IGNORE';
697 local $SIG{TERM} = 'IGNORE';
698 local $SIG{TSTP} = 'IGNORE';
699 local $SIG{PIPE} = 'IGNORE';
701 my $oldAutoCommit = $FS::UID::AutoCommit;
702 local $FS::UID::AutoCommit = 0;
705 foreach my $cust_svc ( $self->cust_svc ) {
706 #false laziness w/svc_Common::insert
707 my $svc_x = $cust_svc->svc_x;
708 foreach my $part_export ( $cust_svc->part_svc->part_export ) {
709 my $error = $part_export->export_insert($svc_x);
711 $dbh->rollback if $oldAutoCommit;
717 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
728 =item order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]
730 CUSTNUM is a customer (see L<FS::cust_main>)
732 PKGPARTS is a list of pkgparts specifying the the billing item definitions (see
733 L<FS::part_pkg>) to order for this customer. Duplicates are of course
736 REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to
737 remove for this customer. The services (see L<FS::cust_svc>) are moved to the
738 new billing items. An error is returned if this is not possible (see
739 L<FS::pkg_svc>). An empty arrayref is equivalent to not specifying this
742 RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the
743 newly-created cust_pkg objects.
748 my ($custnum, $pkgparts, $remove_pkgnum, $return_cust_pkg) = @_;
750 # Transactionize this whole mess
751 local $SIG{HUP} = 'IGNORE';
752 local $SIG{INT} = 'IGNORE';
753 local $SIG{QUIT} = 'IGNORE';
754 local $SIG{TERM} = 'IGNORE';
755 local $SIG{TSTP} = 'IGNORE';
756 local $SIG{PIPE} = 'IGNORE';
758 my $oldAutoCommit = $FS::UID::AutoCommit;
759 local $FS::UID::AutoCommit = 0;
763 my $cust_main = qsearchs('cust_main', { custnum => $custnum });
764 return "Customer not found: $custnum" unless $cust_main;
766 # Create the new packages.
768 foreach (@$pkgparts) {
769 $cust_pkg = new FS::cust_pkg { custnum => $custnum,
771 $error = $cust_pkg->insert;
773 $dbh->rollback if $oldAutoCommit;
776 push @$return_cust_pkg, $cust_pkg;
778 # $return_cust_pkg now contains refs to all of the newly
781 # Transfer services and cancel old packages.
782 foreach my $old_pkgnum (@$remove_pkgnum) {
783 my $old_pkg = qsearchs ('cust_pkg', { pkgnum => $old_pkgnum });
784 foreach my $new_pkg (@$return_cust_pkg) {
785 $error = $old_pkg->transfer($new_pkg);
786 if ($error and $error == 0) {
787 # $old_pkg->transfer failed.
788 $dbh->rollback if $oldAutoCommit;
793 # Transfers were successful, but we went through all of the
794 # new packages and still had services left on the old package.
795 # We can't cancel the package under the circumstances, so abort.
796 $dbh->rollback if $oldAutoCommit;
797 return "Unable to transfer all services from package ".$old_pkg->pkgnum;
799 $error = $old_pkg->cancel;
805 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
813 sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?
815 In sub order, the @pkgparts array (passed by reference) is clobbered.
817 Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard
818 method to pass dates to the recur_prog expression, it should do so.
820 FS::svc_acct, FS::svc_domain, FS::svc_www, FS::svc_ip and FS::svc_forward are
821 loaded via 'use' at compile time, rather than via 'require' in sub { setup,
822 suspend, unsuspend, cancel } because they use %FS::UID::callback to load
823 configuration values. Probably need a subroutine which decides what to do
824 based on whether or not we've fetched the user yet, rather than a hash. See
825 FS::UID and the TODO.
827 Now that things are transactional should the check in the insert method be
832 L<FS::Record>, L<FS::cust_main>, L<FS::part_pkg>, L<FS::cust_svc>,
833 L<FS::pkg_svc>, schema.html from the base documentation