Improving Billing Performance

30 Improving Billing Performance

earn how to improve billing performance in Oracle Communications Billing and Revenue Management (BRM) by tuning billing processes or by changing business logic operations.

Topics in this document about improving the billing process:

Topics in this document about changing the business logic to improve performance:

About Billing Configuration File Entries

You can use configuration (pin.conf) file entries to tune the performance of billing applications. The entries in the billing configuration file are preceded with one of the following:

-pin_mta: These entries set the default value for all utilities, except non-MTA utilities such as pin_mass_refund and pin_recover.
The utility's name: These entries override the -pin_mta values for the specified utility.

For example, the following children and fetch_size values are used by all MTA billing utilities. The pin_collect and pin_mass_refund utilities use their own fetch_size values.

- pin_mta children 5
- pin_mta fetch_size 10000
- pin_collect fetch_size 5000
- pin_mass_refund fetch_size 8000

For billing performance issues not related to the configuration file, see "Additional Issues Related to Billing Performance".

Tuning the Number of Children for Billing Utilities

The children entry governs how many child threads will process data in parallel. Each child thread fetches and processes one account from the queue before it fetches the next account.

By default, a billing utility uses five child threads to process accounts. You can increase the number of child threads to get better billing performance when the database server remains under-utilized even though you have a large number of accounts. If you increase the number of children beyond the optimum, performance suffers from context switching. This is often indicated by higher system time with no increase in throughput.

Billing performance is best when the number of children is nearly equal to the number of DM back ends and most back ends are dedicated to processing transactions. For information on adjusting the number of DM back ends, see "Configuring DM Front Ends and Back Ends".

To tune the number of children:

Open the billing utilities configuration file (BRM_home/apps/fm_bill/pin.conf).
In the Performance Entries section, edit the children entry:
```
- pin_mta children 5
```
Save and close the file.

Tuning the Account Cache Size for Billing Utilities (fetch_size)

The fetch_size entry specifies the number of account records to retrieve from the database and hold in memory before the billing utility starts processing them. In general, this value should be as large as possible to reduce the number of fetches from the database. The maximum possible fetch size depends on the complexity of the application's search results.

When running billing for parent accounts (pay_type 10001), the fetch_size value refers to the number of parent accounts to retrieve. For example, if you have 10,000 parent accounts and each account has an average of 50 children, you would set fetch_size to 10,000 to retrieve all of the parent accounts. If you are running billing for only the children (pay_type 10007), you would set fetch_size to 500,000 to retrieve all of the child accounts.

Tip:

For best performance, use a fetch_size value that is a multiple of the per_batch value.

To tune the account cache size:

Open the billing utilities configuration file (BRM_home/apps/pin_bill_accts/pin.conf).
In the Performance Entries section, edit the fetch_size entry. For example:
```
- pin_mta fetch_size 1000000
```
Save and close the file.

Tuning the Performance for the pin_collect Utility

You can tune the performance of the pin_collect utility by using the following configuration file entries:

per_batch: This entry specifies the number of payment transactions that the pin_collect utility sends to dm_fusa in a batch. For example, if you have 20,000 payments to process and the per_batch entry is set to 5000, the pin_collect utility would send four batches to dm_fusa (with each batch containing 5,000 payment transactions).
children: This entry specifies how many child threads will process data in parallel. Each child thread fetches and processes one payment transaction from the queue before it fetches the next transaction.
fetch_size: This entry specifies the total number of payment transactions to retrieve from the database and hold in memory before pin_collect starts processing them. For pin_collect, the optimal fetch size is the number of child threads multiplied by the number of payment transactions in a batch (fetch_size = children * per_batch). For example, if the pin_collect utility has 10 child threads and a per_batch size of 5,000, you would set fetch_size to 50,000.

To tune the performance for the pin_collect utility:

Open the billing utility configuration file (BRM_home/apps/pin_billd/pin.conf).
In the Performance Entries section, add per_batch, children, and fetch_size entries for pin_collect. For example:
```
- pin_collect per_batch 5000
- pin_collect children 10
- pin_collect fetch_size 50000
```
Save and close the file.

