Skip Headers
Oracle® Communications Billing and Revenue Management Configuring and Running Billing
Release 7.5

E16696-08
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

13 Running Billing Utilities

This chapter describes how to run the Oracle Communications Billing and Revenue Management (BRM) billing utilities.

For background information about BRM billing, see "About Billing".

For background information about corrective billing in BRM, see "About Corrective Billing".

To run billing, you should know how to use the cron and crontab commands.

Before running billing, you must set the billing configuration defaults, as described in "Setting Business Policies for Billing".

About Billing Your Customers

The way in which you bill customers depends on whether they are to receive a regular bill or a corrective bill for a prior bill.

Regular Billing Process

To bill customers, you run a set of billing utilities by running billing scripts automatically or manually on a daily, weekly, and monthly basis. See "About Running the Billing Scripts".

When you run the daily billing script, BRM does the following tasks:

  1. Runs the pin_deferred_act utility to execute scheduled (deferred) actions. See "Executing Deferred Actions with the pin_deferred_act Utility".

  2. Runs the pin_bill_accts utility to create bills for accounts, and to perform accounting cycle functions, such as creating new bill items. See "Billing Accounts with the pin_bill_accts Utility".

  3. Runs the pin_collect utility to collect credit card payments. See "About Collecting BRM-Initiated Payments" in BRM Configuring and Collecting Payments.

  4. Runs the pin_refund utility to generate refunds for BRM-initiated payments. See "About Refunds" in BRM Managing Accounts Receivable.

  5. Runs the pin_inv_accts utility to create invoices. See "Generating Invoices with the pin_inv_accts Utility".

  6. Runs the pin_deposit utility to deposit pre-authorized credit card payments, such as payments authorized when issuing a charge in Customer Center. See "About Collecting BRM-Initiated Payments" in BRM Configuring and Collecting Payments.

  7. Runs the pin_cycle_fees utility to prorate balance impacts for cycle forward fees. See "Prorating Cycle-Forward Fees and Canceling Products with the pin_cycle_fees Utility".

In addition to running daily billing, you also run weekly and monthly billing scripts that run the pin_collect utility to collect payments that the daily billing was not able to collect.

For more information about the billing utilities, see "About the Billing Utilities". For information about handling billing failures, see "Handling Billing Failures".

Corrective Billing Process

The corrective billing process in BRM does not support the above mentioned scripts. The general steps in the process are:

  1. Run the pin_make_corrective_bill utility to generate the corrective bill.

  2. Run the pin_inv_accts to generate Corrective Invoices. See BRM Configuring and Generating Invoices.

  3. Run the pin_collect utility. See "About Collecting BRM-Initiated Payments" in BRM Configuring and Collecting Payments.

  4. Run the pin_collections_process utility. For more information on this utility see BRM Developer's Reference.

About the Billing Utilities

The billing scripts run the following utilities:

The billing scripts also run payment utilities. See the following topics:

Billing Accounts with the pin_bill_accts Utility

The pin_bill_accts utility is used to generate regular bills.

The pin_bill_accts utility calculates the balance due for each account bill unit, including all usage and cycle fees, and creates a bill for the balance due. It creates bills for accounts whose billing date is any day before midnight of the day that you run the pin_bill_accts utility as shown in Figure 13-1.

Figure 13-1 Accounts Included when Running pin_bill_accts

Description of Figure 13-1 follows
Description of "Figure 13-1 Accounts Included when Running pin_bill_accts"

The balance due amount is the amount requested as a payment by the pin_collect utility, and the amount that is shown on the invoice. For more information about the due amount, see "Fields in an Item" in BRM Managing Accounts Receivable.

The pin_bill_accts utility also performs the accounting cycle activity, such as creating new bill items. For more information, see "About accounting and billing cycles".

For information about the pin_bill_accts utility syntax, see "pin_bill_accts".

When to Run the pin_bill_accts Utility

Use the pin_bill_day script to run the pin_bill_accts utility daily.

If you use the subordinate hierarchy, you must run the pin_bill_accts utility to bill subordinate bill units before the parent bill units. The correct order is set in the pin_bill_day script.

