Difference between revisions of "Freeside:3:Documentation:Developer/FS/detail format"

Revision as of 07:40, 24 March 2015

NAME

FS::detail_format - invoice detail formatter

DESCRIPTION

An FS::detail_format object is a converter to create invoice details (FS::cust_bill_pkg_detail) from call detail records (FS::cdr) or other usage information. FS::detail_format inherits from nothing.

Subclasses of FS::detail_format represent specific detail formats.

CLASS METHODS

new FORMAT, OPTIONS

Returns a new detail formatter. The FORMAT argument is the name of a subclass.

OPTIONS may contain:

- buffer: an arrayref to store details into. This may avoid the need for a large copy operation at the end of processing. However, since summary formats will produce nothing until the end of processing, finish must be called after all CDRs have been appended.

- inbound: a flag telling the formatter to format CDRs for display to the receiving party, rather than the originator. In this case, the FS::cdr_termination object will be fetched and its values used for rated_price, rated_seconds, rated_minutes, and svcnum. This can be changed with the inbound method.

- locale: a locale string to use for static text and date formats. This is optional.

METHODS

inbound VALUE

Set/get the 'inbound' flag.

phonenum VALUE

Set/get the locally meaningful phone number. This is used to tag call details for presentation on certain kinds of invoices.

append CDRS

Takes any number of call detail records (as FS::cdr objects), formats them, and appends them to the internal buffer.

By default, this simply calls single_detail on each CDR in the set. Subclasses should override append and maybe finish if they do not produce detail lines from CDRs in a 1:1 fashion.

The 'billpkgnum', 'invnum', 'pkgnum', and 'phonenum' fields will be set later.

details

Returns all invoice detail records in the buffer. This will perform a finish first. Subclasses generally shouldn't override this.

finish

Ensures that all invoice details are generated given the CDRs that have been appended. By default, this does nothing.

header

Returns a header row for the format, as an FS::cust_bill_pkg_detail object. By default this has 'format' = 'C', 'detail' = the value returned by header_detail, and all other fields empty.

This is called after finish, so it can use information from the CDRs.

single_detail CDR

Takes a single CDR and returns an invoice detail to describe it.

By default, this maps the following fields from the CDR:

rated_price => amount rated_classnum => classnum rated_seconds => duration rated_regionname => regionname accountcode => accountcode startdate => startdate

'phonenum' is set to the internal phonenum value set on the formatter object.

It then calls columns on the CDR to obtain a list of detail columns, formats them as a CSV string, and stores that in the 'detail' field.

columns CDR

Returns a list of CSV columns (to be shown on the invoice) for the CDR. This is the method most subclasses should override.

header_detail

Returns the 'detail' field for the header row. This should probably be a CSV string of column headers for the values returned by columns.