Filtering Search Results

Some BRM operations, such as searching for group members or searching for items to include on an invoice, can return large amounts of data and cause the Data Manager to fail. In this case, use the following configuration file entries to use a step search to find accounts in charge and discount sharing groups:

group_members_fetch: Use this entry to search for members of the group sharing object when the parent group contains many members.
group_children_fetch: Use this entry to search for child accounts in groups when the parent group contains many members.
item_fetch_size: Use this entry when searching for items.

To filter search results:

Open the Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf) in a text editor.
Uncomment or enter the following lines, as needed:
```
- fm_bill group_members_fetch n
- fm_bill group_children_fetch n
- fm_bill item_fetch_size n
```
where n is the size of pool (memory in bytes) for the step search. The default value is 0.
Save and close the file.

Specifying the Number of Retries in Case of a Deadlock

For Oracle, you must specify the number of retries to be attempted in case a deadlock occurs during a billing run. For information on the deadlock error, see "Reference Guide to BRM Error Codes".

To specify the deadlock retry number:

Open the billing configuration file (BRM_home/apps/pin_billd/pin.conf).
Uncomment the - pin_bill_accts deadlock_retry_count entry.
Change the deadlock_retry_count entry, if necessary. The default is 20.
```
- pin_bill_accts  deadlock_retry_count  20
```
Save the file.

You do not need to restart the CM to enable this entry.

Ensuring the Sequence of Scheduled Actions

You can ensure that the pin_deferred_act utility processes scheduled actions for an account in the correct order by using the group_by_account entry. When enabled, the utility uses a single thread to process all scheduled actions for one account.

To ensure the sequence of scheduled actions:

Open the billing configuration file (BRM_home/apps/pin_billd/pin.conf).
Set the group_by_account entry to 1.
```
- pin_mta  group_by_account  1
```
Save the file.

You do not need to restart the CM to enable this entry.

Rearranging Accounts to Improve Billing Performance

Billing utilities fetch accounts and cache them to system memory in the same sequence in which they are stored in the BRM database.

Note:

The number of accounts fetched from the database is determined by the fetch_size entry in the billing utilities configuration file.

Each account in memory is then distributed to individual child threads (or processes) for billing. This behavior may slow billing performance because of database contention.

You can sometimes improve billing performance by rearranging accounts in system memory prior to distributing the accounts to child threads for processing by using the delta_step entry in the billing utility configuration file.

When a value is specified for this parameter, the billing utilities rearrange accounts cached in system memory based on the parameter value specified. Generally, Oracle retrieves the accounts in the order in which they are found in the database, grouped according to their physical location on the disk.

For example, we might have 100 accounts to bill and 10 threads, as well as 10 database blocks (A, B, C, D, E, F, G, H, I, and J) that each contain 10 accounts. The database returns a list that looks like this: A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, and so on for each block. When BRM starts its threads, each of the 10 threads gets the next available account to process, and the mapping might look like this:

Thread 1  - A1
Thread 2  - A2
Thread 3  - A3
Thread 4  - A4
Thread 5  - A5
Thread 6  - A6
Thread 7  - A7
Thread 8  - A8
Thread 9  - A9
Thread 10 - A10

When a thread finishes processing an account, it takes the next available account from the list, and processing continues until all accounts have been processed. As a result, all of the threads at any given time may be accessing accounts in the same database blocks and vying for the same resources.

You can change the order in which these accounts are processed using the delta_step parameter. For example, to rearrange accounts by selecting and placing every tenth account cached in system memory, and then distribute these accounts to threads for billing, set this entry to 10:

pin_billd delta_step 10

The thread mapping, instead of proceeding one account at a time, would look something like this:

Thread 1  - A1
Thread 2  - B1
Thread 3  - C1
Thread 4  - D1
Thread 5  - E1
Thread 6  - F1
Thread 7  - G1
Thread 8  - H1
Thread 9  - I1
Thread 10 - J1