You must run the pin_bill_accts utility before you run pin_collect because pin_collect needs the balance due amount collected by the pin_bill_accts utility.

Increasing Performance of the pin_bill_accts Utility

To increase billing performance, you run multiple threads of the pin_bill_accts utility simultaneously. See "Tuning Billing Performance" in BRM System Administrator's Guide.

Customizing the pin_bill_accts Utility

The pin_bill_accts utility uses the BRM MTA framework. You can customize pin_bill_accts by using the callback function and policy opcode hooks provided in the MTA framework.

For more information, see "Customizing BRM Multithreaded Client Applications" in BRM Developer's Guide.

Billing Accounts with the pin_make_corrective_bill Utility

The pin_make_corrective_bills utility generates corrective bills.

This utility is used to generate corrective bills for prior bills that have corrections or to process corrections on prior corrective bills.

The pin_make_corrective_bills utility validates that it can generate corrective bills for the selected bill, calculates the balance due after allocating the adjustments and A/R actions for each account bill unit and creates a corrective bill for the balance due. It creates corrective bills for accounts whose bills have corrections that fall within the period you specify.

The balance due amount is the amount requested as a payment by the pin_collect utility, and the amount that is shown on the corrective invoice. For more information about the due amount, see "Fields in an Item" in BRM Managing Accounts Receivable.

The pin_make_corrective_bills utility sets up an event for the type of corrective invoice to associate with the corrective bill.

For information about the pin_make_corrective_bills utility syntax, see "pin_make_corrective_bills".

When to Run the pin_make_corrective_bills Utility

Run the pin_make_corrective_bills utility when you have allocated all adjustments to prior bills.

When you generate corrective bills for an account hierarchy, you must run the pin_make_corrective_bills utility for the parent bill unit.

You must run the pin_make_corrective_bills utility before you run pin_collect because pin_collect needs the balance due amount collected by the pin_make_corrective_bill utility.

Increasing Performance of the pin_make_corrective_bill Utility

To increase billing performance, you run multiple threads of the pin_make_corrective_bills utility simultaneously. See "Tuning Billing Performance" in BRM System Administrator's Guide.

Customizing the pin_make_corrective_bill Utility

The pin_make_corrective_bills utility uses the BRM MTA framework. You can customize pin_make_corrective_bills by using the callback function and policy opcode hooks provided in the MTA framework.

For more information, see "Customizing BRM Multithreaded Client Applications" in BRM Developer's Guide.

Generating Invoices with the pin_inv_accts Utility

The pin_inv_accts utility generates regular invoices for regular bills and corrective invoices for corrective bills. Use the pin_inv_accts utility to generate regular invoices and corrective invoices and store them in the BRM database or in a separate database.

For more information about:

When to Run pin_inv_accts

For regular bills, typically, you run invoicing each day for accounts that had a regular bill created by the pin_bill_accts utility. For information, see "Running Daily Billing".

If you miss any billing days, the pin_inv_accts utility still generates invoices for accounts whose billing day was missed. This is because the pin_bill_accts utility creates bills for the missed billing days, and the pin_inv_accts utility generates invoices for those bills as shown in Figure 13-2.

Figure 13-2 Invoices Created when Running pin_inv_accts

Description of Figure 13-2 follows
Description of "Figure 13-2 Invoices Created when Running pin_inv_accts"

For corrective bills, you run generate a corrective invoice when you create the corrective bill using the pin_make_corrective_bill utility.

Viewing Invoices

By default, you can view invoices through Customer Center, and your customers can view them on your Web pages. You can use XSL style sheets or other methods to design your invoices. For more information, see "Designing and Generating Invoices" in BRM Designing and Generating Invoices.

Emailing or Printing Invoices

To email invoices, or to print invoices for faxing or mailing, run the pin_inv_send utility. This utility is not included in the daily billing script by default. You can either add it to the daily billing script or run it separately.

For information, see "Sending Invoices to Customers" in BRM Designing and Generating Invoices.

Prorating Cycle-Forward Fees and Canceling Products with the pin_cycle_fees Utility

