Difference between revisions of "Freeside:3:Documentation:Developer/FS/Report/Table"
From Freeside
m (Edit via perl MediaWiki framework (1.13)) |
m (Edit via perl MediaWiki framework (1.13)) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 12: | Line 12: | ||
This returns a scalar value for foo, over the period from $startdate to $enddate, limited to agent $agentnum, subject to options in %opt. | This returns a scalar value for foo, over the period from $startdate to $enddate, limited to agent $agentnum, subject to options in %opt. | ||
| − | ; signups: The number of customers signed up. Options are | + | ; signups: The number of customers signed up. Options are: |
| + | :- cust_classnum: limit to this customer class - pkg_classnum: limit to customers with a package of this class. If this is an arrayref, it's an ANY match. - refnum: limit to this advertising source - indirect: boolean; limit to customers that have a referral_custnum that matches the advertising source | ||
| + | ; invoiced: The total amount charged on all invoices.; netsales: invoiced - netcredits; cashflow: payments - refunds; netcashflow: payments - netrefunds; payments: The sum of payments received in the period.; credits: The sum of credits issued in the period.; refunds: The sum of refunds paid in the period.; netcredits: The sum of credit applications to invoices in the period.; receipts: The sum of payment applications to invoices in the period.; netrefunds: The sum of refund applications to credits in the period.; discounted: The sum of discounts on invoices in the period.; gross: invoiced + discounted; cust_pkg_setup_cost: The total setup costs of packages setup in the period | ||
:'classnum': limit to this package class. | :'classnum': limit to this package class. | ||
; cust_pkg_recur_cust: the total recur costs of packages in the period | ; cust_pkg_recur_cust: the total recur costs of packages in the period | ||
:'classnum': limit to this package class. | :'classnum': limit to this package class. | ||
; cust_bill_pkg: the total package charges on invoice line items. | ; cust_bill_pkg: the total package charges on invoice line items. | ||
| − | :'charges': limit the type of charges included (setup, recur, usage). Should be a string containing one or more of 'S', 'R', or 'U'; | + | :'charges': limit the type of charges included (setup, recur, usage, discount, taxes). Should be a string containing one or more of 'S', 'R', or 'U'; or 'D' or 'T' (discount and taxes should not be combined with the others.) If unspecified, defaults to 'SRU'. |
:'classnum': limit to this package class. | :'classnum': limit to this package class. | ||
| Line 23: | Line 25: | ||
:'use_override': for line items generated by an add-on package, use the class of the add-on rather than the base package. | :'use_override': for line items generated by an add-on package, use the class of the add-on rather than the base package. | ||
| − | :' | + | :'average_per_cust_pkg': divide the result by the number of distinct packages. |
:'distribute': for non-monthly recurring charges, ignore the invoice date. Instead, consider the line item's starting/ending dates. Determine the fraction of the line item duration that falls within the specified interval and return that fraction of the recurring charges. This is somewhat experimental. | :'distribute': for non-monthly recurring charges, ignore the invoice date. Instead, consider the line item's starting/ending dates. Determine the fraction of the line item duration that falls within the specified interval and return that fraction of the recurring charges. This is somewhat experimental. | ||
| Line 32: | Line 34: | ||
:'usageclass': limit to this usage class number. | :'usageclass': limit to this usage class number. | ||
| + | ; active_pkg: The number of packages that were active at the start of the period. The end date of the period is ignored. Options: | ||
| + | :- refnum: Limit to customers with this advertising source. - classnum: Limit to packages with this class. - towernum: Limit to packages that have a broadband service with this tower. - zip: Limit to packages with this service location zip code. | ||
| + | :Except for zip, any of these can be an arrayref to allow multiple values for the field. | ||
| + | ; setup_pkg: The number of packages with setup dates in the period. This excludes packages created by package changes. Options are as for active_pkg.; susp_pkg: The number of packages that were suspended in the period (and not canceled). Options are as for active_pkg.; unsusp_pkg: The number of packages that were unsuspended in the period. Options are as for active_pkg.; cancel_pkg: The number of packages with cancel dates in the period. Excludes packages that were canceled to be changed to a new package. Options are as for active_pkg.; active_cust: The number of customers who had any active recurring packages at the start of the period. The end date is ignored, agentnum is mandatory, and no other parameters are accepted.; started_cust: The number of customers who had no active packages at the start of the period, but had active packages at the end. Like active_cust, agentnum is mandatory and no other parameters are accepted.; suspended_cust: The number of customers who had active packages at the start of the period, and at the end had no active packages but some suspended packages. Note that this does not necessarily mean that their packages were suspended during the period.; resumed_cust: The inverse of suspended_cust: the number of customers who had suspended packages and no active packages at the start of the period, and active packages at the end.; cancelled_cust: The number of customers who had active packages at the start of the period, and only cancelled packages at the end. | ||
==METHODS== | ==METHODS== | ||
; init_projection | ; init_projection | ||
| Line 38: | Line 44: | ||
; extend_projection START END | ; extend_projection START END | ||
:Generates data for the next period of projection. This will be called for sequential periods where the END of one equals the START of the next (with no gaps). | :Generates data for the next period of projection. This will be called for sequential periods where the END of one equals the START of the next (with no gaps). | ||
| + | ; _init_tower_pkg_cache | ||
| + | :Internal method: creates a temporary table relating pkgnums to towernums. A (pkgnum, towernum) record indicates that this package once had a svc_broadband service which, as of its last insert or replace_new history record, had a sectornum associated with that towernum. | ||
| + | |||
| + | :This is expensive, so it won't be done more than once an hour. Historical data about package churn shouldn't be changing in realtime anyway. | ||
==BUGS== | ==BUGS== | ||
| Line 48: | Line 58: | ||
Hey! '''The above document had some coding errors, which are explained below:''' | Hey! '''The above document had some coding errors, which are explained below:''' | ||
| − | ; Around line | + | ; Around line 1342: |
:You forgot a '=back' before '=head1' | :You forgot a '=back' before '=head1' | ||
Latest revision as of 06:33, 28 September 2015
NAME
FS::Report::Table - Tables of report data
SYNOPSIS
See the more specific report objects, currently only FS::Report::Table::Monthly and FS::Report::Table::Daily.
OBSERVABLES
The common interface for an observable named 'foo' is:
$report->foo($startdate, $enddate, $agentnum, %options)
This returns a scalar value for foo, over the period from $startdate to $enddate, limited to agent $agentnum, subject to options in %opt.
- signups: The number of customers signed up. Options are:
- - cust_classnum: limit to this customer class - pkg_classnum: limit to customers with a package of this class. If this is an arrayref, it's an ANY match. - refnum: limit to this advertising source - indirect: boolean; limit to customers that have a referral_custnum that matches the advertising source
- invoiced: The total amount charged on all invoices.; netsales: invoiced - netcredits; cashflow: payments - refunds; netcashflow: payments - netrefunds; payments: The sum of payments received in the period.; credits: The sum of credits issued in the period.; refunds: The sum of refunds paid in the period.; netcredits: The sum of credit applications to invoices in the period.; receipts: The sum of payment applications to invoices in the period.; netrefunds: The sum of refund applications to credits in the period.; discounted: The sum of discounts on invoices in the period.; gross: invoiced + discounted; cust_pkg_setup_cost: The total setup costs of packages setup in the period
- 'classnum': limit to this package class.
- cust_pkg_recur_cust: the total recur costs of packages in the period
- 'classnum': limit to this package class.
- cust_bill_pkg: the total package charges on invoice line items.
- 'charges': limit the type of charges included (setup, recur, usage, discount, taxes). Should be a string containing one or more of 'S', 'R', or 'U'; or 'D' or 'T' (discount and taxes should not be combined with the others.) If unspecified, defaults to 'SRU'.
- 'classnum': limit to this package class.
- 'use_override': for line items generated by an add-on package, use the class of the add-on rather than the base package.
- 'average_per_cust_pkg': divide the result by the number of distinct packages.
- 'distribute': for non-monthly recurring charges, ignore the invoice date. Instead, consider the line item's starting/ending dates. Determine the fraction of the line item duration that falls within the specified interval and return that fraction of the recurring charges. This is somewhat experimental.
- 'project': enable if this is a projected period. This is very experimental.
- cust_bill_pkg_detail: the total usage charges in detail lines.
- Arguments as for cust_bill_pkg, plus:
- 'usageclass': limit to this usage class number.
- active_pkg: The number of packages that were active at the start of the period. The end date of the period is ignored. Options:
- - refnum: Limit to customers with this advertising source. - classnum: Limit to packages with this class. - towernum: Limit to packages that have a broadband service with this tower. - zip: Limit to packages with this service location zip code.
- Except for zip, any of these can be an arrayref to allow multiple values for the field.
- setup_pkg: The number of packages with setup dates in the period. This excludes packages created by package changes. Options are as for active_pkg.; susp_pkg: The number of packages that were suspended in the period (and not canceled). Options are as for active_pkg.; unsusp_pkg: The number of packages that were unsuspended in the period. Options are as for active_pkg.; cancel_pkg: The number of packages with cancel dates in the period. Excludes packages that were canceled to be changed to a new package. Options are as for active_pkg.; active_cust: The number of customers who had any active recurring packages at the start of the period. The end date is ignored, agentnum is mandatory, and no other parameters are accepted.; started_cust: The number of customers who had no active packages at the start of the period, but had active packages at the end. Like active_cust, agentnum is mandatory and no other parameters are accepted.; suspended_cust: The number of customers who had active packages at the start of the period, and at the end had no active packages but some suspended packages. Note that this does not necessarily mean that their packages were suspended during the period.; resumed_cust: The inverse of suspended_cust: the number of customers who had suspended packages and no active packages at the start of the period, and active packages at the end.; cancelled_cust: The number of customers who had active packages at the start of the period, and only cancelled packages at the end.
METHODS
- init_projection
- Sets up for future projection of all observables on the report. Currently this is limited to 'cust_bill_pkg'.
- extend_projection START END
- Generates data for the next period of projection. This will be called for sequential periods where the END of one equals the START of the next (with no gaps).
- _init_tower_pkg_cache
- Internal method: creates a temporary table relating pkgnums to towernums. A (pkgnum, towernum) record indicates that this package once had a svc_broadband service which, as of its last insert or replace_new history record, had a sectornum associated with that towernum.
- This is expensive, so it won't be done more than once an hour. Historical data about package churn shouldn't be changing in realtime anyway.
BUGS
Documentation.
SEE ALSO
FS::Report::Table::Monthly, reports in the web interface.
POD ERRORS
Hey! The above document had some coding errors, which are explained below:
- Around line 1342:
- You forgot a '=back' before '=head1'