The delta_step parameter makes it possible for each thread to be working on data from a different area of the database, reducing contention for the same resources and improving billing performance.

You can determine the optimal setting for the delta_step parameter by testing the billing processes and monitoring their performance. By default, this parameter is set to 0, which means that the accounts cached in system memory are not rearranged before distribution.

To rearrange accounts in system memory:

Open the billing utility configuration file (BRM_home/apps/pin_billd/pin.conf).
In the Performance Entries section, edit the delta_step entry. For example:
```
- pin_billd delta_step 10
```
Save and close the file.

Additional Issues Related to Billing Performance

To reduce system load, you can split large billing runs into smaller billing runs. See "Splitting a Billing Run into Multiple Runs" in BRM Configuring and Running Billing.
You can improve performance of the pin_bill_accts utility by excluding accounts that do not need to be billed. For more information, see "About Suspending Billing of Accounts and Bills" in BRM Configuring and Running Billing.
When you run the pin_collect utility, you can improve performance by archiving the temporary transmission logs created by the DM for the credit card processing service. See "Checking Paymentech Transmission Log Files" in BRM Configuring and Collecting Payments for more information about the transmission log files.
You can create billing-related indexes just before you run billing and then delete them when billing finishes. You can add these tasks to the billing scripts. See "Running Billing Scripts" in BRM Configuring and Running Billing and "Removing Unused Indexes".

How the Number of Events Affects Billing

The number of events has no effect on billing or invoicing except in the following cases:

If you defer tax calculations, billing performance is slower.
If you create detailed invoices, performance is slower. A telephone usage invoice is an example of a detailed invoice; a fixed-fee cable subscription invoice is an example of a nondetailed invoice.

Improving Performance in Retrieving Purchased Offerings for a Bill Unit

You can improve billing performance while retrieving purchased charge offers and discount offers for a bill unit (/billinfo object) from the database by specifying the batch size of the number of services to search at a time.

To enable this feature, run the pin_bus_params utility to change the MaxServicesToSearch business parameter. For information about this utility, see "pin_bus_params" in BRM Developer's Guide.

To specify the batch size of the number of services to search:

Go to BRM_home/sys/data/config.

Create an XML file from the /config/business_params object:

pin_bus_params -r Subscription bus_params_subscription.xml

In the file, specify the batch size of the number of services:
```
<MaxServicesToSearch>5</MaxServicesToSearch>
```
Save the file as bus_params_subscription.xml.

Load the XML file into the BRM database:

pin_bus_params bus_params_subscription.xml

Stop and restart the CM.

Improving Performance by Skipping Previous Total Unpaid Bill for Open Item Accounting Type

You can configure BRM to skip the previous total unpaid bill for the open item accounting type when calculating the current bill. Using this business parameter, you can reduce the time taken for calculating the current bill for the open item accounting type.

To enable this feature, run the pin_bus_params utility to change the PerfAdvanceTuningSettings business parameter. For information about this utility, see "pin_bus_params" in BRM Developer's Guide.

To configure BRM to skip the previous total unpaid bill for the open item accounting type when calculating the current bill:

Go to BRM_home/sys/data/config.

Create an XML file from the /config/business_params object:

pin_bus_params -r BusParamsBilling bus_params_billing.xml

In the file, change 0 to 8:

<PerfAdvancedTuningSettings>8</PerfAdvancedTuningSettings>

Save the file as bus_params_billing.xml.
Load the XML file into the BRM database:
```
pin_bus_params bus_params_billing.xml
```
Stop and restart the CM.

Improving Trial Billing Performance by Enabling General Ledger Collection

You can configure BRM to enable the general ledger (G/L) collection for trial billing by setting the PerfAdvancedTuningSettings business parameter to 64. Using this value, you can collect the G/L data required for creating trial invoices.

To enable the G/L collection for trial billing:

