Advanced Configuration for Recurring Charges

20 Advanced Configuration for Recurring Charges

Learn how to configure advanced functionality for recurring charges in Pricing Design Center (PDC) for Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

Configuring Flexible Cycle Forward Charges

By default, BRM supports monthly, bimonthly, quarterly, semi-annual, and annual cycle forward charges. You can also configure BRM to support flexible cycle forward charges. Flexible cycle forward charges can use daily, weekly, monthly, or multimonth cycles that are not restricted to billing or accounting cycles.

You can use flexible cycle forward charges to grant free balances, provide discounts, or charge fees at any time during the accounting cycle. For example, you can set up a cycle forward fee to grant minutes every week or every day rather than once a month. Or you can set up a monthly cycle forward fee to grant minutes on the 15th of every month, which differs from the monthly accounting cycle that begins on the 1st of every month.

Because flexible cycles are not aligned with accounting cycles, cycle forward fees are always prorated.

You set up flexible cycle forward charges by configuring flexible cycle forward events.

To set up flexible cycles:

Define a custom cycle forward event subclass using Storable Class Editor in Developer Center. The name of the custom cycle forward event must use this syntax:
```
/event/billing/product/fee/cycle/cycle_forward_customName
```
where customName is your custom name for the event subclass. For example, create /event/billing/product/fee/cycle/cycle_forward_10days to define a cycle forward event that occurs every ten days.

Note:

Use the /event/billing/product/fee/cycle/cycle_forward_quarterly object specification as a model.
Map the new event to a valid purchase level:
1. In the service-event map configuration file (BRM_home/sys/data/pricing/example/pin_event_map), add an entry for the new cycle forward event. The entry must use the following format:
```
purchase_level:event_type:event_description:count: unit
```
  where:
  - count specifies the frequency of the cycle. It must be a positive number.
  - unit must be day, week, month, or year.
  For example, to map a biannual (24-month duration) cycle forward event to an account purchase type, the pin_event_map entry is:
```
/account:/event/billing/product/fee/cycle/cycle_forward_biannual:Biannual Cycle Forward Event:24:month
```
  or
```
/account:/event/billing/product/fee/cycle/cycle_forward_biannual:Biannual Cycle Forward Event:2:year
```
  See "Creating Service and Event Storable Classes" in BRM Developer's Guide.
2. Run the load_event_map utility.
Map the new event type to a valid ratable usage metric (RUM):
1. In the usage map configuration file, add an entry for the new cycle forward event. For example:
```
/event/billing/product/fee/cycle/cycle_forward_biannual:Occurrence: 0: 0: 0: 0: 0: 0: 0: cycle_forward_biannual
```
2. Run the load_usage_map utility.
Stop and restart the CM.
Use PDC to create charge offers that include your new cycle forward fee.

Charging Cycle Forward Fees Associated with Flexible Cycles

Cycle forward fees are charged when you run monthly billing or the pin_cycle_forward billing utility.

When a cycle forward event is generated, balance impacts are applied using balance validity dates.

If a cycle forward event balance impact for a noncurrency balance is set up with a relative cycle start date, balance impacts are applied either to the current cycle or to a future cycle.

For example, if the relative cycle is set to 1 and the cycle is from January 1 to March 1, a sub-balance is created with a validity period from January 1 to March 1. If the relative cycle is set to 2, a sub-balance is created with a validity period from March 1 to May 1.

Applying Cycle Forward Fees in Parallel

For accounts with multiple services (for example, a wholesale market customer account), you can configure BRM to apply cycle forward fees in parallel for multiple services instead of applying cycle forward fees sequentially for each service, thereby reducing the time to complete billing.

When you configure BRM to apply cycle forward fees in parallel, you can also configure BRM to:

Enforce cycle fee processing prior to billing. By doing so, BRM eliminates the process of applying cycle forward fees during billing and improves the performance of the billing process.
Use a single item at the account level to accumulate the cycle charges for all the services. By doing so, BRM reduces the number of items to process and improves overall system performance, which is important when you bill for wholesale customer accounts. When BRM applies cycle forward fees in parallel with service charges aggregated to a single account item, the account can have only a single bill unit (/billinfo object). Even though the account item aggregates the service charges, the respective service balance groups are still updated with the service charges.

