18 Running Trial Billing

Learn how to run trial billing to validate billing results in Oracle Communications Billing and Revenue Management (BRM) without billing your customers.

Topics in this document:

• About Trial Billing

• About Trial Invoices

• About Collecting Revenue Assurance Data from Trial Billing

• Configuring Trial Billing

• Running Trial Billing

• Purging Trial Invoices

• Exporting Trial Invoices

About Trial Billing

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

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 can also collect revenue assurance data for trial bills and display the data by generating Revenue Assurance Billing reports.

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.

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

Table 18-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, usage item, and bill objects in the BRM database.	Creates cycle forward and usage item 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".

About Trial Billing for Bill Unit Hierarchies and Sharing Groups

Bill unit hierarchies and sharing groups enable customers to pay other customers' bills. Bill unit hierarchies form a parent-child relationship; paying parent bill units and their nonpaying child bill units are on the same billing cycle. Trial billing for bill unit hierarchies is handled differently from regular billing.

In regular billing, charges for nonpaying child bill units are calculated first and then rolled up to the paying parent bill unit. BRM creates a database lock for each nonpaying bill unit, computes the balance impacts, and then releases the lock.

In trial billing, the paying parent and all its nonpaying child bill units are locked simultaneously. The parent bill unit and the nonpaying child bill units remain locked until the balance impacts of all nonpaying bill units are computed and rolled up to the parent bill unit.

Note:

• As with regular billing, BRM considers the invoicing threshold value for bill unit hierarchies during trial billing. If it exceeds the threshold value (the number of nonpaying bill units is greater than the threshold value), a separate invoice is generated for each nonpaying bill unit by using multiple threads.

• When hierarchical bill units are selected for trial billing, access to the parent and child bill units is prevented, and system performance is decreased due to the database locks.

With sharing groups, sharing occurs when an account is added to a sharing group and a discount is added to that account. The sharing group owner account and member account can have different billing cycles. When a sharing group owner is selected for trial billing, the trial invoice might not contain all the fees from member accounts.

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

In trial billing, when a sharing group owner account is selected, trial billing is not run for member accounts. In this case, the owner's trial invoice might not contain the recurring charges for the sponsored cycle events of the member accounts because such charges are generated by running billing. The owner's trial invoice would, however, contain the members' usage charges because those charges are not generated by billing.

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.

• 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.

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

Note:

Trial invoices are always stored in the primary BRM database schema. In a multischema system, regular invoices can be stored in a separate schema.

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). 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.

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.

Configuring Trial Billing

You can configure the following options for trial billing:

• Specifying Accounts for Trial Billing

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

• 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. Each array element corresponds to one account and bill unit.

Note:

• Trial billing stops and reports a warning message when it encounters an account or bill unit with inactive status.

• All accounts listed in the input file will be trial billed.

• If a selected account has a nonpaying bill unit, pin_trial_bill_accts does not create a trial bill for it. Nonpaying 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 "Configuring a Split Billing Run".

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

1. 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.

2. 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".

3. 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.

4. 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. If filename is in a different directory from which you run pin_trial_bill_accts, you must also 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 of the account, and add a Billinfo child element that specifies the POID of the bill unit.

Note:

• Trial billing stops and reports a warning message when it encounters an account or bill unit 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 64295 that belongs to the account with POID 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 17763 and one trial bill for the account with POID 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 "Load Balancing Billing Runs".

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.

Running Trial Billing

To run trial billing, use the "pin_trial_bill_accts" utility:

1. Go to BRM_home/apps/pin_trial_bill.

2. Run the pin_trial_bill_accts utility:

   pin_trial_bill_accts
   

   Running the utility with no parameters runs trial billing for all accounts that are due for billing. You can run trial billing for a subset of accounts. For example, you can:

   • Use the -start and -end parameters to run trial billing for bills in a specified date range. See "Running Trial Billing With Date Ranges".

   • Use the -pay_type parameter to run trial billing for a specific payment type.

   • Use the -bill_only to run trial billing without generating trial invoices and collect revenue assurance data.

   • Use the -split parameter to generate detailed revenue assurance data.

   • Use the -active, -inactive, and -closed parameters to run trial billing for a specific account status.

   See "pin_trial_bill_accts".

Running Trial Billing With Date Ranges

The start and end dates determine which accounts are selected for trial billing and which billing cycles for those accounts are trial billed.

The end date is used as the search criteria for retrieving accounts for trial billing. The search selects all accounts with a billing date less than the end date. You can specify either an absolute date, a number of days before or after the current date, or the current date (by specifying 0).

Note:

If you do not specify an end date, pin_trial_bill_accts uses the current date for the end date.

The start date determines the billing cycles for which trial invoices are generated. You can specify either an absolute date, a number of days before or after the current date, or the current date (by specifying 0).

If you specify a start date, trial billing is run only when a billing cycle is completed between the start date and the end date. Trial billing is not run on partial cycles.

Note:

If you do not specify a start date or if you specify 0 for the current date, pin_trial_bill_accts generates trial invoices for all billing cycles that were completed between the current date and the end date and that have not already been billed. More than one trial invoice might be generated for accounts that have not been billed for one or more billing cycles.

Examples:

• Create trial invoices for accounts whose billing date is on or before 4/1/2002 (current date is 3/15/2002):

  pin_trial_bill_accts -end 04/01/2002
  pin_trial_bill_accts -end +17
    

• Create trial invoices for accounts whose billing date is on or before 3/1/2002 (current date is 3/15/2002)

  pin_trial_bill_accts -end 03/01/2002
  pin_trial_bill_accts -end -14
    

• Create trial invoices for accounts whose billing date is on or before the current date:

  pin_trial_bill_accts -end 0
  pin_trial_bill_accts
    

• Create trial invoices for accounts with complete billing cycles between 4/1/2002 and 5/15/2002 (current date is 5/15/2002):

  pin_trial_bill_accts -start 04/01/2002 -end 5/15/2002
  pin_trial_bill_accts -start -44 -end 0

Running Trial Billing According to Payment Type

Generates trial invoices for accounts with the specified payment method ID. If you do not specify the payment method ID, the pin_trial_bill_accts utility generates trial invoices for all payment methods.

The ID can be any payment method ID from Table 18-2.

Table 18-2 Payment Method ID

Payment Method	ID
credit card	10003
debit card	10002
direct debit	10005
guest	10010
invoice	10001
prepaid	10000
SEPA	10018
subordinate	10007
undefined	0

For example, to generate trial invoices for all bills paid by the credit card payment method, use the following syntax:

pin_trial_bill_accts -pay_type 10003
   

For hierarchical bill units, you must run nonpaying child bill units before running paying parent bill units. For example, to generate trial invoices for hierarchical bill units whose payment method is by check, use the following syntax:

pin_trial_bill_accts -pay_type 10007
pin_trial_bill_accts -pay_type 10012
   

Note these limitations:

• The -active, -closed, or -inactive parameters are not supported for nonpaying child bill units when combined with the -pay_type parameter. These parameters limit the number of nonpaying child bill units that are invoiced, which leads to errors when their paying parent bill unit is trial billed.

• Do not set a threshold value. Setting a threshold value limits the number of nonpaying child bill units that are invoiced, which leads to errors when their paying parent bill unit is trial billed.

  Note:

  The threshold entry is located in the BRM_home/apps/pin_trial_bill/pin.conf file.

• The -f, -f_control, and -bill_only parameters are not supported for all bill units when used with the -pay_type parameter.

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.

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.

Note:

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.