14 About Trial Billing

This chapter provides an overview of Oracle Communications Billing and Revenue Management (BRM) trial billing and explains when and how to run trial billing.

Before you implement trial billing, you should be familiar with:

BRM billing. See "About Billing".
BRM billing applications. See "Billing Utilities".

About Trial Billing

Trial billing is a process that simulates BRM billing. You use trial billing to validate billing results without running actual billing.

The trial billing utility simulates the billing functions of the "pin_bill_accts" utility. It can additionally create and store trial invoices in the BRM database. You use trial invoices to validate customer charges before creating the final bills.

You can also collect revenue assurance data for trial bills and display the data by generating Revenue Assurance Billing reports. You use revenue assurance data to validate overall billing results.

In case of billing discrepancies, you can make corrections, such as adjustments or payment allocations, or you can run rerating. When you are satisfied with the results from trial billing, run actual billing to generate the final bills.

To perform trial billing, you run the "pin_trial_bill_accts" utility. Trial billing searches the BRM database for accounts with an expired billing date. For each account it finds, it computes the balance impacts and creates and stores a trial invoice in the BRM database.

For information on running trial billing, see "Running Trial Billing".

Comparing Billing and Trial Billing

Table 14-1 summarizes the similarities and differences between regular billing and trial billing:

Table 14-1 Comparisons between Regular Billing and Trial Billing

Billing with pin_bill_accts	Trial Billing with pin_trial_bill_accts
Performs billing on an account's billing day of month.	Performs trial billing before or after an account's billing day of month.
Creates cycle forward and usage item objects in the BRM database.	Creates cycle forward and usage item objects, but the objects are not recorded in the BRM database.
Creates bill objects in the BRM database.	Creates bill objects, but the objects are not recorded in the BRM database.
Calculates and totals the balance impacts for the previous billing cycle.	Calculates and totals the balance impacts for any billing cycle.
Calculates and updates account balances.	Calculates but does not update account balances.
Does not create invoices.	Creates and stores trial invoices in the BRM database unless you specify not to.
Balance due in the bill object shows the exact amount that is due.	Balance due in the trial invoices may not show the exact amount due at time of actual billing. This is because events that have a balance impact can occur after you run trial billing.

Note:

With regular billing, invoices are created separately by running the "pin_inv_accts" utility. The trial billing utility simulates billing and additionally creates and stores trial invoices. For this reason, a trial billing run that generates invoices takes longer than actual billing. You have the option to not generate trial invoices if you do not need them. See "Creating Trial Bills without Generating Trial Invoices".

How Trial Billing Works

When you run the "pin_trial_bill_accts" utility to perform trial billing, the PCM_OP_BILL_MAKE_TRIAL_BILL opcode is called to create the trial invoices and collect revenue assurance data for the trial billing run.

Note:

To collect revenue assurance data for trial billing, you must enable the trial billing utility to generate revenue assurance data. See "Enabling Billing Utilities to Generate Revenue Assurance Data" in BRM Collecting Revenue Assurance Data.

PCM_OP_BILL_MAKE_TRIAL_BILL calls the PCM_OP_BILL_MAKE_BILL opcode to compute the balance impacts and the balance due for the accounts specified in the input flist. The input flist includes the following fields:

The POID of the /account object for trial billing.
The name of the program that called PCM_OP_BILL_MAKE_TRIAL_BILL.
The start and end dates that specify the billing cycles for trial billing.
LAST_BILL_STATE_TO_PROCESS with the value 2 to indicate that the /billinfo state is final.
Two optional flag fields:
- PIN_FLD_PREINVOICE_MODE specifies whether to generate trial invoices for the trial billing run. See "Generating Trial Invoices".
- PIN_FLD_CHECK_SPLIT_FLAGS specifies whether to split the revenue assurance data collected for trial billing into detailed categories. See "Collecting Split Revenue Assurance Data".
  
  Note:
  Trial billing stops and reports a warning message when it encounters an account or bill unit (/billinfo) with inactive status.

Generating Trial Invoices