The pin_cycle_fees utility performs two tasks:

  • Use this utility to identify cycle-forward fees that have reached the end of free billing periods. For example, if a customer signs up for one month of free service, the pin_cycle_fees utility finds when the free period is over, and applies the cycle-forward fee balance impact to the customer's account balance group.

  • Use this utility to cancel products that have an expired pending cancellation. For example, if a product is set to cancel at a future date, the pin_cycle_fees utility cancels the product.

    Important:

    These two tasks are performed by running the pin_cycle_fees utility twice with different parameters.

How the pin_cycle_fees Utility Prorates Cycle Forward Fees

If a free period ends before the customer's billing date, the pin_cycle_fees utility calculates the prorated fees for the time between the end of the free period and the start of the customer's next accounting cycle.

For example, a customer opens an account on February 15 and is given one free month, but the customer's billing date is on the 1st of the month. When you run pin_cycle_fees on March 15, it finds that the customer's free time period has ended. The utility then assesses the prorated fee due for March 15 through March 31 and impacts the customer's balance with the prorated amount. The result is that the system makes no charges to the customer on March 1, but charges the prorated fee and the cycle fee on April 1 as shown in Figure 13-3.

Figure 13-3 Proration of Cycle Forward Fees by pin_cycle_fees

Description of Figure 13-3 follows
Description of "Figure 13-3 Proration of Cycle Forward Fees by pin_cycle_fees"

The pin_cycle_fees utility checks for all free cycle-forward fees that have expired.

For information about the pin_cycle_fees utility syntax, see "pin_cycle_fees".

When to Run the pin_cycle_fees Utility

Use the pin_bill_day script to run the pin_cycle_fees utility daily. This applies the prorated balance impacts as soon as they are due. If you do not run the pin_cycle_fees utility daily, the pin_bill_accts utility applies the balance impacts for the expired cycle forward fees. The only difference is that the balance impacts are not calculated by the pin_cycle_fees utility on the day that the cycle-forward fee expires.

Informing Customers That a Free Period Has Ended

You can find accounts that contain an expired free cycle-forward fee, and inform those customers that their free period has ended. To do so, run the pin_cycle_fees utility with the verbose and test options. Then use a custom utility to notify the customers. See "pin_cycle_fees".

Improving Performance of the pin_cycle_fees Utility

If system performance slows unacceptably when running the pin_cycle_fees utility, edit the pin_bill_day script and change the default start and end parameters for the pin_cycle_fees utility to every other day or every third day.

Executing Deferred Actions with the pin_deferred_act Utility

The pin_deferred_act utility enables you to execute scheduled actions. Using /schedule objects, you can schedule in advance when to activate, inactivate, or close an account or service. You can also schedule future changes to account groups. To ensure that the account status is correct before running billing, the pin_deferred_act utility makes all scheduled status and hierarchical group changes before running the other billing utilities.

For more information about the pin_deferred_act utility syntax, see "pin_deferred_act".

When to Run the pin_deferred_act Utility

Use the pin_bill_day script to run the pin_deferred_act utility daily. It is the first billing utility run by the pin_bill_day script.

About Running the Billing Scripts

BRM supports billing scripts for regular bills only.

Billing scripts run one or more billing utilities on a daily, weekly, or monthly basis. By default, billing scripts are located in BRM_Home/bin, where BRM_Home is the directory where you installed BRM components. Table 13-1 shows the billing utilities in each script:

Table 13-1 Utilities in Billing Scripts

Billing Script Description

pin_bill_day

Run daily.

Runs the following billing utilities:

pin_bill_week

Run weekly.

By default, runs the pin_collect utility with the rebill option on all active accounts with a payment collection date at least 8 days old. Collects outstanding balances from active credit card or direct debit accounts that could not be collected during regular daily billing.

pin_bill_month

Run monthly.

By default, runs the pin_collect utility with the rebill option on all closed and inactive accounts with a payment collection date at least 31 days old. Collects outstanding balances from closed or inactive accounts.


Customizing the Billing Scripts

Billing scripts are located in BRM_Home\bin.

You can customize the billing scripts in the following ways:

  • Specify which billing utilities to run.

  • Use the parameters for each billing utility to specify how to run them.

  • Set the error logging level.

Running Billing

