1 package FS::cust_main::Packages;
4 use vars qw( $DEBUG $me $skip_label_sort );
5 use List::Util qw( min );
7 use FS::Record qw( qsearch qsearchs );
10 use FS::contact; # for attach_pkgs
11 use FS::cust_location; #
14 $me = '[FS::cust_main::Packages]';
19 FS::cust_main::Packages - Packages mixin for cust_main
25 These methods are available on FS::cust_main objects;
31 =item order_pkg HASHREF | OPTION => VALUE ...
33 Orders a single package.
35 Note that if the package definition has supplemental packages, those will
38 Options may be passed as a list of key/value pairs or as a hash reference.
49 Optional FS::cust_location object. If not specified, the customer's
50 ship_location will be used.
54 Optional arryaref of FS::svc_* service objects.
58 If this option is set to a job queue jobnum (see L<FS::queue>), all provisioning
59 jobs will have a dependancy on the supplied job (they will not run until the
60 specific job completes). This can be used to defer provisioning until some
61 action completes (such as running the customer's credit card successfully).
65 This option is option is deprecated but still works for now (use
66 I<depend_jobnum> instead for new code). If I<noexport> is set true, no
67 provisioning jobs (exports) are scheduled. (You can schedule them later with
68 the B<reexport> method for each cust_pkg object. Using the B<reexport> method
69 on the cust_main object is not recommended, as existing services will also be
74 Optional subject for a ticket created and attached to this customer
78 Optional queue name for ticket additions
86 my $opt = ref($_[0]) ? shift : { @_ };
88 local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
90 warn "$me order_pkg called with options ".
91 join(', ', map { "$_: $opt->{$_}" } keys %$opt ). "\n"
94 local $FS::svc_Common::noexport_hack = 1 if $opt->{'noexport'};
96 my $cust_pkg = $opt->{'cust_pkg'};
97 my $svcs = $opt->{'svcs'} || [];
100 $svc_options{'depend_jobnum'} = $opt->{'depend_jobnum'}
101 if exists($opt->{'depend_jobnum'}) && $opt->{'depend_jobnum'};
103 my %insert_params = map { $opt->{$_} ? ( $_ => $opt->{$_} ) : () }
104 qw( ticket_subject ticket_queue allow_pkgpart );
106 local $SIG{HUP} = 'IGNORE';
107 local $SIG{INT} = 'IGNORE';
108 local $SIG{QUIT} = 'IGNORE';
109 local $SIG{TERM} = 'IGNORE';
110 local $SIG{TSTP} = 'IGNORE';
111 local $SIG{PIPE} = 'IGNORE';
113 my $oldAutoCommit = $FS::UID::AutoCommit;
114 local $FS::UID::AutoCommit = 0;
117 if ( $opt->{'contactnum'} and $opt->{'contactnum'} != -1 ) {
119 $cust_pkg->contactnum($opt->{'contactnum'});
121 } elsif ( $opt->{'contact'} ) {
123 if ( ! $opt->{'contact'}->contactnum ) {
125 my $error = $opt->{'contact'}->insert;
127 $dbh->rollback if $oldAutoCommit;
128 return "inserting contact (transaction rolled back): $error";
131 $cust_pkg->contactnum($opt->{'contact'}->contactnum);
135 # $cust_pkg->contactnum();
139 if ( $opt->{'locationnum'} and $opt->{'locationnum'} != -1 ) {
141 $cust_pkg->locationnum($opt->{'locationnum'});
143 } elsif ( $opt->{'cust_location'} ) {
145 my $error = $opt->{'cust_location'}->find_or_insert;
147 $dbh->rollback if $oldAutoCommit;
148 return "inserting cust_location (transaction rolled back): $error";
150 $cust_pkg->locationnum($opt->{'cust_location'}->locationnum);
152 } elsif ( ! $cust_pkg->locationnum ) {
154 $cust_pkg->locationnum($self->ship_locationnum);
158 $cust_pkg->custnum( $self->custnum );
160 my $error = $cust_pkg->insert( %insert_params );
162 $dbh->rollback if $oldAutoCommit;
163 return "inserting cust_pkg (transaction rolled back): $error";
166 foreach my $svc_something ( @{ $opt->{'svcs'} } ) {
167 if ( $svc_something->svcnum ) {
168 my $old_cust_svc = $svc_something->cust_svc;
169 my $new_cust_svc = new FS::cust_svc { $old_cust_svc->hash };
170 $new_cust_svc->pkgnum( $cust_pkg->pkgnum);
171 $error = $new_cust_svc->replace($old_cust_svc);
173 $svc_something->pkgnum( $cust_pkg->pkgnum );
174 if ( $svc_something->isa('FS::svc_acct') ) {
175 foreach ( grep { $opt->{$_.'_ref'} && ${ $opt->{$_.'_ref'} } }
176 qw( seconds upbytes downbytes totalbytes ) ) {
177 $svc_something->$_( $svc_something->$_() + ${ $opt->{$_.'_ref'} } );
178 ${ $opt->{$_.'_ref'} } = 0;
181 $error = $svc_something->insert(%svc_options);
184 $dbh->rollback if $oldAutoCommit;
185 return "inserting svc_ (transaction rolled back): $error";
189 # add supplemental packages, if any are needed
190 my $part_pkg = FS::part_pkg->by_key($cust_pkg->pkgpart);
191 foreach my $link ($part_pkg->supp_part_pkg_link) {
192 #warn "inserting supplemental package ".$link->dst_pkgpart;
193 my $pkg = FS::cust_pkg->new({
194 'pkgpart' => $link->dst_pkgpart,
195 'pkglinknum' => $link->pkglinknum,
196 'custnum' => $self->custnum,
197 'main_pkgnum' => $cust_pkg->pkgnum,
198 # try to prevent as many surprises as possible
199 'allow_pkgpart' => $opt->{'allow_pkgpart'},
200 map { $_ => $cust_pkg->$_() }
202 start_date order_date expire adjourn contract_end
203 refnum discountnum waive_setup
206 $error = $self->order_pkg('cust_pkg' => $pkg,
207 'locationnum' => $cust_pkg->locationnum);
209 $dbh->rollback if $oldAutoCommit;
210 return "inserting supplemental package: $error";
214 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
219 =item order_pkgs HASHREF [ , OPTION => VALUE ... ]
221 Like the insert method on an existing record, this method orders multiple
222 packages and included services atomicaly. Pass a Tie::RefHash data structure
223 to this method containing FS::cust_pkg and FS::svc_I<tablename> objects.
224 There should be a better explanation of this, but until then, here's an
228 tie %hash, 'Tie::RefHash'; #this part is important
230 $cust_pkg => [ $svc_acct ],
233 $cust_main->order_pkgs( \%hash, 'noexport'=>1 );
235 Services can be new, in which case they are inserted, or existing unaudited
236 services, in which case they are linked to the newly-created package.
238 Currently available options are: I<depend_jobnum>, I<noexport>, I<seconds_ref>,
239 I<upbytes_ref>, I<downbytes_ref>, and I<totalbytes_ref>.
241 If I<depend_jobnum> is set, all provisioning jobs will have a dependancy
242 on the supplied jobnum (they will not run until the specific job completes).
243 This can be used to defer provisioning until some action completes (such
244 as running the customer's credit card successfully).
246 The I<noexport> option is deprecated but still works for now (use
247 I<depend_jobnum> instead for new code). If I<noexport> is set true, no
248 provisioning jobs (exports) are scheduled. (You can schedule them later with
249 the B<reexport> method for each cust_pkg object. Using the B<reexport> method
250 on the cust_main object is not recommended, as existing services will also be
253 If I<seconds_ref>, I<upbytes_ref>, I<downbytes_ref>, or I<totalbytes_ref> is
254 provided, the scalars (provided by references) will be incremented by the
255 values of the prepaid card.`
261 my $cust_pkgs = shift;
264 local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
266 warn "$me order_pkgs called with options ".
267 join(', ', map { "$_: $options{$_}" } keys %options ). "\n"
270 local $SIG{HUP} = 'IGNORE';
271 local $SIG{INT} = 'IGNORE';
272 local $SIG{QUIT} = 'IGNORE';
273 local $SIG{TERM} = 'IGNORE';
274 local $SIG{TSTP} = 'IGNORE';
275 local $SIG{PIPE} = 'IGNORE';
277 my $oldAutoCommit = $FS::UID::AutoCommit;
278 local $FS::UID::AutoCommit = 0;
281 local $FS::svc_Common::noexport_hack = 1 if $options{'noexport'};
283 foreach my $cust_pkg ( keys %$cust_pkgs ) {
285 my $error = $self->order_pkg(
286 'cust_pkg' => $cust_pkg,
287 'svcs' => $cust_pkgs->{$cust_pkg},
288 map { $_ => $options{$_} }
289 qw( seconds_ref upbytes_ref downbytes_ref totalbytes_ref depend_jobnum )
292 $dbh->rollback if $oldAutoCommit;
298 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
304 Merges this customer's package's into the target customer and then cancels them.
309 my( $self, $new_custnum ) = @_;
311 #mostly false laziness w/ merge
313 return "Can't attach packages to self" if $self->custnum == $new_custnum;
315 my $new_cust_main = qsearchs( 'cust_main', { 'custnum' => $new_custnum } )
316 or return "Invalid new customer number: $new_custnum";
318 return 'Access denied: "Merge customer across agents" access right required to merge into a customer of a different agent'
319 if $self->agentnum != $new_cust_main->agentnum
320 && ! $FS::CurrentUser::CurrentUser->access_right('Merge customer across agents');
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 if ( qsearch('agent', { 'agent_custnum' => $self->custnum } ) ) {
334 $dbh->rollback if $oldAutoCommit;
335 return "Can't merge a master agent customer";
339 if ( qsearch('access_user', { 'user_custnum' => $self->custnum } ) ) {
340 $dbh->rollback if $oldAutoCommit;
341 return "Can't merge a master employee customer";
344 if ( qsearch('cust_pay_pending', { 'custnum' => $self->custnum,
345 'status' => { op=>'!=', value=>'done' },
349 $dbh->rollback if $oldAutoCommit;
350 return "Can't merge a customer with pending payments";
353 #end of false laziness
357 my %contact_hash = ( 'first' => $self->first,
358 'last' => $self->get('last'),
359 'custnum' => $new_custnum,
363 my $contact = qsearchs( 'contact', \%contact_hash)
364 || new FS::contact \%contact_hash;
365 unless ( $contact->contactnum ) {
366 my $error = $contact->insert;
368 $dbh->rollback if $oldAutoCommit;
373 foreach my $cust_pkg ( $self->ncancelled_pkgs ) {
375 my $cust_location = $cust_pkg->cust_location || $self->ship_location;
376 my %loc_hash = $cust_location->hash;
377 $loc_hash{'locationnum'} = '';
378 $loc_hash{'custnum'} = $new_custnum;
379 $loc_hash{'disabled'} = '';
380 my $new_cust_location = qsearchs( 'cust_location', \%loc_hash)
381 || new FS::cust_location \%loc_hash;
383 my $pkg_or_error = $cust_pkg->change( {
385 'cust_main' => $new_cust_main,
386 'contactnum' => $contact->contactnum,
387 'cust_location' => $new_cust_location,
390 my $error = ref($pkg_or_error) ? '' : $pkg_or_error;
393 $dbh->rollback if $oldAutoCommit;
399 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
404 =item all_pkgs [ OPTION => VALUE... | EXTRA_QSEARCH_PARAMS_HASHREF ]
406 Returns all packages (see L<FS::cust_pkg>) for this customer.
412 my $extra_qsearch = ref($_[0]) ? shift : { @_ };
414 return $self->num_pkgs unless wantarray || keys %$extra_qsearch;
417 if ( $self->{'_pkgnum'} && ! keys %$extra_qsearch ) {
418 @cust_pkg = values %{ $self->{'_pkgnum'}->cache };
420 @cust_pkg = $self->_cust_pkg($extra_qsearch);
423 local($skip_label_sort) = 1 if $extra_qsearch->{skip_label_sort};
424 map { $_ } sort sort_packages @cust_pkg;
430 Synonym for B<all_pkgs>.
438 =item ncancelled_pkgs [ EXTRA_QSEARCH_PARAMS_HASHREF ]
440 Returns all non-cancelled packages (see L<FS::cust_pkg>) for this customer.
444 sub ncancelled_pkgs {
446 my $extra_qsearch = ref($_[0]) ? shift : {};
448 local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
450 return $self->num_ncancelled_pkgs unless wantarray;
453 if ( $self->{'_pkgnum'} ) {
455 warn "$me ncancelled_pkgs: returning cached objects"
458 @cust_pkg = grep { ! $_->getfield('cancel') }
459 values %{ $self->{'_pkgnum'}->cache };
463 warn "$me ncancelled_pkgs: searching for packages with custnum ".
467 $extra_qsearch->{'extra_sql'} .= ' AND ( cancel IS NULL OR cancel = 0 ) ';
469 @cust_pkg = $self->_cust_pkg($extra_qsearch);
473 local($skip_label_sort) = 1 if $extra_qsearch->{skip_label_sort};
474 sort sort_packages @cust_pkg;
478 =item cancelled_pkgs [ EXTRA_QSEARCH_PARAMS_HASHREF ]
480 Returns all cancelled packages (see L<FS::cust_pkg>) for this customer.
486 my $extra_qsearch = ref($_[0]) ? shift : { @_ };
488 return $self->num_cancelled_pkgs($extra_qsearch) unless wantarray;
490 $extra_qsearch->{'extra_sql'} .=
491 ' AND cust_pkg.cancel IS NOT NULL AND cust_pkg.cancel > 0 ';
493 local($skip_label_sort) = 1 if $extra_qsearch->{skip_label_sort};
495 sort sort_packages $self->_cust_pkg($extra_qsearch);
500 my $extra_qsearch = ref($_[0]) ? shift : {};
502 $extra_qsearch->{'select'} ||= '*';
503 $extra_qsearch->{'select'} .=
504 ',( SELECT COUNT(*) FROM cust_svc WHERE cust_pkg.pkgnum = cust_svc.pkgnum )
508 $_->{'_num_cust_svc'} = $_->get('_num_cust_svc');
513 'table' => 'cust_pkg',
514 'hashref' => { 'custnum' => $self->custnum },
519 # This should be generalized to use config options to determine order.
522 my $locationsort = ( $a->locationnum || 0 ) <=> ( $b->locationnum || 0 );
523 return $locationsort if $locationsort;
525 if ( $a->get('cancel') xor $b->get('cancel') ) {
526 return -1 if $b->get('cancel');
527 return 1 if $a->get('cancel');
528 #shouldn't get here...
531 my $a_num_cust_svc = $a->num_cust_svc;
532 my $b_num_cust_svc = $b->num_cust_svc;
533 return 0 if !$a_num_cust_svc && !$b_num_cust_svc;
534 return -1 if $a_num_cust_svc && !$b_num_cust_svc;
535 return 1 if !$a_num_cust_svc && $b_num_cust_svc;
536 return 0 if $skip_label_sort
537 || $a_num_cust_svc + $b_num_cust_svc > 20; #for perf, just give up
538 my @a_cust_svc = $a->cust_svc_unsorted;
539 my @b_cust_svc = $b->cust_svc_unsorted;
540 return 0 if !scalar(@a_cust_svc) && !scalar(@b_cust_svc);
541 return -1 if scalar(@a_cust_svc) && !scalar(@b_cust_svc);
542 return 1 if !scalar(@a_cust_svc) && scalar(@b_cust_svc);
543 $a_cust_svc[0]->svc_x->label cmp $b_cust_svc[0]->svc_x->label;
550 Returns all suspended packages (see L<FS::cust_pkg>) for this customer.
556 return $self->num_suspended_pkgs unless wantarray;
557 grep { $_->susp } $self->ncancelled_pkgs;
560 ### This appears to be unused, will be going away
562 #=item unflagged_suspended_pkgs
564 #Returns all unflagged suspended packages (see L<FS::cust_pkg>) for this
565 #customer (thouse packages without the `manual_flag' set).
569 sub unflagged_suspended_pkgs {
571 return $self->suspended_pkgs
572 unless dbdef->table('cust_pkg')->column('manual_flag');
573 grep { ! $_->manual_flag } $self->suspended_pkgs;
576 =item unsuspended_pkgs
578 Returns all unsuspended (and uncancelled) packages (see L<FS::cust_pkg>) for
583 sub unsuspended_pkgs {
585 return $self->num_unsuspended_pkgs unless wantarray;
586 grep { ! $_->susp } $self->ncancelled_pkgs;
591 Returns all unsuspended (and uncancelled) packages (see L<FS::cust_pkg>) for
592 this customer that are active (recurring).
596 #recurring_pkgs? different from cust_pkg idea of "active" which has
597 # a setup vs not_yet_billed which doesn't
600 grep { my $part_pkg = $_->part_pkg;
601 $part_pkg->freq ne '' && $part_pkg->freq ne '0';
603 $self->unsuspended_pkgs;
606 =item ncancelled_active_pkgs
608 Returns all non-cancelled packages (see L<FS::cust_pkg>) for this customer that
609 are active (recurring).
613 #ncancelled_recurring_pkgs? different from cust_pkg idea of "active" which has
614 # a setup vs not_yet_billed which doesn't
615 sub ncancelled_active_pkgs {
617 grep { my $part_pkg = $_->part_pkg;
618 $part_pkg->freq ne '' && $part_pkg->freq ne '0';
620 $self->ncancelled_pkgs;
625 Returns active packages, and also any suspended packages which are set to
626 continue billing while suspended.
632 grep { my $part_pkg = $_->part_pkg;
633 $part_pkg->freq ne '' && $part_pkg->freq ne '0'
634 && ( ! $_->susp || $_->option('suspend_bill',1)
635 || ( $part_pkg->option('suspend_bill', 1)
636 && ! $_->option('no_suspend_bill',1)
640 $self->ncancelled_pkgs;
645 Returns the next date this customer will be billed, as a UNIX timestamp, or
646 undef if no billing package has a next bill date.
652 min( map $_->get('bill'), grep $_->get('bill'), $self->billing_pkgs );
655 =item num_cancelled_pkgs
657 Returns the number of cancelled packages (see L<FS::cust_pkg>) for this
662 sub num_cancelled_pkgs {
663 shift->num_pkgs("cust_pkg.cancel IS NOT NULL AND cust_pkg.cancel != 0");
666 =item num_ncancelled_pkgs
668 Returns the number of packages that have not been cancelled (see L<FS::cust_pkg>) for this
673 sub num_ncancelled_pkgs {
674 shift->num_pkgs("( cust_pkg.cancel IS NULL OR cust_pkg.cancel = 0 )");
677 =item num_billing_pkgs
679 Returns the number of packages that have not been cancelled
680 and have a non-zero billing frequency (see L<FS::cust_pkg>)
685 sub num_billing_pkgs {
687 my $opt = shift || {};
688 $opt->{addl_from} .= ' LEFT JOIN part_pkg USING (pkgpart)';
689 $opt->{extra_sql} .= ' AND ' if $opt->{extra_sql};
690 $opt->{extra_sql} .= "freq IS NOT NULL AND freq != '0'";
691 $self->num_ncancelled_pkgs($opt);
694 sub num_suspended_pkgs {
695 shift->num_pkgs(" ( cust_pkg.cancel IS NULL OR cust_pkg.cancel = 0 )
696 AND cust_pkg.susp IS NOT NULL AND cust_pkg.susp != 0 ");
699 sub num_unsuspended_pkgs {
700 shift->num_pkgs(" ( cust_pkg.cancel IS NULL OR cust_pkg.cancel = 0 )
701 AND ( cust_pkg.susp IS NULL OR cust_pkg.susp = 0 ) ");
706 my $sql = scalar(@_) ? shift : '';
707 $sql = "AND $sql" if $sql && $sql !~ /^\s*$/ && $sql !~ /^\s*AND/i;
708 my $sth = dbh->prepare(
709 "SELECT COUNT(*) FROM cust_pkg WHERE custnum = ? $sql"
710 ) or die dbh->errstr;
711 $sth->execute($self->custnum) or die $sth->errstr;
712 $sth->fetchrow_arrayref->[0];
717 Returns the number of packages for this customer that have services that
718 can have RADIUS usage statistics.
724 # have to enumerate exportnums but it's not bad
725 my @exportnums = map { $_->exportnum }
726 grep { $_->can('usage_sessions') }
727 qsearch('part_export');
728 return 0 if !@exportnums;
729 my $in_exportnums = join(',', @exportnums);
730 my $sql = "SELECT COUNT(DISTINCT pkgnum) FROM cust_pkg
731 JOIN cust_svc USING (pkgnum)
732 JOIN export_svc USING (svcpart)
733 WHERE exportnum IN( $in_exportnums ) AND custnum = ?";
734 FS::Record->scalar_sql($sql, $self->custnum);
737 =item display_recurring
739 Returns an array of hash references, one for each recurring freq
740 on billable customer packages, with keys of freq, freq_pretty and amount
741 (the amount that this customer will next be charged at the given frequency.)
743 Results will be numerically sorted by freq.
745 Only intended for display purposes, not used for actual billing.
749 sub display_recurring {
750 my $cust_main = shift;
752 my $sth = dbh->prepare("
753 SELECT DISTINCT freq FROM cust_pkg LEFT JOIN part_pkg USING (pkgpart)
754 WHERE freq IS NOT NULL AND freq != '0'
755 AND ( cancel IS NULL OR cancel = 0 )
757 ") or die $DBI::errstr;
759 $sth->execute($cust_main->custnum) or die $sth->errstr;
761 #not really a numeric sort because freqs can actually be all sorts of things
762 # but good enough for the 99% cases of ordering monthly quarterly annually
763 my @freqs = sort { $a <=> $b } map { $_->[0] } @{ $sth->fetchall_arrayref };
769 foreach my $freq (@freqs) {
771 my @cust_pkg = qsearch({
772 'table' => 'cust_pkg',
773 'addl_from' => 'LEFT JOIN part_pkg USING (pkgpart)',
774 'hashref' => { 'custnum' => $cust_main->custnum, },
775 'extra_sql' => 'AND ( cancel IS NULL OR cancel = 0 )
776 AND freq = '. dbh->quote($freq),
777 'order_by' => 'ORDER BY COALESCE(start_date,0), pkgnum', # to ensure old pkgs come before change_to_pkg
780 my $freq_pretty = $cust_pkg[0]->part_pkg->freq_pretty;
784 foreach my $cust_pkg (@cust_pkg) {
785 my $part_pkg = $cust_pkg->part_pkg;
786 next if $cust_pkg->susp
787 && ! $cust_pkg->option('suspend_bill')
788 && ( ! $part_pkg->option('suspend_bill')
789 || $cust_pkg->option('no_suspend_bill')
793 next if $skip_pkg->{$cust_pkg->pkgnum};
794 if ($cust_pkg->change_to_pkgnum) {
795 #if change is on or before next bill date, use new pkg
796 next if $cust_pkg->expire <= $cust_pkg->bill;
797 #if change is after next bill date, use old (this) pkg
798 $skip_pkg->{$cust_pkg->change_to_pkgnum} = 1;
803 #add recurring amounts for this package and its billing add-ons
804 foreach my $l_part_pkg ( $part_pkg->self_and_bill_linked ) {
805 $pkg_amount += $l_part_pkg->base_recur($cust_pkg);
808 #subtract amounts for any active discounts
809 #(there should only be one at the moment, otherwise this makes no sense)
810 foreach my $cust_pkg_discount ( $cust_pkg->cust_pkg_discount_active ) {
811 my $discount = $cust_pkg_discount->discount;
812 #and only one of these for each
813 $pkg_amount -= $discount->amount;
814 $pkg_amount -= $pkg_amount * $discount->percent/100;
817 $pkg_amount *= ( $cust_pkg->quantity || 1 );
819 $amount += $pkg_amount;
826 'freq_pretty' => $freq_pretty,
841 L<FS::cust_main>, L<FS::cust_pkg>