By default, PCM_OP_BILL_MAKE_TRIAL_BILL calls the PCM_OP_INV_MAKE_INVOICE opcode to create the trial invoice. This opcode stores the trial invoice in the primary database schema as an /invoice object (POID type /invoice/trial) and returns an array of trial invoice POIDs for the invoices that were created for the account specified in the input flist. PCM_OP_BILL_MAKE_TRIAL_BILL opens a separate transaction to create the /invoice/trial objects.

If the PIN_FLD_PREINVOICE_MODE field is present in the input flist and has a value of 1, PCM_OP_BILL_MAKE_TRIAL_BILL does not call the invoicing opcode to create trial invoices and only revenue assurance data is generated for the account. If the PIN_FLD_PREINVOICE_MODE field is not present in the input flist or has a value of 0, trial billing creates trial invoices.

Note:

If a start date is not provided in the input flist, PCM_OP_BILL_MAKE_TRIAL_BILL performs trial billing for all billing cycles completed before the end date. For accounts with skipped billing cycles, more than one trial invoice might be created.

Collecting Split Revenue Assurance Data

If the PIN_FLD_CHECK_SPLIT_FLAGS field is present in the input flist and has a value of 1, PCM_OP_BILL_MAKE_TRIAL_BILL passes this flag to PCM_OP_BILL_MAKE_BILL, which returns amounts associated with each item type and service type combination so that the revenue assurance data collected for trial billing can be split into detailed categories. The item and service type details are returned in the PIN_FLD_REVENUES array in the output flist, along with the total number of subscription services associated with the account. If any bills were suppressed, the amount suppressed and the suppression reason are also returned.

If PIN_FLD_CHECK_SPLIT_FLAGS has a value of 0 or is not present in the input flist, PCM_OP_BILL_MAKE_TRIAL_BILL does not return item type and service type details.

Split revenue assurance data can be viewed by generating a Revenue Assurance Billing Detail report.

About Trial Invoices

A trial invoice is a statement of charges and the balance that is due. You use trial invoices to validate billing charges before creating final bills for your customers. Trial invoices are generated when you run the trial billing utility (pin_trial_bill_accts). For information about creating trial invoices, see "Running Trial Billing".

Note:

Trial invoices are created only for billing cycles that have not been billed yet.
Trial invoices are optional. If you do not need trial invoices, you can specify not to generate them: for example, when the revenue assurance data collected from trial billing is sufficient for validating the billing results.

Figure 14-1 shows a trial invoice displayed in the Sample Invoice Viewer using the default invoice template:

Figure 14-1 Trial Invoice

Description of ''Figure 14-1 Trial Invoice''

Note:

Session or activity charges incurred between the dates of actual billing and trial billing do not appear on trial invoices.

You can design your own invoice templates for displaying trial invoices, and you can customize the information displayed on trial invoices in the same ways you do for regular invoices.

For more information about invoice templates, see "Designing Invoice Templates" in BRM Designing and Generating Invoices.

For more information about customizing invoice information, see "Customizing the Information Included in Invoices" in BRM Designing and Generating Invoices.

You can also purge and export trial invoices. See "Purging Trial Invoices" and "Exporting Trial Invoices".

How Trial Invoices Are Stored

Trial invoices are stored in the BRM database in the same formats as regular invoices. By default, trial invoices are stored in pin_flist format. For more information about invoice storage formats, see "About Formats for Storing Invoices" in BRM Designing and Generating Invoices.

Trial invoices and regular invoices are different in the following ways:

Trial invoices and regular invoices are stored in the /invoice object with different POID types. Regular invoices are stored with the POID type /invoice. Trial invoices are stored with the POID type /invoice/trial, a subclass of the /invoice base class. If you have a custom /invoice class: for example, /invoice/custom_subclass: BRM stores trial invoices with the POID type /invoice/custom_class/trial.
Trial invoices are always stored in the primary BRM database schema. In a multischema system, regular invoices can be stored in a separate schema.

Using Trial Invoices for Validating Billing Charges

The following examples show how to use trial invoices for validating billing charges:

Verifying a new price plan