Use the following command to create an editable XML file from the billing instance of the /config/business_params object:
```
pin_bus_params -r BusParamsBilling bus_params_billing.xml
```
This command creates the XML file named bus_params_billing.xml.out in your working directory. To place this file in a different directory, specify the full path name for the file. For more information on this utility, see "pin_bus_params" in BRM Developer's Guide.
Open the bus_params_billing.xml.out file.
Search for PerfAdvancedTuningSettings.
Add 64 (0x40, set Bit 6) to the existing value of PerfAdvancedTuningSettings.

For example, if the existing value is 0, change it to 64 (0+64):
```
<PerfAdvancedTuningSettings>64</PerfAdvancedTuningSettings>
```
For more information on the parameter values, see the PerfAdvancedTuningSettings parameter description in Table 63-2.

Caution:

BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM subscription configurations.
Save the file as bus_params_billing.xml.
Go to the BRM_home/sys/data/config directory which includes support files used by the pin_bus_params utility.
Use the following command to load this change into the appropriate /config/business_params object.
```
pin_bus_param_ pathToWorkDirectory/bus_params_billing.xml
```
where pathToWorkingDirectory is the directory in which bus_params_billing.xml resides.

Note:

To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
Read the object with the testnap utility or Object Browser to verify that all fields are correct.
Stop and restart the CM.

Excluding Searches on Closed Offerings

By default, BRM retrieves active, inactive, and closed offerings during the billing process. However, most of the time, BRM does not use the data from the closed offerings.

You can configure BRM to retrieve only the active and inactive offerings by running the pin_bus_params utility to change the CancelledOfferingsSearch business parameter. For information about this utility, see "pin_bus_params" in BRM Developer's Guide.

To disable searches on closed offerings:

Go to BRM_home/sys/data/config.

Create an XML file from the /config/business_params object:

pin_bus_params -r BusParamsSubsription bus_params_subscription.xml

In the file, change disabled to enabled:

<CancelledOfferingsSearch>enabled</CancelledOfferingsSearch>

Save the file as bus_params_subscription.xml.

Load the XML file into the BRM database:

pin_bus_params bus_params_subscription.xml

Stop and restart the CM.

Improving Performance by Skipping Previous Total for Open Item Accounting Type When Calculating the Current Bill

Note:

To configure this option, you configure business profiles. For general information about business profiles, see "Creating and Managing Business Profiles" in BRM Managing Customers

By default, the previous unpaid bill is calculated even for open item accounting types when calculating the current bill for a bill unit (/billinfo object), but the final bill does not include the previous unpaid amount. This is a time-consuming process as it involves checking all previous bill items.

To improve performance, you can configure BRM to skip calculating the previous total unpaid bill for open item accounting types.

Note:

To make this performance improvement for all bill units system-wide, see "Improving Performance by Skipping Previous Total Unpaid Bill for Open Item Accounting Type".

To skip the previous total for open item accounting type when calculating the current bill:

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

By default, the file is located in BRM_home/sys/data/config.
Set the following business profile key to Yes:
```
<NameValue key="Skip_Prev_Total" value="Yes"/>
```
where:
- Yes specifies to not calculate the previous unpaid bill amount when calculating the current bill.
- No specifies to calculate the previous unpaid bill amount when calculating the current bill. This is the default behavior when the entry is not in the file.
Save and close the file.
Run the following command, which loads the updated contents of the pin_business_profile.xml file into the BRM database:
```
load_pin_business_profile -v pin_business_profile.xml
```
Read the object with the testnap utility or Object Browser and verify your changes.

For general instructions on using testnap, see "testnap" in BRM Developer's Guide.
Stop and restart the CM.

Improving Performance by Using Multiple Item Configurations

Note:

To configure this option, you configure business profiles. For general information about business profiles, see "Creating and Managing Business Profiles" in BRM Managing Customers

By default, BRM uses the same item-tag-to-item-type mapping (item configuration) for all bill units in the system. The item configuration is used to assign bill items to events during the rating process; it also specifies which bill items are pre-created at the beginning of each billing cycle. For more information about item configuration, see "Creating Custom Bill Items" in BRM Configuring and Running Billing.