Run billing as pin_user, not as root. Running billing as pin_user provides the read/write permissions for billing.

Note:

Avoid running other BRM utilities while running billing as it may impact billing performance because of database contention.

What Time to Run Billing Scripts

Since billing generates a lot of system activity, it's best to run billing scripts at night.

Important:

Use a different time for all three scripts so you do not run billing utilities simultaneously.

Manually Running the pin_bill_day Script

If you do not use bill run management, run the following command:

pin_bill_day

You must run the pin_bill_day script manually instead of automatically to do the following:

When running pin_bill_day manually with bill run management, you use this syntax:

pin_bill_day -file filename

Where filename is the name and location of a billing run configuration file.

The script passes the name of the file to the pin_bill_accts utility, which validates the file and then uses its contents to configure a billing run.

Note:

  • The -file parameter when used with pin_bill_day, affects only the pin_bill_accts utility; it does not apply to other billing utilities run by the pin_bill_day script. For example, pin_cycle_fees which performs a database search to find all accounts with cycle forward fees that are due, does not use the accounts passed in with the -file option.

  • When running pin_bill_day with the -file option, ensure that the accounts specified in the billing run configuration file reside on the same database schema where pin_bill_day is run. If the file contains accounts from different database schemas, pin_bill_day reports an error.

Caution:

When you use a cron job to run pin_bill_day, do not include the configuration file name. If you do, depending on the restrictions in the configuration file, some bill units might never be billed.

Customizing the pin_bill_day Script for Best Pricing Options

To support best pricing, the pin_bill_day script includes the following entries for pin_bill_accts:

pin_bill_accts -discount -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -cycle_charge_only $1 $2 $3
pin_bill_accts -sponsorship -cycle_charge_only $1 $2 $3
pin_bill_accts -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -finalize_bill $1 $2 $3
pin_bill_accts -finalize_bill $1 $2 $3

$1, $2, and $3 are the parameters passed to the pin_bill_accts utility by the pin_bill_day script:

  • $1 specifies the file to read for managing the billing run.

  • $2 is the name of the billing run configuration file.

  • $3 specifies whether to collect audit revenue data by item type or not.

For more information about these parameters, see "About Bill Run Management".

You can customize the pin_bill_day script to run pin_bill_accts with the options that suit your configuration.

To Bill Subordinates before Member Discounts

If a member of the discount sharing group is also a parent of a subordinate hierarchy, you can bill subordinates before discount sharing group members by using the following sequence in the pin_bill_day script:

pin_bill_accts -pay_type 10007 -cycle_charge_only $1 $2 $3
pin_bill_accts -sponsorship -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -finalize_bill $1 $2 $3
pin_bill_accts -finalize_bill $1 $2 $3

This ensures that all subordinate accounts are billed before their parent accounts are billed.

To Bill Member Discounts before Subordinates

If a subordinate account is the owner of a discount sharing group, you can bill discount sharing group members before subordinates by using the following sequence in the pin_bill_day script:

pin_bill_accts -sponsorship -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -finalize_bill $1 $2 $3
pin_bill_accts -finalize_bill $1 $2 $3

Important:

Ensure that the billing_flow_discount parameter in the business_params object is set to 2 to specify that member discounts must be billed before parents.

This ensures that all discount sharing group members are billed before the discount sharing group owner account is billed.

To Apply Cycle Fees for Subordinates and Sponsorship Members in One Run

If you have accounts where cycle fees can be applied independently for parents and children from the subordinate and sponsorship hierarchies, you can use the following sequence in the pin_bill_day script:

pin_bill_accts -discount -cycle_charge_only $1 $2 $3
pin_bill_accts -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -finalize_bill $1 $2 $3
pin_bill_accts -finalize_bill $1 $2 $3

To Apply Cycle Fees for Subordinates, Sponsorship Members, and Discount-Sharing Group Members in One Run

If you have accounts where cycle fees can be applied independently for parents and children for all hierarchies, you can use the following sequence in the pin_bill_day script:

pin_bill_accts -cycle_charge_only $1 $2 $3
pin_bill_accts -pay_type 10007 -finalize_bill $1 $2 $3
pin_bill_accts -finalize_bill $1 $2 $3

