View source for Freeside:4:Documentation:Developer/FS/cdr

==NAME==
FS::cdr - Object methods for cdr records

==SYNOPSIS==
<code>
  use FS::cdr;
 
  $record = new FS::cdr \%hash;
  $record = new FS::cdr { 'column' => 'value' };
 
  $error = $record->insert;
 
  $error = $new_record->replace($old_record);
 
  $error = $record->delete;
 
  $error = $record->check;
</code>
==DESCRIPTION==
An FS::cdr object represents an Call Data Record, typically from a telephony system or provider of some sort. FS::cdr inherits from FS::Record. The following fields are currently supported:

; acctid - primary key; calldate - Call timestamp (SQL timestamp); clid - Caller*ID with text; src - Caller*ID number / Source number; dst - Destination extension; dcontext - Destination context; channel - Channel used; dstchannel - Destination channel if appropriate; lastapp - Last application if appropriate; lastdata - Last application data; src_ip_addr - Source IP address (dotted quad, zero-filled); dst_ip_addr - Destination IP address (same); dst_term - Terminating destination number (if different from dst); startdate - Start of call (UNIX-style integer timestamp); answerdate - Answer time of call (UNIX-style integer timestamp); enddate - End time of call (UNIX-style integer timestamp); duration - Total time in system, in seconds; billsec - Total time call is up, in seconds; disposition - What happened to the call&#58; ANSWERED, NO ANSWER, BUSY; amaflags - What flags to use&#58; BILL, IGNORE etc, specified on a per channel basis like accountcode.; accountcode - CDR account number to use&#58; account; uniqueid - Unique channel identifier (Unitel/RSLCOM Event ID); userfield - CDR user-defined field; cdr_type - CDR type - see [[Freeside:4:Documentation:Developer/FS/cdr type|FS::cdr_type]] (Usage = 1, S&E = 7, OC&C = 8); charged_party - Service number to be billed; upstream_currency - Wholesale currency from upstream; upstream_price - Wholesale price from upstream; upstream_rateplanid - Upstream rate plan ID; rated_price - Rated (or re-rated) price; distance - km (need units field?); islocal - Local - 1, Non Local = 0; calltypenum - Type of call - see [[Freeside:4:Documentation:Developer/FS/cdr calltype|FS::cdr_calltype]]; description - Description (cdr_type 7&8 only) (used for cust_bill_pkg.itemdesc); quantity - Number of items (cdr_type 7&8 only); carrierid - Upstream Carrier ID (see [[Freeside:4:Documentation:Developer/FS/cdr carrier|FS::cdr_carrier]]); upstream_rateid - Upstream Rate ID; svcnum - Link to customer service (see [[Freeside:4:Documentation:Developer/FS/cust svc|FS::cust_svc]]); freesidestatus - NULL, processing-tiered, rated, done, skipped, no-charge, failed; freesiderewritestatus - NULL, done, skipped; cdrbatch; detailnum - Link to invoice detail ([[Freeside:4:Documentation:Developer/FS/cust bill pkg detail|FS::cust_bill_pkg_detail]])
==METHODS==
; new HASHREF
:Creates a new CDR. To add the CDR to the database, see [[#insert|"insert"]].

:Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the ''hash'' method.
; insert
:Adds this record to the database. If there is an error, returns the error, otherwise returns false.
; delete
:Delete this record from the database.
; replace OLD_RECORD
:Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
; check
:Checks all fields to make sure this is a valid CDR. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

:Note: Unlike most types of records, we don't want to "reject" a CDR and we want to process them as quickly as possible, so we allow the database to check most of the data.
; is_tollfree [ COLUMN ]
:Returns true when the cdr represents a toll free number and false otherwise.

:By default, inspects the dst field, but an optional column name can be passed to inspect other field.
; set_charged_party
:If the charged_party field is already set, does nothing. Otherwise:

:If the cdr-charged_party-accountcode config option is enabled, sets the charged_party to the accountcode.

:Otherwise sets the charged_party normally: to the src field in most cases, or to the dst field if it is a toll free number.
; set_status STATUS
:Sets the status to the provided string. If there is an error, returns the error, otherwise returns false.

:If status is being changed from 'rated' to some other status, also removes any usage allocations to this CDR.
; set_status_and_rated_price STATUS RATED_PRICE [ SVCNUM [ OPTION => VALUE ... ] ]
:Sets the status and rated price.

:Available options are: inbound, rated_pretty_dst, rated_regionname, rated_seconds, rated_minutes, rated_granularity, rated_ratedetailnum, rated_classnum, rated_ratename.

:If there is an error, returns the error, otherwise returns false.
; parse_number [ OPTION => VALUE ... ]
:Returns two scalars, the countrycode and the rest of the number.

:Options are passed as name-value pairs. Currently available options are:
:; column
::The column containing the number to be parsed. Defaults to dst.
:; international_prefix
::The digits for international dialing. Defaults to '011' The value '+' is always recognized.
:; domestic_prefix
::The digits for domestic long distance dialing. Defaults to '1'
; rate [ OPTION => VALUE ... ]
:Rates this CDR according and sets the status to 'rated'.

:Available options are: part_pkg, svcnum, plan_included_min, detail_included_min_hashref.

:part_pkg is required.

:If svcnum is specified, will also associate this CDR with the specified svcnum.

:plan_included_min should be set to a scalar reference of the number of included minutes and will be decremented by the rated minutes of this CDR.

:detail_included_min_hashref should be set to an empty hashref at the start of a month's rating and then preserved across CDRs.
; rate_cost
:Rates an already-rated CDR according to the cost fields from the rate plan.

:Returns the amount.
; cdr_termination [ TERMPART ]; calldate_unix
:Parses the calldate in SQL string format and returns a UNIX timestamp.
; startdate_sql
:Parses the startdate in UNIX timestamp format and returns a string in SQL format.
; cdr_carrier
:Returns the FS::cdr_carrier object associated with this CDR, or false if no carrierid is defined.
; carriername
:Returns the carrier name (see [[Freeside:4:Documentation:Developer/FS/cdr carrier|FS::cdr_carrier]]), or the empty string if no FS::cdr_carrier object is assocated with this CDR.
; cdr_calltype
:Returns the FS::cdr_calltype object associated with this CDR, or false if no calltypenum is defined.
; calltypename
:Returns the call type name (see [[Freeside:4:Documentation:Developer/FS/cdr calltype|FS::cdr_calltype]]), or the empty string if no FS::cdr_calltype object is assocated with this CDR.
; downstream_csv [ OPTION => VALUE, ... ]; downstream_csv OPTION => VALUE ...
:Returns a string of formatted call details for display on an invoice.

:Options:

:format

:charge - override the 'rated_price' field of the CDR

:seconds - override the 'billsec' field of the CDR

:count - number of usage events included in this record, for summary formats

:ratename - name of the rate table used to rate this call

:granularity

==CLASS METHODS==
; invoice_formats
:Returns an ordered list of key value pairs containing invoice format names as keys (for use with part_pkg::voip_cdr) and "pretty" format names as values.
; invoice_header FORMAT
:Returns a scalar containing the CSV column header for invoice format FORMAT.
; clear_status
:Clears cdr and any associated cdr_termination statuses - used for CDR reprocessing.
; import_formats
:Returns an ordered list of key value pairs containing import format names as keys (for use with batch_import) and "pretty" format names as values.
; batch_import HASHREF
:Imports CDR records. Available options are:
:; file
::Filename
:; format:; params
::Hash reference of preset fields, typically cdrbatch
:; empty_ok
::Set true to prevent throwing an error on empty imports
; process_batch_import; ip_addr_sql FIELD RANGE
:Returns an SQL condition to search for CDRs with an IP address within RANGE. FIELD is either 'src_ip_addr' or 'dst_ip_addr'. RANGE should be in the form "a.b.c.d-e.f.g.h' (dotted quads), where any of the leftmost octets of the second address can be omitted if they're the same as the first address.

==BUGS==
==SEE ALSO==
[[Freeside:4:Documentation:Developer/FS/Record|FS::Record]], schema.html from the base documentation.