You can use trial billing to verify that a new price plan is loaded in the system and set up correctly. For example, you can designate a few accounts as test accounts for specified products. Run trial billing on the billing date for these accounts by specifying their account POIDs. The trial invoices that are generated for these accounts can then be reviewed by your customer service representatives or billing operations personnel to verify that charges have been applied correctly based on a predefined output.

In case rate fees such as usage charges from an obsolete price plan have been applied to real accounts, run rerating to make new rates effective retroactively, before your billing run.
Verifying miscellaneous charges, such as refunds

If your company issues a mass refund to subscribers, you can run trial billing at any time during the billing cycle to verify that the refunds were applied correctly. Select a few accounts and run trial billing by specifying their account POIDs.

You can perform similar verifications for taxes, late fees, or finance charges; for example, when a new tax rate is introduced, when a late fee changes from $20 to $25, or when the finance rate changes from 6% to 7%. You can run trial billing to verify that the new rates are being applied.

Review the trial invoices. If any discrepancies are found, you can make corrections, such as changing the price plan, making billing adjustments, or running rerating. Certify your results by rerunning trial billing before sending final invoices to your subscribers.

About Collecting Revenue Assurance Data From Trial Billing

When you enable trial billing to generate revenue assurance data, the data is automatically generated when you run the pin_trial_bill_accts utility. You can use this data to validate overall billing results. To view the data, run a Revenue Assurance Billing Summary report.

You enable trial billing to generate revenue assurance data by setting an entry in the trial billing configuration file (BRM_Home/apps/pin_trial_bill/pin.conf, where BRM_Home is the directory where you installed BRM components). For more information, see "Enabling Billing Utilities to Generate Revenue Assurance Data" in BRM Collecting Revenue Assurance Data.

You can also split revenue assurance data collected from trial billing into more detailed categories by running pin_trial_bill_accts with the -split parameter. The split data is based on the type of billable item and its associated services. To view split revenue assurance data, run a Revenue Assurance Billing Detail report.

Note:

The -split parameter for pin_trial_bill_accts is valid only if Revenue Assurance Manager is installed.

You can customize how revenue assurance data is split by configuring item subtypes for the type of revenue, such as one-time usage, recurring charges, adjustments, and payments.

For information about revenue assurance data, see "About Collecting Revenue Assurance Data from Billing" in BRM Collecting Revenue Assurance Data.

For more information about split revenue assurance data, see "About Splitting Revenue Assurance Data into Detailed Categories" in BRM Collecting Revenue Assurance Data.

For information about Revenue Assurance Manager reports, see "Revenue Assurance Manager Reports" in BRM Collecting Revenue Assurance Data.

For information about generating reports, see "Running BRM Reports" in BRM Reports.

Running Trial Billing

To run trial billing, you run the pin_trial_bill_accts utility. It connects to the default database schema specified in the trial billing configuration file (pin.conf) located in the BRM_Home/apps/pin_trial_bill directory.

For a description of the syntax and parameters for pin_trial_bill_accts, see "pin_trial_bill_accts".

Important:

If you use the pin_bill_day script to run the pin_bill_accts utility, you must run pin_trial_bill_accts before running pin_bill_day.

When you run trial billing, you can specify search criteria such as the billing cycles, the status of the accounts, and the list of accounts and bill units for which to create trial bills. pin_trial_bill_accts creates trial bills for all accounts and bill units that meet the search criteria you specify. If you do not specify any search criteria, pin_trial_bill_accts generates trial bills for all billing cycles that have not been billed and are complete at the time you run the utility.

You can configure pin_trial_bill_accts to select accounts randomly or you can provide a list of accounts and bill units in an input file. See "Specifying Accounts for Trial Billing".

You can provide a list of accounting days of month (DOMs) and billing segments in an input file to select bill units with the specified DOMs or segments. You can also use this input file to provide a list of specific accounts and bill units. See "Specifying Bill Units, Billing Segments, and DOMs for Trial Billing".

If the revenue assurance data collected from trial billing is sufficient for validating your billing charges, you can run the trial billing utility without creating trial invoices. This improves the performance of trial billing. See "Creating Trial Bills without Generating Trial Invoices".

