2021-2Q: [ACC] Voice Billing
A new feature that redesigns the flow of the Voice Billing / Call Detail Records processing has been added to the SIMPLer system.
Previous implementation of CDR processing ( described here: 2012-1Q: CDR Rating Tool ) has been utilizing the 'External Billing Records' as the way to record the voice call summary details under a customer subscription. Unfortunately there were a couple of shortcomings of this approach:
the actual calls data were only available on invoices, the invoice pdf pages listing the calls were created at the stage of rating CDR files and after that the only call details SIMPLer kept was the additional invoice pages
we could not display the call details in an easy way in SIMPLer GUI (nor in the End User Portal) as the actual calls were not stored in the database
no further processing of calls could be done at a later stage i.e. external tax calculators could not be used with voice calls - which was forcing a not cost-effective 'safe harbour' approach when calculating taxes in the US
Redesigned Voice Billing flow uses a dedicated Voice Calls table to store the voice calls and a 'Voice Calls' product to bill customers based on that table contents.
General Overview of day to day actions related to voice calls
Calls from processed CDR's will now appear under a dedicated 'Voice Calls' section at the bottom of the customer details page. By default only calls that were 'Not Used' on any invoices will be displayed. The operator can browse through pages of voice calls as well as use the 'Display' dropdown menu 'All' option to display all calls recorded for a particular customer.
1) Customer Account Setup for Voice: Subscriptions
'Not Used' Voice Calls from the above table will be used to calculate subscriptions based on 'Voice Calls' type products only. To invoice calls made by a customer it is important that a 'Voice Calls' product is added to the customer subscription. It is advised that a customer has only one 'Voice Calls' subscription added to his account.
2) Customer Account Setup for Voice: Voice Identifier
Processing CDR (Call Data Records) files from a Voice Service Provider is required to match each call to a customer account. The customer setup might differ depending on who the provider is, but typically the matching is done based on:
Nickname / InvoicingID - in such case nothing additional needs being set in SIMPLer
Voice Identifier - this custom field typically is filled with the customer phone number (this is used to filter out the CDR records) or an account reference from the Voice platform (if it is unique and not the same as a SIMPLer customer's Nickname or Invoicing ID). The 'Voice Identifier' can be set on a 'per customer' or 'per subscription' basis depending on preference
Note: This will be described in more detail below
Once an invoice with voice calls is created the Voice Calls section, associated and used to generate it, will appear under Invoice Details page.
Calls can be released upon crediting an invoice thus making them available for 're-invoicing'.
If one forgets to 'Release' the voice calls upon crediting invoice / creating a bad debt note these can always be released later for each credited / bad debt note invoice.
As mentioned above - only a 'Voice Calls' product-based subscriptions will pick up the Voice Calls for billing. It is crucial to ensure that a 'Voice Calls' Product Type is selected while setting up this product in the Products section of SIMPLer.
Note: Total amount of the voice calls that are available in the particular billing cycle will be added to the 'Voice Calls' product base price. There are two approaches with setting up these subscriptions:
use single product for both 'Voice Package' and 'Voice Calls' - the product type should be 'Voice Calls' and the the price of the product should be set to the package price
bill the 'Voice Calls' and the 'Voice Package' from separate products - the voice package product type should be 'Standard' and have a price set, while the voice calls product type should be 'Voice Calls' and have the price set to 0 (zero)
Voice CDR processing
It is highly recommended to make use of automated CDR processing. We acknowledge that it might be difficult to set up but Azotel engineers are happy to help. This is a once-off task and once set everything happens automatically going forward with no manual intervention required.
Therefore in the majority of cases the below section of this document can be omitted.
If an operator wishes to manually process the CDR files the below section covers the most important details.
The CDR Rating Tool enables the processing and importing of CDR records from external voice systems into SIMPLer. We strongly advise that the rated voice calls are used, i.e. have the rating implemented on the voice operator side, and import the already rated files into SIMPLer. CDR records can include taxes or be tax exempt as SIMPLer is able to calculate taxes on Voice calls.
The ability of presenting a flexible and fully customizable call details section at the end of an invoice is what makes the system unique and powerful.
The CDR Rating Tool works with CSV (comma separated values) files although it also supports files other than comma delimiters. The CSV file must have columns in following order:
Date/Time - Date/Time of the call . This value will not be used for the actual CDR processing. It will be used to sort the records and can be displayed as is on customer invoices in the section that lists all calls made by a customer in a particular period
Voice Identifier - (Mandatory Field) . This will be used to match the call record against an actual customer record in SIMPLer. Customers in SIMPLer must be assigned a Voice Identifier (or a set of space separated voice identifiers) in order to be included in the CDR rating process
Source Number - (Mandatory Field) Origination number of the call . A regular expression check can be set against the field
Destination Number - (Mandatory Field) Destination number of the call . A regular expression check can be set against the field
Region - Region of the call. Some operators may provide a call region, which is a name for the destination (i.e. Italy or Poland). A regular expression check can be set against the field
Call Duration - (Mandatory Field) Duration of the call. This will be available to use in Rating formulas
Pre-Rated Amount -(Mandatory Field) Pre-rated amount. In some cases the CDR's will already be rated. An operator can choose to re-rate them or keep the previous rates
Price per Unit - (Optional) can be used in the Amount / Units calculation formulas
Discount - (Optional) can be used in the Amount / Units calculation formulas
Total Hours - (Optional) can be used in the Amount / Units calculation formulas
Description - (Optional) will be recorded in the Voice Calls table if defined
Billable Number - (Optional) will be recorded in the Voice Calls table if defined
Example CDR File
01-Jan-21 8:34;467160000;467160000;0048696940200;Poland - Mobile;2;0,034
01-Jan-21 8:44;467160011;467160011;0044922974535;England - Mobile;1;0,09
01-Jan-21 8:45;467160000;467160000;33482849;Local Telco;3;0,051
01-Jan-21 8:46;467160099;467160099;17214433;Local Telco;1;0,0095
01-Jan-21 8:47;467160099;467160099;0048328376283;Poland - Landline;1;0,0095
The CDR rating tool is a manual interface to a rating engine that helps an operator process their CDR files and prepare them to upload figures into the SIMPLer billing system. It takes the input CSV file in the format described previously in this guide and rates each of its rows.
Rows are first matched against a customer account in SIMPLer using the Voice Identifier column of the CSV file.
Next if a customer account matching the CDR was found the system will search for a CDR processing rule that will match the CDR. If multiple rules match the longest, best matching rules will take precedence.
The uploaded CSV file may come in different formats hence there is a choice of 'Column Delimiter' used in a file.
The number of 'Fraction Digits' can be set prior to processing. This will be used to set the fraction digits to the recommended value when rounding. In some countries it is required to have 3 or more fraction digits in the result.
The 'CDR Rating tool' has five output modes:
HTML - used for debugging. It will display a summary processing page with two sections: Processing Errors and Rated Output where an operator can debug the errors and preview the total amounts rated (that will be available in the import subscriptions)
CSV Spreadsheet - this is SIMPLer's 'Import External Billing Records' tool compatible CSV output. It can be imported directly into SIMPLer without any changes required. It contains three columns: Invoicing ID, Total Amount, HTML (templated) output
XLS Spreadsheet - XLS output of rated content containing three columns: Invoicing ID, Total Amount, HTML (templated) output
Unprocessed Records - this option outputs a file that covers all the unprocessed rows in their original format. This allows easy re-processing after corrections such as adding missing Voice Identifiers to customer accounts
Process in Background & Email - this option will process the file and send a summary email that will have csv, xml, and unprocessed records files
'Import to Database' dropdown defines whether the calls from a file that is being processed should be imported to the Voice Calls table. Once selected calls will be automatically imported and no further action is required.
This is the final step of the import but we would advise that an operator verifies the file has been processed properly first (using any of the above outputs methods).
CDR Processing Rules setup
Before starting to process and rate the CDR's a set of processing rules must be setup. These rules will define all conditions required to process a single CDR entry. Click on the 'VOIP' tab followed by 'CDR Rating Engine' and 'Manage Processing Rules' links to access the management page.
Note: For 99% of cases the 'match all' rule presented on above screenshot will be more than sufficient to process calls from the CDR file. For anything more complex we would advise to contact Azotel and an engineer would be happy to assist.
The CDR processing rules are heavily based on concepts presented below - Azotel strongly suggests to scan through the documentation pages for these before implementing complex formulas:
the regular expressions concept - provides a flexible means for "matching" various strings of text, such as words, patterns of characters. For more information and detailed examples please refer to: http://en.wikipedia.org/wiki/Regular_expression
perl math - mathematical operators available in Perl. These will be used to create calculation formulas.
The following arithmetic operators are available:
Conditional execution can be defined using following statement:
(( CONDITION ) ? EXPRESSION_TO BE _EXECUTED_IF_MATCHED : EXPRESSION_TO BE _EXECUTED_IF_NOT_MATCHED )
Following logical operators are available:
In CDR Processing formulas an operator can use the following tokens that will be exchanged with the live content from CDR's:
%%DURATION%% - Duration of call as in CDR
%%AMOUNT%% - Prerated amount from CDR
%%AMOUNT%% * 1.3
In this case the rated amount will be equal to the prerated amount multiplied by 1.3
%%DURATION%% * 2.8
In this case the rated amount will be equal to the duration of call multiplied by 2.8
((( %%DURATION%% % 2) > 0) ? int( %%DURATION / 2 ) + 1 : int( %%DURATION / 2 ) ) * 0.2
In this case the rated amount will be equal to the duration rounded up to units of two multiplied by 0.2
Each of the rules consist of the following attributes:
Source Regexp - CDR records with source number matching this regular expression (and the two remaining regular expression rules) will be processed according to the current processing rule. If left blank the system will not process it and automatically assume it is a source match
Destination Regexp - CDR records with destination number matching this regular expression (and the two remaining regular expression rules) will be processed according to the current processing rule. If left blank the system will not process it and automatically assume it is a destination match
Region Regexp - CDR records with region number matching this regular expression (and the two remaining regular expression rules) will be processed according to the current processing rule. If left blank the system will not process it and automatically assume it is a region match
Label - defines a processed CDR group that in turn will be used by the templating system to generate Call Details summary stats for all rates that have the same label. The typical use would be to define a summary call region (eg. 'National - Landlines' or 'International - Ireland') that can be used in the Call Details for summary details of all calls made to that region
Package - defines a complete set of rates. The CDR record will be processed according to the customers Voice Package attribute set under the customer's account. Only CDR processing rules where Package attribute matches customers Voice Package field will be used to process the particular CDR record. Typical use would be to provide different rating schemes to customers depending on the deal an operator has with them
Formula - Perl Eval based formula that will be used to calculate the rate for the call
Units Formula - Perl Eval based formula that will be used to calculate the units for the call
Detailed - this flag defines an additional attribute with which a rated CDR record will be labeled. It can be used on the Voice Details template to produce 'detailed' CDR output for labeled records while leaving out ones that don't have that flag. Typical use would be to provide detailed output for 'International' calls while providing only a summary voice call details for 'national' calls.
The management pages enable operator to browse, search, view details, add and edit CDR processing rules in a simple manner.
Test Processing Rules tool
Simpler provides a 'TestProcessing Rules' tool where an operator can check the rating output when processing predefined CDR details. Typical use would be to test the CDR Processing Rules while defining them to ensure each row can be matched
Typical Rating Flow
Typical manual CDR rating process after the SIMPLer system has been setup would entail the following steps:
1. Prepare the CSV file. Make sure it contains the right columns in the correct order. It may require reordering the columns in the spreadsheet received from the voice provider. The final format should be similar to the example below
01-Jan-21 8:34;467160000;467160000;0048696940200;Poland - Mobile;2;0,034
01-Jan-21 8:44;467160011;467160011;0044922974535;England - Mobile;1;0,09
2. Test run the file to limit the number of processing errors. Go to 'VoIP' tab in SIMPLer, then click on 'CDR Rating Engine'. Select the CSV file you want to process, set the 'Delimiter' and 'Fraction Digits' attributes if different to the default and then click the 'Calculate VoIP Usage' button with the 'HTML' set as the output option.
Use the HTML output to identify the Processing Errors (if any). These records will fail due to:
Voice Identifier mismatch - no customer holds such Voice Identifier
CDR Processing Rule Mismatch - there is no CDR processing rule that would match the CDR record using the source, destination and region regular expressions
Add missing rules and/or Voice Identifiers until the Processing Errors section is clear. It is also recommended to scan through the Rated Output and verify if everything looks correct.
3. Import to database. Enable 'Import to Database' option and hit the 'Calculate VoIP Usage' with any output option selected. This will process the file and upload the results to the Voice Calls table
Published Date: 19-April-2021