Before configuring BRM to apply cycle forward fees in parallel, your configuration must meet these requirements:

The number of services attached to a single balance group must be less than 10 in order to get the performance benefit of applying cycle forward fees in parallel.
There should be no dependency on the order of applying cycle forward fees for account groups (hierarchical, charge sharing, or discount sharing). This is because the cycle forward fees are applied by the pin_cycle_fees utility instead of by the billing application that gives more control on the order of processing accounts in hierarchies.

Applying parallel cycle forward fees involves the following processes:

Running the pin_cycle_fees utility in parallel at the services level, which processes cycle forward fees aligned to the accounting cycle.

Note:

When the parallel fee processing feature is enabled, cycle forward fees are applied by the pin_cycle_fees utility, which is run before the pin_deferred_act utility. However, when the parallel cycle forward fees processing fees feature is not enabled, cycle forward fees are applied by the billing application after running pin_deferred_act.
Running the pin_update_journals utility to post-process cycle forward fees.
Running the pin_bill_accts utility for regular billing.
Running the pin_cycle_fees utility to process flexible cycle forward fees.
Running the pin_update_journals utility to post-process flexible cycle forward fees.

To configure BRM to apply cycle forward fees in parallel, run the pin_bus_params utility to change the StagedBillingFeeProcessing business parameter. For information about this utility, see "pin_bus_params" in BRM Developer's Guide.

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

Search for this line:
```
<StagedBillingFeeProcessing>0</StagedBillingFeeProcessing>
```
The default is 0. (BRM applies the cycle forward fees as part of the billing process.)

Note:

The cycle fee processing at the time of billing is only with reference to the cycle forward fees aligned with the accounting cycle boundary.
Do one of these:
- To apply cycle forward fees in parallel by service, specify 1.
- To enforce cycle fee processing prior to billing and apply cycle forward fees in parallel by service, specify 2.
- To apply cycle forward fees in parallel by service with service charges aggregated to a single account item, specify 3.
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.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

About Enforcing Cycle Forward Fee Processing Prior to Billing

When BRM enforces cycle fee processing prior to billing, the following processes are impacted:

The pin_cycle_fees utility performs additional error processing to set the error status (as needed) on the corresponding bill unit

Note:

If you customize pin_cycle_fees and use the application global structure PIN_FLD_EXTENDED_INFO provided by the multithreaded application framework to hold custom information at run time, you must consider that pin_cycle_fees stores the error processing information in a single array element PIN_FLD_ERROR_INFO under PIN_FLD_EXTENDED_INFO.
The billing process stops if any of the following conditions is true:
- The BILLING_STATUS_FLAGS field of the /billinfo object indicates that there was an error processing one of the cycle forward fees.
- There is at least one service for which cycle fee processing (regular, deferred, deferred purchase, or deferred cancellation) has not been completed for the accounting cycle being billed.
In rare cases, if billing is due for a bill unit for more than one accounting cycles, special handling is required. See "Handling Skipped Billing" for more information.

About Aggregating Service Charges to Account Items

When applying cycle forward fees in parallel by service with service charges aggregated to a single account item, multiple threads of pin_cycle_fees updates a single item. To avoid updating the same item by multiple threads, pin_cycle_fees logs the item and journal updates to temporary tables as follows:

Logs item updates to the /tmp_events_to_process object in the TMP_EVENTS_TO_PROCESS_T table.
Logs journal updates to the /tmp_journals_to_process object in the TMP_JOURNALS_TO_PROCESS_T table.

The pin_update_journals utility processes the temporary item and journal data and updates the main item and journal tables.

To ensure efficient access of these temporary tables, Oracle recommends the following:

Resetting high water mark. Records are frequently inserted into and deleted from the temporary tables, which can fragment the temporary tables. Reset the high water mark for the temporary tables as the BRM schema user.