Specifying Accounts for Trial Billing

To run trial billing for a small number of random accounts, set the pin_trial_bill_accts flag in the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf) to the maximum number of accounts to bill:

- pin_trial_bill_accts threshold numberOfAccounts

To specify a list of specific accounts to be trial billed, use the -f parameter:

pin_trial_bill_accts -end 4/1/2002 -f inputFile

Note:

You can also use the -f_control parameter as an alternative way of specifying accounts for trial billing. See "Specifying Bill Units, Billing Segments, and DOMs for Trial Billing".

The input file lists the account POIDs and bill unit POIDs in flist array format. The flist must use the following structure, where each array element corresponds to one account and bill unit:

0 PIN_FLD_RESULTS             ARRAY [0] allocated 1, used 1
1     PIN_FLD_ACCOUNT_OBJ      POID [0] 0.0.0.1 /account 9605
1     PIN_FLD_POID             POID [0] 0.0.0.1 /billinfo 2342
0 PIN_FLD_RESULTS             ARRAY [1] allocated 1, used 1
1     PIN_FLD_ACCOUNT_OBJ      POID [0] 0.0.0.1 /account 9765
1     PIN_FLD_POID             POID [0] 0.0.0.1 /billinfo 2570
0 PIN_FLD_RESULTS             ARRAY [2] allocated 1, used 1
1     PIN_FLD_ACCOUNT_OBJ      POID [0] 0.0.0.1 /account 11973
1     PIN_FLD_POID             POID [0] 0.0.0.1 /billinfo 3987

Note:

Trial billing stops and reports a warning message when it encounters an account or bill unit (/billinfo) with inactive status.
All accounts listed in the input file will be trial billed.
If a selected account has a subordinate bill unit, pin_trial_bill_accts does not create a trial bill for it. Subordinate bill units are trial billed only when their parent accounts are selected for trial billing.
If an account that has not been billed for some time is selected for trial billing, a trial invoice is generated for each billing cycle that was skipped. The invoice data is stored in shared memory until all the billing cycles have been processed. If the account skipped many billing cycles, this could result in a PIN_ERR_NO_MEM error, indicating that the system does not have enough shared memory to process that account.

Specifying Bill Units, Billing Segments, and DOMs for Trial Billing

You can run trial billing for bill units associated with specified accounting DOMs, specified billing segments, or a combination of DOMs and segments. You list the DOMs and billing segments in a trial-billing-run configuration file. You can also use this file to specify a list of accounts and bill units for trial billing.

You create a trial-billing-run configuration file by copying and modifying the BRM billing run configuration file (BRM_Home/apps/pin_billd/pin_bill_run_control.xml). You then specify this file when you run pin_trial_bill_accts with the -f_control parameter.

Note:

Using a trial-billing-run configuration file to specify accounts for trial billing is an alternative way of specifying accounts in flist format by using the -f parameter. (See "Specifying Accounts for Trial Billing".)
The pin_bill_run_control.xml file is the same file used to split a regular billing run into multiple runs. (See "Splitting a Billing Run into Multiple Runs".)

To specify accounts and bill units, DOMs, or billing segments for trial billing:

Open the pin_bill_run_control.xml file in an XML editor or a text editor.

By default, the file is in the BRM_Home/apps/pin_billd directory.
Edit the file to specify the bill units to trial bill:
- To specify accounts and their bill units, see "Specifying Bill Units for Trial Billing".
- To specify accounting DOMs, see "Specifying Accounting DOMs for Trial Billing".
- To specify billing segments, see "Specifying Billing Segments for Trial Billing".
Save the file under a different name and close it. Give the file a meaningful name: for example, if trial billing a group of accounts, include the account range or reason for billing in the file name; if trial billing specific DOMs, include the DOM range in the file name.

Note:
When you run pin_trial_bill_accts, the configuration file you create and the default BRM_Home/apps/pin_billd/business_configuration.xsd file must be in the same directory.
Run pin_trial_bill_accts with the -f_control parameter:
```
pin_trial_bill_accts -end 4/1/2002 -f_control filename
```
where filename is the name of the trial-billing-run configuration file that you created.
Note:
- If filename is in the same directory from which you run pin_trial_bill_accts, specify only the file name.
- If filename is in a different directory from which you run pin_trial_bill_accts, you must include the entire path for the file.