Specifying Start and End Times

With the following billing utilities, you can specify a date range for account billing or payment collection dates:

  • pin_deposit (billing date)

  • pin_collect (payment collection date)

  • pin_cycle_fees (billing date)

For example, you can specify to run pin_deposit on accounts whose billing date falls in a particular week. You typically use date parameters when you run the billing utilities manually, but you can include them in scripts.

The default billing scripts do not use date ranges. You might need to set the date range to rerun billing, or to increase performance by limiting billing activity.

The syntax for the start and end parameters is:

-start [ mm/dd/yy or yyyy | number_of_days ]

-end [ mm/dd/yy or yyyy | number_of_days ]

You can specify the exact start and end dates, or specify a number of days before the current date for the start and end time. Note that the end date is automatically the current date if you do not specify a value for the -end parameter.

The following examples run pin_deposit for accounts that have a billing date from March 20 through March 23 if the current date is March 24:

pin_deposit -start 03/20/01 -end 03/23/01 
pin_deposit -start 4 -end 1 

If a start date is specified, the entire day is included.

If an end date is specified, that entire day is included, ending at, but not including, the 0th (first) second of the next day (00:00:00 a.m.). The end date cannot be a future date.

Setting Start and End Dates for pin_collect

The pin_collect utility collects payments for 2 days: the day before the utility is run and the day on which the utility is run: when any of the following conditions are met:

  • The start and end parameters are not set (the default).

  • The start and end parameters are set to the same value.

  • The start parameter is set to the current date, and the end parameter is not set.

To collect payments only on the day you run pin_collect, set the start parameter with a value of 0. For example:

pin_collect -start 0

You can also specify exact start and end dates, and you can specify a number of days before the current date for the start and end time calculation. The pin_collect utility only processes bills with a collection date within the start and end date range.

Note:

For open item accounting, the end date of the bill is not used to determine whether the bill falls within the specified range and qualifies for collection: only the start date is used.

Editing Billing Utility Configuration Files

All billing utilities share a common configuration file located in BRM_Home/apps/pin_billd.

Editing the Billing Scripts

To make changes to how the billing utilities run, you must edit the scripts with a text editor. Each script includes editing instructions.

For information about billing utilities, see "About the Billing Utilities". For information about billing utility syntax, see "Running Billing Utilities Manually".

Changing the Path in the Billing Scripts

The default billing scripts include a command that points to the directory that contains the billing utilities. To change the path for the billing utilities, edit the path entries in the billing scripts. For example, to change the path for the pin_bill_day script, edit these lines:

PINDIR=/opt/portal/${VERSION}
CNFDIR=${PINDIR}/apps/pin_billd
NVDIR=${PINDIR}/apps/pin_inv
OGDIR=/var/portal/${VERSION}/pin_billd
PATH=/usr/bin:/bin:${PINDIR}/bin
cd ${CNFDIR}

Testing Billing

You can test billing by running the utilities without actually generating any bill.

For regular billing, use

pin_bill_accts -test -verbose

See "pin_bill_accts".

For corrective billing, use

pin_make_corrective_bills -validate_only

See "pin_make_corrective_bills".

You can also test credit card and direct debit processing. See "Testing Paymentech Credit Card Processing" in BRM Configuring and Collecting Payments.

Running Daily Billing

The pin_bill_day script performs most of the billing operations for regular bills. See "About Running the Billing Scripts".

Use a cron job with a crontab entry to run the pin_bill_day script. The following crontab entry runs pin_bill_day at 1:00 a.m. daily:

0 1 * * * BRM_Home/bin/pin_bill_day &

Running Weekly Billing

The pin_bill_week script runs the pin_collect utility with the rebill option to process outstanding bills from active credit card or direct debit accounts that could not be collected during regular daily billing runs. This enables you to collect overdue payments.

For example, the daily billing run might return a soft decline on a BRM-initiated payment. In that case, the payment is not collected, but the bill is left open so that the pin_collect utility can attempt to collect the payment again when you run the pin_bill_week script.

Caution:

By default, the pin_bill_week script runs the pin_collect utility with the utility's end parameter set to 7. If you modify the script to run the utility with the end parameter set to 1 or 0, do not run the script at the same time that you run the pin_bill_day script. If you do, accounts whose payment collection date is on the day or the day before the utility runs may by double charged.

Use a cron job with a crontab entry to avoid conflicts with the pin_bill_month script. The following crontab entry runs pin_bill_week every Sunday at 12:05 a.m.

5 0 * * 0 BRM_Home/bin/pin_bill_week &

Running Monthly Billing

The pin_bill_month script runs the pin_collect utility with the rebill option to process outstanding bills from closed or inactive accounts.

Use a cron job with a crontab entry to run the pin_bill_month script. The following crontab entry runs pin_bill_month at 12:05 a.m. on the first day of the month:

5 0 1 * * BRM_Home/bin/pin_bill_month &

Handling Billing Failures

Billing can fail in the following cases:

  • When an internal BRM component, such as a CM or DM, goes offline.

  • When the online payment processor goes offline.

  • When a connection between BRM components is broken.

For information about troubleshooting BRM components, see "Resolving Problems in Your BRM System" in BRM System Administrator's Guide.

You handle billing failures differently depending on the billing utility that was affected, and how the failure occurred:

If the Billing Utility Was Interrupted

If the pin_collect utility or the pin_deposit utility is interrupted in progress, you can run it again. However, you might need to resolve failed BRM-initiated payment transactions. See "Resolving Failed BRM-Initiated Payment Transactions" in BRM Configuring and Collecting Payments.

All other billing utilities, pin_cycle_fees, pin_deferred_act, pin_inv_accts, and pin_bill_accts, can be run again. You do not need to resolve failed transactions.

If You Miss a Daily Billing Run

If the billing utilities were not run at all, for example, if the database was offline, you can run all of the billing utilities with no problems. The pin_bill_accts utility bills all accounts that are due for billing, not just those that are due on the day that you run the utility.

The pin_collect utility and pin_inv_accts utility act on accounts that were billed by the pin_bill_accts utility, so if you run the pin_bill_accts utility first, payments for all accounts that are due are collected or invoiced.

Running Billing Utilities Manually

You can run regular billing utilities manually or using the pin_bill_day, pin_bill_week, or pin_bill_month billing scripts. However, you must run corrective billing utilities manually. When you do, ensure that you maintain the same order as they run in the billing scripts.

When you create your test database, it's a good idea to run the billing utilities manually, by using the verbose parameter. This enables you to see whether you get the expected results.

For information on billing utilities, see "About the Billing Utilities" and the following reference pages:

  • pin_bill_accts for regular bills. Or, pin_make_corrective_bills for corrective bills

  • pin_collect

  • pin_inv_accts

  • pin_deposit

  • pin_cycle_fees

Note:

It is not possible to run multiple copies of the same billing program simultaneously.

Monitoring Billing Activity

Since billing errors can have a negative impact on your business, you must be especially vigilant in checking for errors every time you run any of the BRM billing utilities. Check the log file for the billing utilities (pin_billd.pinlog) to quickly spot any errors.

Checking for Payment-Processing Errors

BRM keeps track of transactions with BRM-initiated payment processing services, such as Paymentech, and waits for a confirmation that each transaction is processed. You should check for transaction errors daily and resolve transaction failures. See "Resolving Failed BRM-Initiated Payment Transactions" in BRM Configuring and Collecting Payments.

Maintaining Transmission Logs for Billing Transactions

The pin_collect utility creates transmission log files to record the billing transactions sent to and received from Paymentech. The files for information sent have the prefix fusas (Paymentech), and the files for information received have the prefix fusar (Paymentech).

The Paymentech transmission log files are stored in the system temporary directory. If that directory is not defined or does not exist, BRM looks for a different folder, in the following order:

  • The Directory defined by the temp_dir entry in the Paymentech DM configuration file (BRM_Home/sys/dm_fusa/pin.conf)

  • /var/tmp

  • /tmp

You must delete or archive billing transmission logs periodically to prevent the file system from overflowing. If data security is an issue, delete or archive the files to a secure location immediately after you run billing. Good business practice suggests archiving the files for at least 30 days before discarding them.