Run these commands every time before calling the pin_bill_accts inside the pin_bill_day script.
```
ALTER TABLE TMP_JOURNALS_TO_PROCESS_T ENABLE ROW MOVEMENT;
ALTER TABLE TMP_JOURNALS_TO_PROCESS_T SHRINK SPACE; 
ALTER TABLE tmp_events_to_process_t ENABLE ROW MOVEMENT; 
ALTER TABLE tmp_events_to_process_t SHRINK SPACE;
```
For more information about the high water mark, see the Oracle Database documentation.

Presetting statistics. Preset the statistics of the temporary tables that are created during BRM installation by running the following commands as a one-time activity. This enables BRM to avoid a full scan of these tables.

Exec dbms_stats.set_table_stats('SCHEMA_NAME','TMP_EVENTS_TO_PROCESS_T','','','',200000000,40000000,1250) ;

Exec dbms_stats.set_index_stats('SCHEMA_NAME','I_TMP_EVENTS_ID','',numrows=>200000000,numlblks=>1000000,numdist=>200000000,avglblk=>1,avgdblk=>1,clstfct=>200000000);

Exec dbms_stats.set_column_stats('SCHEMA_NAME','TMP_EVENTS_TO_PROCESS_T','POID_ID0','',distcnt=>200000000,density=>1/200000000,nullcnt=>0,srec=>srec_eve,avgclen=>11); 

Exec dbms_stats.set_table_stats('SCHEMA_NAME','TMP_JOURNALS_TO_PROCESS_T','','','',200000000,40000000,1250);

Exec dbms_stats.set_index_stats('SCHEMA_NAME','I_TMP_JOURNALS_ID','',numrows=>200000000,numlblks=>1000000,numdist=>200000000,avglblk=>1,avgdblk=>1,clstfct=>200000000);

Exec dbms_stats.set_column_stats('SCHEMA_NAME','TMP_JOURNALS_TO_PROCESS_T','POID_ID0','',distcnt=>200000000,density=>1/200000000,nullcnt=>0,srec=>srec_eve,avgclen=>11);

Exec dbms_stats.lock_table_stats('SCHEMA_NAME','TMP_EVENTS_TO_PROCESS_T');
Exec dbms_stats.lock_table_stats('SCHEMA_NAME','TMP_JOURNALS_TO_PROCESS_T');

where SCHEMA_NAME is the BRM database user; for example, pin1.

Handling Skipped Billing

In rare cases, if billing is due for a bill unit for more than one accounting cycles, special handling is required. This multiple cycle overdue billing is referred to as skipped billing.

For example, assume that the current date is December 1 and BRM did not perform billing for the cycles ending November 1 and October 1. In this case, when you run pin_bill_day on the current date, three bills are due to be created.

When BRM tries to calculate the cycle forward fees, the following happens:

pin_cycle_fees applies cycle forward fees due only as of October 1 because October 1 billing has not been processed yet.
pin_bill_accts performs billing only on October 1 and stops with an error when performing billing on November 1 because cycle forward fees due as of November 1 have not been processed yet.

To handle the case of skipped billing used in this example:

Run pin_cycle_fees, pin_update_journals, and pin_deferred_act in the following sequence:

pin_cycle_fees -defer_purchase
pin_cycle_fees -defer_cycle_fees
pin_cycle_fees -defer_cancel
pin_cycle_fees -regular_cycle_fees
pin_update_journals
pin_deferred_act

Run pin_bill_accts.
Repeat step 1 and step 2 twice more, which performs billing for November 1 and December 1.

Using the pin_bill_day Script to Apply Parallel Cycle Forward Fees

To support applying cycle forward fees in parallel, the pin_bill_day script includes the following commented out sections:

Pre-Billing Parallel Cycle Fee Processing: Includes the following entries for pin_cycle_fees and pin_update_journals:

##### pin_cycle_fees -defer_purchase
##### pin_cycle_fees -defer_cycle_fees
##### pin_cycle_fees -defer_cancel
###### pin_cycle_fees -regular_cycle_fees
##### pin_update_journals

Post-Billing Parallel Cycle Fee Processing: Includes the following entry for pin_update_journals:
```
##### pin_update_journals
```

To apply cycle forward fees in parallel by using the pin_bill_day script:

Make sure that the StagedBillingFeeProcessing parameter is not set to 0.
Open the BRM_home/bin/pin_bill_day script in a text editor.