For more information, see "pin_trial_bill_accts".

Specifying Bill Units for Trial Billing

To generate trial bills for a set of accounts and bill units, add a BillingList parent element in the trial-billing-run configuration file for each account and bill unit to include. In the BillingList parent element, add an Account child element that specifies the POID ID of the account, and add a Billinfo child element that specifies the POID ID of the bill unit.

Important:

Trial billing stops and reports a warning message when it encounters an account or bill unit (/billinfo) with inactive status.
To trial bill specific accounts and bill units, you must include both the account POID and bill unit POID. If only one is specified, the account or bill unit is not trial billed.

For example, the following BillingList parent element generates trial bills only for the bill unit with POID ID 64295 that belongs to the account with POID ID 17763:

<BillingList>
    <Account>17763</Account>
    <Billinfo>64295</Billinfo>
</BillingList>

To specify multiple accounts or multiple bill units from the same account, add a BillingList parent element for each bill unit. For example, the following entries generate two trial bills for the account with POID ID 17763 and one trial bill for the account with POID ID 25147:

<BillingList>
    <Account>17763</Account>
    <Billinfo>64295</Billinfo>
</BillingList>
<BillingList>
    <Account>17763</Account>
    <Billinfo>68439</Billinfo>
</BillingList>
<BillingList>
    <Account>25147</Account>
    <Billinfo>314552</Billinfo>
</BillingList>

Specifying Accounting DOMs for Trial Billing

To generate trial bills for bill units associated with specified accounting DOMs, add a DOMList parent element in the trial-billing-run configuration file. In the DOMList parent element, add a DOM child element that specifies the accounting DOM for each day whose bill units you want to include.

For example, the following DOMList parent element generates trial bills only for bill units whose accounting DOM is 1 or 15:

<DOMList>
    <DOM>---01</DOM>
    <DOM>---15</DOM>
</DOMList>

If the DOMList parent element is omitted, bill units associated with any accounting DOM can be included in the billing run.

Specifying Billing Segments for Trial Billing

To run trial billing for specified billing segments, you must first set up billing segments in your system and then associate them with bill units. For more information, see "About Billing Segments".

To generate trial bills for bill units associated with specified billing segments, add a BillSegmentList parent element in the trial-billing-run configuration file. In the BillSegmentList parent element, add a BillSegment child element that specifies the billing segment ID for each billing segment whose bill units you want to include. The segment ID is the ID of any billing segment defined in the /config/billing_segment object in your BRM system.

For example, the following BillSegmentList parent element generates trial bills only for bill units associated with billing segments 101, 102, and 103:

<BillSegmentList>
    <BillSegment>101</BillSegment>
    <BillSegment>102</BillSegment>
    <BillSegment>103</BillSegment>
</BillSegmentList>

If the BillSegmentList parent element is omitted, bill units associated with any billing segment can be included in the billing run.

Creating Trial Bills without Generating Trial Invoices

If the revenue assurance data collected from trial billing provides enough information for you to validate your billing charges and you do not need the specific information provided in invoices, you can run the trial billing utility with the -bill_only parameter. This parameter suppresses the creation of trial invoices. Generating trial invoices takes longer than regular billing; therefore, running trial billing without generating trial invoices improves the performance of trial billing and is equivalent in performance to running regular billing.

Hierarchical and Sponsor Groups for Trial Billing

Hierarchical and sponsorship groups enable customers to pay other customers bills. Hierarchical accounts form a parent-child relationship, and parent and child accounts are on the same billing cycle. Trial billing for hierarchical accounts is handled differently than regular billing.

In regular billing, charges for the subordinate accounts are calculated first and then rolled up to the parent account. For each subordinate account, BRM creates a database lock, computes the balance impacts, and then releases the lock.

