1 package FS::detail_format;
7 use FS::cust_bill_pkg_detail;
12 my $me = '[FS::detail_format]';
16 FS::detail_format - invoice detail formatter
20 An FS::detail_format object is a converter to create invoice details
21 (L<FS::cust_bill_pkg_detail>) from call detail records (L<FS::cdr>)
22 or other usage information. FS::detail_format inherits from nothing.
24 Subclasses of FS::detail_format represent specific detail formats.
30 =item new FORMAT, OPTIONS
32 Returns a new detail formatter. The FORMAT argument is the name of
37 - buffer: an arrayref to store details into. This may avoid the need for a
38 large copy operation at the end of processing. However, since summary formats
39 will produce nothing until the end of processing, C<finish> must be called
40 after all CDRs have been appended.
42 - inbound: a flag telling the formatter to format CDRs for display to the
43 receiving party, rather than the originator. In this case, the
44 L<FS::cdr_termination> object will be fetched and its values used for
45 rated_price, rated_seconds, rated_minutes, and svcnum. This can be changed
46 with the C<inbound> method.
48 - locale: a locale string to use for static text and date formats. This is
55 if ( $class eq 'FS::detail_format' ) {
57 or die "$me format name required";
58 $class = "FS::detail_format::$format"
59 unless $format =~ /^FS::detail_format::/;
62 die "$me error loading $class: $@" if $@;
65 my $locale = $opt{'locale'} || '';
66 my $conf = FS::Conf->new({ locale => $locale });
67 $locale ||= $conf->config('locale') || 'en_US';
69 my %locale_info = FS::Locales->locale_info($locale);
70 my $language_name = $locale_info{'name'};
72 my $self = { conf => FS::Conf->new({ locale => $locale }),
73 csv => Text::CSV_XS->new({ binary => 1 }),
74 inbound => ($opt{'inbound'} ? 1 : 0),
75 buffer => ($opt{'buffer'} || []),
76 _lh => FS::L10N->get_handle($locale),
77 _dh => eval { Date::Language->new($language_name) } ||
91 Set/get the 'inbound' flag.
97 $self->{inbound} = ($_[0] > 0) if (@_);
103 Set/get the locally meaningful phone number. This is used to tag call details
104 for presentation on certain kinds of invoices.
110 $self->{phonenum} = shift if @_;
116 Takes any number of call detail records (as L<FS::cdr> objects),
117 formats them, and appends them to the internal buffer.
119 By default, this simply calls C<single_detail> on each CDR in the
120 set. Subclasses should override C<append> and maybe C<finish> if
121 they do not produce detail lines from CDRs in a 1:1 fashion.
123 The 'billpkgnum', 'invnum', 'pkgnum', and 'phonenum' fields will
131 push @{ $self->{buffer} }, $self->single_detail($_);
137 Returns all invoice detail records in the buffer. This will perform
138 a C<finish> first. Subclasses generally shouldn't override this.
150 Ensures that all invoice details are generated given the CDRs that
151 have been appended. By default, this does nothing.
159 Returns a header row for the format, as an L<FS::cust_bill_pkg_detail>
160 object. By default this has 'format' = 'C', 'detail' = the value
161 returned by C<header_detail>, and all other fields empty.
163 This is called after C<finish>, so it can use information from the CDRs.
170 FS::cust_bill_pkg_detail->new(
171 { 'format' => 'C', 'detail' => $self->header_detail }
175 =item single_detail CDR
177 Takes a single CDR and returns an invoice detail to describe it.
179 By default, this maps the following fields from the CDR:
182 rated_price => amount
183 rated_classnum => classnum
184 rated_seconds => duration
185 rated_regionname => regionname
186 accountcode => accountcode
187 startdate => startdate
189 If the formatter is in inbound mode, it will look up a C<cdr_termination>
190 record and use rated_price and rated_seconds from that, and acctid will be
191 set to null to avoid linking the CDR to the detail record for the inbound
194 'phonenum' is set to the internal C<phonenum> value set on the formatter
197 It then calls C<columns> on the CDR to obtain a list of detail
198 columns, formats them as a CSV string, and stores that in the
207 my @columns = $self->columns($cdr);
208 my $status = $self->csv->combine(@columns);
209 die "$me error combining ".$self->csv->error_input."\n"
212 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
213 my $price = $object->rated_price if $object;
214 $price = 0 if $cdr->freesidestatus eq 'no-charge';
216 FS::cust_bill_pkg_detail->new( {
217 'acctid' => ($self->{inbound} ? '' : $cdr->acctid),
219 'classnum' => $cdr->rated_classnum,
220 'duration' => $object->rated_seconds,
221 'regionname' => $cdr->rated_regionname,
222 'accountcode' => $cdr->accountcode,
223 'startdate' => $cdr->startdate,
225 'detail' => $self->csv->string,
226 'phonenum' => $self->phonenum,
232 Returns a list of CSV columns (to be shown on the invoice) for
233 the CDR. This is the method most subclasses should override.
239 die "$me no columns method in ".ref($self);
244 Returns the 'detail' field for the header row. This should
245 probably be a CSV string of column headers for the values returned
252 die "$me no header_detail method in ".ref($self);
255 # convenience methods for subclasses
257 sub conf { $_[0]->{conf} }
259 sub csv { $_[0]->{csv} }
263 $self->{date_format} ||= ($self->conf->config('date_format') || '%m/%d/%Y');
268 $self->{money_char} ||= ($self->conf->config('money_char') || '$');
271 # localization methods
275 $self->{_dh}->time2str(@_);
278 # header strings are now localized in FS::TemplateItem_Mixin::detail
280 #imitate previous behavior for now
285 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
286 my $sec = $object->rated_seconds if $object;
288 # termination objects now have rated_granularity.
289 if ( $object->rated_granularity eq '0' ) {
292 elsif ( $object->rated_granularity eq '60' ) {
293 sprintf('%dm', ($sec + 59)/60);
296 sprintf('%dm %ds', $sec / 60, $sec % 60);
303 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
304 my $price = $object->rated_price if $object;
305 $price = '0.00' if $object->freesidestatus eq 'no-charge';
306 length($price) ? $self->money_char . $price : '';