Uncomment these entries in the Pre-Billing Parallel Cycle Fee Processing section:

##### pin_cycle_fees -defer_purchase
##### pin_cycle_fees -defer_cycle_fees
##### pin_cycle_fees -defer_cancel
###### pin_cycle_fees -regular_cycle_fees
##### pin_update_journals

Uncomment this entry in the Post-Billing Parallel Cycle Fee Processing section:
```
##### pin_update_journals
```
Save and close the file.
Run pin_bill_day.

About Limitations and Impacts of Applying Cycle Forward Fees in Parallel

Configuring BRM to apply cycle forward fees in parallel includes these limitations and impacts:

In rare cases, when the pin_cycle_fees utility successfully creates temporary item and journal data and the subsequent run of the pin_update_journals utility fails to update the item and journal tables, you must investigate and correct the problem in processing the temporary item and journal data before performing any accounts receivable action or generating ledger reports.
If the parallel fee processing feature is configured to enforce cycle fee processing before billing, balance impact events that occur before the pin_cycle_fees utility runs are cancelled with an error.
If the parallel fee processing feature is not configured to enforce cycle fee processing before billing, balance impact events that occur before the pin_cycle_fees utility runs result in triggered billing that can be slow due to serial application of cycle forward fees.
Performance of the following operations is not improved because parallel cycle fee processing does not apply to these operations:
- Trial billing
- Bill Now
- Billing on purchase
- Account creation
- Purchase of bundles
- Billing time discount
- Cycle fold
- Rollover
- Account activation, account inactivation, or account cancellation
- Rerating

Applying Recurring Charges Based on Charge Offer Priority

When multiple charge offers in a bundle include recurring charges, you can configure BRM to apply recurring charges in the order of charge offer priority. You can apply recurring charges based on charge offer priority during the following operations:

Bundle purchase or cancellation, for all the charge offers per bundle.
Billing, for all the charge offers in a bundle per bill unit.

Important:

This parameter does not prioritize charge offers for recurring charges applied by pin_cycle_fees -defer_cancel and does not prioritize customized charge offers.

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

To apply recurring charges based on charge offer priority:

Go to BRM_home/sys/data/config.

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

pin_bus_params -r BusParamsSubscription bus_params_subscription.xml

In the file, change disabled to enabled:

<UsePrioritySubscriptionFees>enabled</UsePrioritySubscriptionFees>

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.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Customizing the Cycle Interval for Specified Charge Offers

To customize the time interval for applying cycle forward and cycle arrears fees for a specified charge offer, use the PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL policy opcode.

This policy opcode is called by PCM_OP_SUBSCRIPTION_CYCLE_FORWARD and PCM_OP_SUBSCRIPTION_CYCLE_ARREARS. The type of cycle event is passed in the PIN_FLD_SCOPE field in the input flist.

By default, this policy opcode is an empty hook to facilitate customization of the cycle forward and cycle arrears start (CHARGED_FROM_T) and end dates (CHARGED_TO_T) for a specific charge offer. The start and end dates provided are used to calculate the scale to determine the cycle fee amount to charge or refund.

For example, if a charge offer is purchased on April 1, 2009 with a monthly cycle forward fee of $30 and the purchase, usage, and cycle end dates are set to April 20, 2009, the cycle fee amount is based on the scale for the period April 1, 2009 to April 20, 2009 (20 days) divided by the unit interval from April 1, 2009 to April 30, 2009 (30 days). The cycle fee charged is 20/30 * $30, or $20.

If the charge offer is canceled on April 15, 2009, the refund amount is based on the scale for the period April 15, 2009 to April 20, 2009 (5 days) divided by the unit interval from April 1, 2009 to April 20, 2009 (20 days). Because the refund amount is refunded from the charged amount ($20), the refund is 5/20 * (20/30 * $30), or $5. Here, the scale value 20/30 is the original charge scale or the period the charge offer was valid during the cycle.

The PIN_FLD_SCALE value in the input and output flists is the original charge scale and is used only to calculate the refund scale.

To change the scale (for example if you do not want to refund the full amount), change the start and end dates. The refund scale is calculated based on the dates that you provide.