In trial billing, the parent and all its subordinate accounts are locked simultaneously. The parent account as well as the subordinate accounts remain locked until all the subordinate account balance impacts have been computed and rolled up to the parent account.

Note:

As with regular billing, the invoicing threshold value for hierarchical groups is considered during trial billing. If the threshold value is exceeded: that is, the number of subordinate bill units is greater than the threshold value: a separate invoice is generated for each subordinate bill unit by using multiple threads, and the invoice for the accounts receivable account's invoice will not contain the data. For more information, see "About Invoicing for Hierarchical Account Groups" in BRM Designing and Generating Invoices.

Important:

When hierarchical accounts are selected for trial billing, access to the parent and child accounts is prevented and system performance is decreased as a result of the database locks.

In contrast, sponsorship occurs when an account is added to a sponsored group and a sponsored product is added to that account. The sponsored group account owner and the member account can have different billing cycles. When a sponsored group owner is selected for trial billing, the trial invoice may not contain all the fees from member accounts.

In regular billing, when a sponsored group owner account is billed, BRM processes the member accounts to determine the sponsored fees to apply to the sponsor owner. The sponsored cycle events of member accounts are accumulated in the /item/sponsor object of the sponsor owner account and appear on the sponsor owner's bill.

In trial billing, when a sponsor owner account is selected, trial billing is not processed for member accounts. A sponsor owner can be processed for trial billing without creating trial bills for member accounts. In this case, the sponsor owner's trial invoice may not contain the sponsored system events of the member accounts.

In the example shown in Figure 14-2, the trial invoice created for the sponsor owner account does not contain the sponsored events (cycle events) of the member account:

Figure 14-2 Included Charges in a Sponsor Owner Trial Invoice

Description of ''Figure 14-2 Included Charges in a Sponsor Owner Trial Invoice''

For more information about hierarchical and sponsored group accounts, see "About Account Groups" in BRM System Administrator's Guide.

Purging Trial Invoices

To purge trial invoices, run the pin_trial_bill_purge utility.

By default, pin_trial_bill_purge purges invoices with the /invoice/trial POID type. If a custom /invoice subclass exists, invoices with /invoice/custom_subclass/trial POID type are purged.

Caution:

If the /invoice class is partitioned, running the purge utility (partition_utils -o) on /invoice purges both regular invoices and trial invoices.

For a description of the syntax and parameters of this utility, see "pin_trial_bill_purge".

For more information about trial invoices, see "About Trial Invoices".

Exporting Trial Invoices

To export trial invoices, run the pin_inv_export utility and use the -trial parameter.

You can export trial invoices in the same formats that are supported for regular invoices. To export trial invoices, follow the same procedures you use for exporting regular invoices. For more information, see "Exporting Invoices" in BRM Designing and Generating Invoices.

For a description of the syntax and parameters of this utility, see "pin_inv_export" in BRM Designing and Generating Invoices.

Viewing Trial Invoices

You can view trial invoices in the following ways:

Use the Sample Invoice Viewer to view invoices stored in the database.
Use a Web browser to view invoices in HTML format.

The Sample Invoice Viewer is shipped with BRM and can be found in the BRM_Home/source/apps/sampleviewer directory. Follow the instructions in the Sample Invoice Viewer readme file on how to configure and run the Sample Invoice Viewer to view trial invoices.

You can also use the pin_inv_export utility to export trial invoices in HTML format and view them in your Web browser. For more information, see "Exporting Trial Invoices".

Note:

You cannot view trial invoices by using the Invoice Viewer in Customer Center.

Improving Trial Billing Performance

The trial billing application is a multithreaded application that uses a set of configuration entries similar to the pin_bill_accts billing application.

Important:

Trial billing may stop responding if the Data Manager has too few back ends configured. You should change the default configuration settings for Data Manager and increase the number of back ends. For more information about setting the number of back ends, see "Improving Data Manager and Queue Manager Performance" in BRM System Administrator's Guide.

For information on how to configure these entries for optimum performance, see "Tuning Billing Performance" in BRM System Administrator's Guide.

For information about multithreaded application, see "Configuring Your Multithreaded Application" in BRM Developer's Guide.