Using the same item configuration for all bill units can degrade performance by unnecessarily pre-creating bill items for certain types of bill units. For example, the default item configuration might pre-create cycle forward and cycle arrears items, which are normally used to track charges for postpaid bill units but are typically not required for prepaid bill units. Pre-creating such items for prepaid bill units needlessly consumes database storage space and takes more time to process during billing.

To generate fewer bill items, you can create multiple item configurations in your system and then assign the appropriate item configuration to each bill unit.

To assign an item configuration to a bill unit:

Create the appropriate item configuration for the bill unit.

To create multiple item configurations, see "Setting Up BRM to Assign Custom Bill Items to Events" in BRM Configuring and Running Billing.
Open the pin_business_profile.xml file in an XML editor or a text editor.

By default, the file is located in BRM_home/sys/data/config.
In the business profile associated with the bill unit, add the following key-value pair if it does not already exist, and set the value to the name of the appropriate item configuration:
```
<NameValue key="Item_Configuration" value="Item_Configuration_Name"/>
```
where Item_Configuration_Name is the name of the item configuration to which you want to assign the bill unit. The name of the default item configuration is Default.

Item configuration names are specified in the PIN_FLD_NAME field of /config/item_tags and /config/item_types objects. A pair of those objects with matching PIN_FLD_NAME values exists for each item configuration defined in your system. For more information, see "Setting Up BRM to Assign Custom Bill Items to Events" in BRM Configuring and Running Billing.

Note:

Modifying the business profile affects all bill units associated with the business profile.
Save and close the file.
Run the following command, which loads the updated contents of the pin_business_profile.xml file into the BRM database:
```
load_pin_business_profile -v pin_business_profile.xml
```
Read the object with the testnap utility or Object Browser and verify your changes.

For general instructions on using testnap, see "testnap" in BRM Developer's Guide.
Stop and restart the CM.

Improving Item Search Performance

If an account's paying bill unit has nonpaying child bill units, BRM performs a step search to find items. By default, BRM returns 1000 items with each step of the search.

To customize the number of items returned:

Open the Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf).
Change the value of the item_search_batch entry.

For example, to set the number of returned items to 2000:
```
- fm_bill item_search_batch 2000
```
To not use step-search, set the value to 0.

Note:

If your paying bill unit has a large hierarchy, bypassing step-search can cause the Data Manager (DM) to run out of memory.
Save and close the file.

Use larger batch search memory sizes to improve run-time performance. You do not need to restart the CM to enable this entry.

Improving Performance by Skipping Billing-Time Tax Calculation

Note:

To configure this option, you configure business profiles. For general information about business profiles, see "Creating and Managing Business Profiles" in BRM Managing Customers.

In some cases, such as for prepaid accounts, taxes do not need to be calculated at billing time. If your system is configured to calculate billing-time taxes, you can improve billing performance by skipping billing-time tax calculation for individual bill units when it is not needed.

Note:

To skip billing-time tax calculation for a bill unit, you configure the bill unit's business profile. Modifying the business profile affects all bill units associated with the business profile.
If a bill unit hierarchy is configured to have billing-time taxes calculated for the entire hierarchy when the paying parent bill unit is billed, do not configure the paying parent bill unit to skip billing-time tax calculation. BRM ignores the skip billing-time tax calculation setting for nonpaying bill units in such hierarchies.

To skip billing-time tax calculation for individual bill units:

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

By default, the file is located in BRM_home/sys/data/config.
In a business profile associated with bill units whose taxes you do not want to calculate at billing time, add the following key-value pair if it does not already exist, and set the value to Yes:
```
<NameValue key="Skip_Deferred_Taxation" value="Yes" />
```
where:
- Yes specifies to not calculate taxes for individual bill units at billing time.
- No specifies to calculate taxes for individual bill units at billing time. This is the default behavior when the entry is not in the file.
Save and close the file.
Run the following command, which loads the updated contents of the pin_business_profile.xml file into the BRM database:
```
load_pin_business_profile -v pin_business_profile.xml
```
Read the object with the testnap utility or Object Browser and verify your changes.

For general instructions on using testnap, see "testnap" in BRM Developer's Guide.
Stop and restart the CM.