Managing Large Billing Runs

14 Managing Large Billing Runs

Learn how to manage large billing runs in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

Implementing these features includes editing the billing run configuration file (pin_bill_run_control.xml).

When splitting a billing run or using customized due dates, you must run the pin_bill_day script manually. See "Running the pin_bill_day Script for Bill Run Management".

Billing Only Specified Accounts and Bill Units

To bill a single account or a limited set of accounts with the pin_bill_day script, you specify the accounts and their bill units in a modified version of the billing run configuration file (pin_bill_run_control.xml). In this case, BRM does not perform a database search but retrieves the account and bill unit information directly.

Note:

If you specify a paying bill unit that is part of a bill unit hierarchy, ensure that all nonpaying bill units are billed first.

Open the BRM_home/apps/pin_billd/pin_bill_run_control.xml file.
Edit the file to specify the accounts and their bill units to bill.

Add an Account and Billinfo child element to the BillingList parent element for each account and bill unit to include. In the child element, specify the POID of the account and bill unit.

Note:

To 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 billed.

A BillingList parent element looks like this:
```
<BillingList>
    <Account>Account_POID</Account>
    <Billinfo>Bill_unit_POID</Billinfo>
</BillingList>
```
For example, the following BillingList parent element generates bills only for the account with POID 55612 and its bill unit with POID 34589:
```
<BillingList>
    <Account>55612</Account>
    <Billinfo>34589</Billinfo>
</BillingList>
```
(Optional) Delete or comment out any billing DOM lists or billing segment lists (specified by DOMList and BillSegmentList parent elements). If you include accounts and bill units along with DOMs or billing segments, only the account's bill units are processed.
Save the file under a different name and close it. For example, when billing a single account, include the account POID in the file name (such as pin_bill_run_account_8445.xml). If billing a group of accounts, include the account range or reason for billing in the file name.

Note:

When you run pin_bill_day, the default BRM_home/apps/pin_billd/business_configuration.xsd file and filename must be in the same directory.
Manually run the pin_bill_day script using this command:
```
pin_bill_day -file filename
```
where filename is the name and location of the modified version of the billing run configuration file. If the file is in a different directory from which you run the pin_bill_day script, you must also include the entire path for the file.
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 parameter.
- 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. See "Setting Up Billing in a Multischema Environment".
- When you run pin_bill_day with the -file parameter, do not run it as a cron job. If you do, depending on the restrictions in filename, some bill units might never be billed.

Splitting a Billing Run into Multiple Runs

When you use the pin_bill_day script to run billing, the billing run includes all bill units whose current accounting-cycle end date is any day before midnight (12:00:00 a.m.) of the day on which the billing run takes place.

To reduce the load and duration of billing runs triggered by the script, you can split large, lengthy billing runs into smaller billing runs based on billing days of month (DOMs) and billing segments. The smaller billing runs can overlap or occur at different times.

Splitting a billing run into multiple runs includes two steps:

Configure auto-triggered billing.
Configure the split billing run.

Configuring Auto-Triggered Billing for Bill Run Management

To split large billing runs into smaller billing runs, you first disable auto-triggered billing on the days that you process the smaller billing runs. If auto-triggered billing is enabled on those days, it reduces your ability to control the way your billing load is distributed.

For example, the billing cycle for two million customers ends on August 1. To reduce the number of bills finalized on August 1, you split the billing run into four smaller runs, each of which includes about 500,000 bill units. You process one smaller billing run per day from August 1 through August 4. If auto-triggered billing is enabled on those days, bill-triggering events might cause BRM to finalize some bills in the smaller billing runs before you process the runs. For example, bill-triggering events might cause BRM to finalize 1,250,000 bills on August 1 instead of only 500,000.

To configure auto-triggered billing for bill run management:

Set a system-wide billing delay. See "Setting Up Delayed Billing".

By default, auto-triggered billing is always enabled. To disable it, you must set a billing delay in your BRM system.

Note:

If you use delayed billing, skip this step. A billing delay is already set in your system. For more information, see "Setting Up Delayed Billing".

By default, after you set a billing delay, auto-triggered billing is enabled for only the delay period and the last two days of each bill unit's accounting cycle.

For example, if your delayed billing cycle is 7 days long, auto-triggered billing is disabled during the following days in a 31-day accounting cycle as shown in Figure 14-1.

Figure 14-1 Auto-Triggered Billing Disabled in Accounting Cycle

Description of "Figure 14-1 Auto-Triggered Billing Disabled in Accounting Cycle"

Note:

If a bill-triggering event occurs during the delayed-billing period, the bill is only partially processed: rollovers and cycle fees are applied, but the bill is not finalized. If a bill-triggering event occurs during the last two days of the cycle, the bill is finalized.
(Optional) Change the number of days auto-triggered billing is enabled at the end of each accounting cycle. See "Configuring Auto-Triggered Billing".

Configuring a Split Billing Run

To split a billing run into smaller billing runs, you configure the smaller billing runs in multiple versions of the billing run configuration file (pin_bill_run_control.xml). Each of the smaller billing runs is limited to bill units associated with one or both of the following:

Specified accounting days of month (DOMs). Bill units associated with any other billing DOM are excluded from the billing run.
Specified billing segments. Bill units associated with any other billing segment are excluded from the billing run.

To restrict the smaller billing runs to specified billing segments, you must first set up billing segments in your system and then associate bill units with them. See "Load Balancing Billing Runs".
Note:

When you split a large billing run into smaller billing runs:
- Configure the smaller billing runs so that in total they include all due bill units.
- To ensure that no bill unit remains unbilled, periodically run the pin_bill_day script without the -file parameter.
- Do not include the same billing segment in multiple small billing runs. If you do, your accounts receivable (A/R) data may become inaccurate.

To split a billing run into smaller billing runs:

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.

Note:

You also edit this file to specify billing run-time due date adjustments. See "Specifying Due Date Adjustments in a Billing Run".
Edit the file to restrict a billing run to bill units associated with one of the following:
- For specific billing DOMs, see "Including Only Specified Billing DOMs in Billing Runs".
- For specific billing segments, see "Including Only Specified Billing Segments in Billing Runs".
  
  Note:
  
  Only one smaller billing run at a time can be configured in a billing run configuration file.
Save the file.

Note:

To create multiple versions of this file, save the file under a different name for each of the smaller billing runs. For example, if a version of the file limits a smaller billing run to billing segment 1001, save the file as pin_bill_run_control_BS1001.xml. The pin_bill_day script can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition. See "Validating Your Billing Run Configuration File Edits".
Repeat steps 1 through 3 as often as necessary to configure a set of smaller billing runs that includes all due bill units in a daily billing run.
Manually run the pin_bill_day script with each version of the XML file by using this command:
```
pin_bill_day -file filename
```
where filename is the name and location of a version of the billing run configuration file. If you run the command in a different directory from where filename is located, you must also include the entire path for the file.

In addition, filename must be in the same directory as the default BRM_home/apps/pin_billd/business_configuration.xsd file.
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 parameter.
- 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. See "Setting Up Billing in a Multischema Environment".
- When you run pin_bill_day with a configuration file, do not run it as a cron job. If you do, depending on the restrictions in configuration file, some bill units might never be billed.

About Sponsored Charges in Split Billing Runs

If the following conditions occur when you split a billing run, sponsored cycle forward charges might appear in the sharing group owner's bill one cycle late:

Sharing group owner account and member account have the same billing DOM.
Sharing group owner account and member account belong to different billing segments.

Including Only Specified Billing DOMs in Billing Runs

To include bill units associated only with specified billing DOMs in a billing run, add a DOM child element to the DOMList parent element in the billing run configuration file for each day whose bill units you want to include.

A DOMList parent element looks like this:

<DOMList>
    <DOM>---gDay1</DOM>
    <DOM>---gDay2</DOM>
    <DOM>---gDay3</DOM>
</DOMList>

where gDay is any two-digit value from 01 through 31.

For example, to include only bill units whose billing DOM is 1 or 15, add child elements:

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

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

Including Only Specified Billing Segments in Billing Runs

To include bill units associated only with specified billing segments in a billing run, add a BillSegment child element to the BillSegmentList parent element in the billing run configuration file for each billing segment whose bill units you want to include.

A BillSegmentList parent element looks like this:

<BillSegmentList>
    <BillSegment>ID</BillSegment>
    <BillSegment>ID</BillSegment>
    <BillSegment>ID</BillSegment>
</BillSegmentList>

where ID is the ID of any billing segment defined in the /config/billing_segment object in your BRM system.

For example, to include only bill units associated with billing segments 101 or 102, add child elements:

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

For information about billing segments, see "Load Balancing Billing Runs".

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

Sample Billing Run Configuration File

The following is a sample pin_bill_run_control.xml file. Billing run loads are restricted to billing DOMs and billing segments specified in the bold elements.

<DOMList>
    <DOM>---03</DOM>
    <DOM>---07</DOM>
    <DOM>---15</DOM>
</DOMList>
<BillSegmentList>
    <BillSegment>101</BillSegment>
    <BillSegment>102</BillSegment>
</BillSegmentList>
<DueDateAdjustment Length=5 >
    <PaymentTerm id = 1001 />
    <PaymentTerm id = 1002 />
</DueDateAdjustment>
<DueDateAdjustment Length = 7/>

For information about the DueDateAdjustment and PaymentTerm elements, see "Specifying Due Date Adjustments in a Billing Run".

Validating Your Billing Run Configuration File Edits

After editing the XML file, you use the file name as a parameter when you run the pin_bill_day script. The script passes the file name to the pin_bill_accts utility, which validates the contents of the XML file against its schema definition. If the contents do not conform to the schema definition, the utility returns an error. The schema definition is BRM_home/xsd/pin_bill_run_control.xsd.

The XML file is not directly linked to its schema definition file. Instead, it is linked to the BRM_home/sys/data/config/business_configuration.xsd reference file.

Managing Bill Due Dates

This section explains how to manage bill due dates by performing the following tasks:

Managing Payment Terms. Payment terms enable you to use different methods to calculate due dates for bills that have the same payment method.
Managing Billing Calendars. Billing calendars enable BRM to implement payment terms based on business days.
Specifying Due Date Adjustments in a Billing Run. Billing run-time adjustments enable you to accommodate operational delays in your billing process.

By default, the bill due date for any payment method is 30 days after the date the bill is finalized. You can change default due dates only at the payment-type level.

The BRM delayed billing feature enables billing for all the bill units in your system to be run a specified number of days after the end of their billing cycle. If you use delayed billing, be careful to avoid configuring bill due dates that occur before bills are finalized. For example, if your system has a 14-day billing delay and you configure a bill due date that is fewer than 14 days after the end of a bill unit's billing cycle, the bill due date will occur before the bill is finalized.

Managing Payment Terms

A payment term specifies how to calculate the due date of a bill. You use payment terms to set due dates a specified number of days after the billing cycle end date or on a specified day of the month. For example, payment terms can be linked to functions that set bill due dates as follows:

21 days after the billing cycle end date
15 business days after the billing cycle end date
The second Tuesday of the month

You can define as many payment terms as you need in your BRM system. Each payment term can be associated with one or more /payinfo objects, but a /payinfo object can be associated with only one payment term at a time. The /payinfo object's payment term applies to all bills associated with the object.

Payment terms enable you to use different methods to calculate due dates for bills that have the same payment method. For example, by default, all bills paid by direct debit are due on the day the bill is finalized. Customer A pays a monthly bill by direct debit and has paychecks automatically deposited every two weeks. However, Customer A wants the account debited on the third Tuesday of every month regardless of when the bill is finalized. To do so without affecting other direct debit customers, you can create a third-Tuesday-of-the-month payment term and associate it with the /payinfo object to which customer A's bill is linked.

To manage payment terms, you perform these tasks:

Editing the Payment Terms Configuration File

You configure all the payment terms in your BRM system in the BRM_home/sys/data/config/pin_payment_term.xml file.

In the file, the PaymentTerms parent element must contain a PaymentTerm child element for each payment term in your system. A PaymentTerm child element looks like this:

<PaymentTerm ID="int">description</PaymentTerm>

where int is a payment term ID. For more information, see Table 14-1.

To create a payment term, add a PaymentTerm child element to the PaymentTerms parent element. In the child element, specify values for the items listed in Table 14-1.

Table 14-1 Payment Term Elements

XML Element or Attribute	Description	Possible Values
ID	The ID of the payment term.	Any nonnegative integer. Note Payment term ID 0 is the default payment term. Payment term IDs 1 through 1000 are reserved for BRM use. Important: In the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode, the ID number must be associated with a function that calculates bill due dates. See the chapter about billing in BRM Opcode Guide.
description	An explanation of the payment term. For example, 3rd Tuesday of the month.	Any string. Note: This string is mapped to the PIN_FLD_DESCR field in the /config/payment_term object, which can be used to populate a list of payment terms in a user interface (UI). When creating the string, take any UI length restrictions into account.

XML Element or Attribute

Description

Possible Values

The ID of the payment term.

Any nonnegative integer.

Note

Payment term ID 0 is the default payment term.
Payment term IDs 1 through 1000 are reserved for BRM use.

Important: In the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode, the ID number must be associated with a function that calculates bill due dates. See the chapter about billing in BRM Opcode Guide.

description

An explanation of the payment term. For example, 3rd Tuesday of the month.

Any string.

Note: This string is mapped to the PIN_FLD_DESCR field in the /config/payment_term object, which can be used to populate a list of payment terms in a user interface (UI). When creating the string, take any UI length restrictions into account.

Sample Payment Terms Configuration File

The following is a sample pin_payment_term.xml file:

<?xml version="1.0" encoding="UTF-8"?>
   
<BusinessConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig business_configuration.xsd">
   
<!-- Sample file. Modify according to guidelines -->
   
<PaymentTermConfiguration>
    <PaymentTerms>
        <PaymentTerm ID="1001">17 days</PaymentTerm>
        <PaymentTerm ID="1002">14 business days</PaymentTerm>
        <PaymentTerm ID="1003">3rd Tuesday of the month</PaymentTerm>
    </PaymentTerms>
</PaymentTermConfiguration>
   
</BusinessConfiguration>

Loading Payment Terms

To set up payment terms in your system, edit the payment terms configuration file (pin_payment_term.xml), and then load its contents into the /config/payment_term object in the BRM database.

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

The file is in the BRM_home/sys/data/config directory.
Enter the appropriate information into the file. See "Editing the Payment Terms Configuration File".
Save the file.
Use the following command to run the "load_pin_payment_term" utility from the directory in which the pin_payment_term.xml file is located:
```
load_pin_payment_term pin_payment_term.xml
```
If you do not run the utility from the directory in which pin_payment_term.xml is located, include the complete path to the file; for example:
```
load_pin_payment_term BRM_home/sys/data/config/pin_payment_term.xml
```
Stop and restart the Connection Manager (CM).
For each payment term in your system, customize the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode to specify the function and parameters to use to calculate the due dates of bills associated with the payment term. See BRM Opcode Guide.

Updating the pin.conf File to Use Payment Terms

To use configured payment terms, update the pin.conf file.

Open the BRM_home/sys/cm/pin.conf file in a text editor.

Add the following line:

- cm_cache fm_cust_pol_paymentterm_cache 256, 40960, 64

Save and close the file.
Stop and restart the CM.

Assigning Payment Terms to Bill Units

To assign a payment term to a bill unit, you associate the payment term with the /payinfo object to which the /billinfo object is linked.

To do this at account creation time, call the PCM_OP_CUST_COMMIT_CUSTOMER opcode to put the ID of the payment term into the PIN_FLD_PAYMENT_TERM field of the appropriate /payinfo object. (PCM_OP_CUST_COMMIT_CUSTOMER calls the PCM_OP_CUST_SET_PAYINFO opcode to perform this task.)

Note:

All the payment terms in a BRM system are stored in the /config/payment_term object. In the object, the PIN_FLD_PAYMENT_TERMS array contains the ID and description (PIN_FLD_DESCR) of each payment term.
If you do not assign a payment term to a /payinfo object at account creation time, BRM automatically assigns the default payment term ID 0 to the /payinfo object. This occurs even if there are no payment terms in your system.

To do this at account maintenance time, call the PCM_OP_CUST_UPDATE_CUSTOMER opcode to perform the task described in the preceding paragraphs.

Note:

When assigning payment terms based on days of month (DOMs), ensure the payment term is compatible with the bill unit's billing DOM.

For example, account A's billing DOM is 20 and its payment term is “3rd Tuesday of the month." When billing is run on August 20, 2004, the due date of account A's August bill is set to September 21 because the third Tuesday of August (August 17) has passed. When billing is run on September 20, the due date of account A's September bill is also set to September 21. Thus, account A has two bills due on the same day, which may be undesirable.

See BRM Opcode Guide.

Managing Billing Calendars

By default, a billing calendar contains a list of days on which bills cannot be due.

Billing calendars enable BRM to implement payment terms based on business days. To calculate due dates for bills associated with such payment terms, BRM must determine which days of the year are considered business days and which are not. To do so, it uses billing calendars to exclude days such as weekends, holidays, and other user-specified nonbilling days from the calculation.

For example, if a billing cycle ends on December 10, 2016, and its payment term adds 15 business days to that date, a billing calendar can be used to prevent the bill's payment being due on New Year's Eve.

You can add multiple billing calendars to your system to accommodate different countries and customers. For example, a US billing calendar would include Thanksgiving and Independence Day (July 4) as nonbilling days when they occur on weekdays.

When calculating due dates for bills associated with payment terms based on business days, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses billing calendars to exclude days such as weekends, holidays, and any other user-specified nonbilling day from the calculation.

To manage billing calendars, you perform these tasks:

Setting Up Billing Calendars

To set up billing calendars in your system, edit the billing calendar configuration file (pin_calendar.xml) and then load its contents into /config/calendar objects in the BRM database (each calendar is loaded into a separate object).

To set up billing calendars:

Open the pin_calendar.xml file.

By default, the file is in the BRM_home/sys/data/config directory.
Enter the appropriate information into the file. See "Editing the Billing Calendar Configuration File".
Note:
- Bill run management includes a default billing calendar. Its case-sensitive name is default. By default, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses this calendar to calculate due dates for payment terms based on business days.
- When you edit the configuration file, if you unintentionally change or delete the calendar, due date calculations based on business days may be incorrect.
Save the file.
Use the following command to run the "load_pin_calendar" utility from the directory in which the pin_calendar.xml file is located:
```
load_pin_calendar pin_calendar.xml
```
Note:
- When you run the utility, the pin_calendar.xml and business_configuration.xsd files must be in the same directory. By default, both files are in BRM_home/sys/data/config.
- This utility needs a configuration (pin.conf) file in the directory from which you run the utility. For information, see "Connecting BRM Utilities" in BRM System Administrator's Guide.
If you do not run the utility from the directory in which pin_calendar.xml is located, include the complete path to the file, for example:
```
load_pin_calendar BRM_home/sys/data/config/pin_calendar.xml
```
Stop and restart the CM.

Editing the Billing Calendar Configuration File

You configure all the billing calendars in your BRM system in the BRM_home/sys/data/config/pin_calendar.xml file.

Note:

This configuration file contains one predefined billing calendar. Its case-sensitive name is default. By default, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses this calendar to calculate due dates for payment terms based on business days.

When you edit the configuration file, if you unintentionally change or delete the calendar, due date calculations based on business days may be incorrect.

To edit this configuration file, open it in an XML editor or a text editor.

In the file, the CalendarConfiguration parent element must contain a Calendar child element for each billing calendar in your system. A Calendar child element looks like this:

<Calendar name="calendar_name">
    <Date>
        <!-- day_description -->
        <Day>---dd</Day>
        <Month>--mm--</Month>
        <Year>yyyy</Year>
    </Date>
</Calendar>

For an example, see "Sample Billing Calendar Configuration File".

To add a calendar to the file, see "Adding Calendars".

To add a day to a calendar, see "Adding Days to Calendars".

Adding Calendars

To create a billing calendar, add a Calendar child element to the CalendarConfiguration parent element. In the child element, specify values for the items listed in Table 14-2.

Table 14-2 Calendar Elements

XML Element or Attribute	Description	Possible Values
name	The name of the billing calendar, such as Gregorian, European_Holidays, and Korean. The name of the default billing calendar is default.	Any string. Maximum length is 255 characters. Note The name is case sensitive. This string is mapped to the PIN_FLD_NAME field in the /config/calendar object, which can be used to populate a list of billing calendars in a user interface (UI). When creating the string, take any UI length restrictions into account.
Date	A day on which you do not want bill payments to be due. A Calendar child element can have multiple Date elements. For example, in a US billing calendar, you might include a Date element for every US holiday (New Year's Day, President's Day, Memorial Day, and so on). Note: The default due date function that uses billing calendars (fm_bill_pol_add_n_bus_days) automatically skips weekends, so you do not need to create a Date element for Sundays and Saturdays in calendars used only by that function. See the chapter about billing in BRM Opcode Guide.	See "Adding Days to Calendars".

XML Element or Attribute

Description

Possible Values

name

The name of the billing calendar, such as Gregorian, European_Holidays, and Korean.

The name of the default billing calendar is default.

Any string.

Maximum length is 255 characters.

Note

The name is case sensitive.
This string is mapped to the PIN_FLD_NAME field in the /config/calendar object, which can be used to populate a list of billing calendars in a user interface (UI). When creating the string, take any UI length restrictions into account.

Date

A day on which you do not want bill payments to be due.

A Calendar child element can have multiple Date elements. For example, in a US billing calendar, you might include a Date element for every US holiday (New Year's Day, President's Day, Memorial Day, and so on).

Note: The default due date function that uses billing calendars (fm_bill_pol_add_n_bus_days) automatically skips weekends, so you do not need to create a Date element for Sundays and Saturdays in calendars used only by that function. See the chapter about billing in BRM Opcode Guide.

See "Adding Days to Calendars".

Adding Days to Calendars

In a Calendar child element, you must add a Date element for each day on which you do not want bill payments to be due. A Date element looks like this:

<Date>
    <!-- description_of_day -->
    <Day>---dd</Day>
    <Month>--mm--</Month>
    <Year>yyyy</Year>
</Date>

To add a day to a calendar, add a Date element to the Calendar element. In the Date element, specify values for the items listed in Table 14-3.

Table 14-3 Date Element Entries

XML Element or Attribute	Description	Possible Values
Day	A day of the month.	1 through 31.
Month	A month of the year.	1 through 12.
Year	The year in which the date is a nonbilling day.	One of the following: To associate the date with one year only, specify the appropriate year in yyyy format (for example, 2005). To associate the date with all years (arecurring nonbilling day), use 0000. For example, to make December 25 (Christmas) a recurring nonbilling day, use these values: Day 25, Month 12, Year 0000.

XML Element or Attribute

Description

Possible Values

Day

A day of the month.

1 through 31.

Month

A month of the year.

1 through 12.

Year

The year in which the date is a nonbilling day.

One of the following:

To associate the date with one year only, specify the appropriate year in yyyy format (for example, 2005).
To associate the date with all years (arecurring nonbilling day), use 0000.
For example, to make December 25 (Christmas) a recurring nonbilling day, use these values: Day 25, Month 12, Year 0000.

Sample Billing Calendar Configuration File

The following is a sample pin_calendar.xml file:

<?xml version="1.0"?>
<BusinessConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig business_configuration.xsd">
<!-- Sample file. Modify according to guidelines -->
   
    <CalendarConfiguration>
        <Calendar name="default">
            <!-- holiday specific to indicated year -->
            <Date>
                <!-- Thanksgiving -->
                <Day>---25</Day>
                <Month>--11--</Month>
                <Year>2004</Year>
            </Date>
        </Calendar>
        <Calendar name="Western Australia">
            <!-- recurring holiday on same date. use 0 for year value -->
            <Date>
                <!-- Christmas -->
                <Day>---25</Day>
                <Month>--12--</Month>
                <Year>0000</Year>
            </Date>
            <!-- holiday date specific to indicated year -->
            <Date>
                <!-- Anzac Day -->
                <Day>---26</Day>
                <Month>--04--</Month>
                <Year>2004</Year>
            </Date>
            <Date>
                <!-- Australia Day -->
                <Day>---26</Day>
                <Month>--01--</Month>
                <Year>2005</Year>
            </Date>
        </Calendar>
    </CalendarConfiguration>
</BusinessConfiguration>

Validating Your Billing Calendar Configuration File Edits

After editing the contents of the XML file, you use the "load_pin_calendar" utility to load the contents of the file into /config/calendar objects in the BRM database. See "Setting Up Billing Calendars".

Before loading the contents of the file, the utility validates the contents against the file's schema definition. If the contents do not conform to the schema definition, the load operation fails. The schema definition is in this file:

BRM_home/xsd/pin_calendar.xsd

The XML file is not directly linked to its schema definition file. Instead, it is linked to this XSD reference file:

BRM_home/sys/data/config/business_configuration.xsd

Updating Billing Calendars

To update billing calendars, re-edit the billing calendar configuration file, and then run the "load_pin_calendar" utility to load the updated contents of the file into /config/calendar objects in the BRM database. See "Setting Up Billing Calendars" for the complete procedure.

Note:

This utility overwrites existing billing calendars. When updating billing calendars, you cannot load new calendars only. You must load the complete set of billing calendars each time you run the utility.

To add the newly loaded data to the CM cache, stop and restart the CM.

Associating Billing Calendars with Payment Terms

When using payment terms based on business days to calculate bill due dates, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses billing calendars to omit nonbilling days from the calculation.

To associate a billing calendar with such payment terms, see the chapter about billing in BRM Opcode Guide..

Specifying Due Date Adjustments in a Billing Run

You use billing run-time due date adjustments to add days to the due dates of bills in a billing run. You can add the same number of days to all the bills in the billing run, or you can add different numbers of days to bills whose accounts are associated with different payment terms.

Billing run-time adjustments enable you to accommodate operational delays in your billing process. For example, bills associated with payment term A are due on the third Thursday of the month. On May 3, a problem in your system makes you unable to run billing. On May 10, you fix the problem and run billing for accounts whose billing DOM is 3. As a result, DOM 3 bills are generated a week late. To make up for this delay, you add a due date adjustment of 7 days for payment term A to the billing run. This gives DOM 3 customers associated with payment term A the usual time between receipt of their bill and its due date.

Note:

To specify adjustments based on the payment term with which a bill is associated, you must first set up payment terms in your system and associate accounts with them. See "Loading Payment Terms".

To specify billing run-time due date adjustments:

Open the billing run configuration file (pin_bill_run_control.xml) in an XML editor or a text editor.

By default, the file is in the BRM_home/apps/pin_billd directory.

Note:

You also use this file to split your daily billing run into smaller billing runs. See "Configuring a Split Billing Run".
Specify the appropriate due date adjustments in the file. See "Editing the Billing Run Configuration File to Adjust Bill Due Dates".
Save the file.

Note:

If you want, you can save a copy of the file under a different name. The pin_bill_day script can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition. See "Validating Your Billing Run Configuration File Edits".
Manually run the pin_bill_day script, using this syntax:
```
pin_bill_day -file filename
```
where filename is the name and location of the billing run configuration file. If you run the command in a different directory from where the file is located, you must also include the entire path for the file.

In addition, filename must be in the same directory as the default BRM_home/apps/pin_billd/business_configuration.xsd file.
Note:
- The -file parameter when used with pin_bill_day, affects only the pin_bill_accts utility.
- 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. See "Setting Up Billing in a Multischema Environment".
- When you run pin_bill_day with a configuration file, do not run it as a cron job. If you do, depending on the restrictions in configuration file, some bill units might never be billed.

Editing the Billing Run Configuration File to Adjust Bill Due Dates

By editing the BRM_home/apps/pin_billd/pin_bill_run_control.xml file and then using it as a parameter for the pin_bill_day script, you can add days to the due dates of bills in a billing run. The due date adjustment can apply to all bills in the billing run or to bills associated only with specified payment terms.

To edit the file, open it in an XML editor or a text editor, and then perform one or both of these tasks:

By default, the added days include weekends and nonbusiness days. To add only business days, change the following code in the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode from this:

if (due_date_adjust) {
    fm_utils_add_n_days(due_date_adjust, &due_t);
}

To this:

if (due_date_adjust) {
    fm_bill_pol_add_n_bus_days(ctxp, n, "billing_calendar_name", &due_t, ebufp);
}

For information about the fm_bill_pol_add_n_bus_days function, see the chapter about billing in BRM Opcode Guide.

Associating Due Date Adjustments with Payment Terms

To specify an adjustment for bills associated with a particular payment term, add the appropriate Payment_Term id element to a Due_date_adjustment element in the billing run configuration file:

<Due_date_adjustment length = n >
    <Payment_Term id = x />
</Due_date_adjustment >

where:

n is a positive integer that represents the number of days to add to the due date of a bill.
x is the ID of any payment term defined in the /config/payment_term object. See "Managing Payment Terms".

You must specify both n and x. For example, the following 5-day adjustment applies only to bills associated with payment terms 1001 and 1002:

<Due_date_adjustment length = 5 >
    <Payment_Term id = 1001 />
    <Payment_Term id = 1002 />
</Due_date_adjustment >

Calculating Due Dates Based on Both Payment Terms and Adjustments

When due date adjustments are associated with payment terms, bill due dates are calculated as follows:

Payment terms that add days

billing cycle end date + payment term + adjustment = due date

For example, if the billing cycle end date is April 1, 2001, the payment term 1001 is “add 7 days to the billing cycle end date," and the due date adjustment is 5 days, this calculation is used:

April 1 + 7 days + 5 days = April 13
Payment terms that specify a particular day of month

payment term + adjustment = due date

For example, if payment term 1002 is “second Tuesday of the month," the due date adjustment is 5 days, and billing is run on April 1, 2004, this calculation is used:

April 8 (second Tuesday of April 2004) + 5 days = April 13

Specifying a Default Due Date Adjustment

To specify a due date adjustment for bills in a billing run that are not associated with a payment term or whose payment term is not associated with an adjustment, add a default adjustment:

<Due_date_adjustment length = n />

where n is a positive integer that represents the number of days to add to the due date of a bill.

For example, if the following adjustments are included in the same XML file, the 7-day adjustment applies to bills associated with any payment term except payment terms 1001 and 1002:

<Due_date_adjustment length = 5 >
    <Payment_Term id = 1001 />
    <Payment_Term id = 1002 />
</Due_date_adjustment >
<Due_date_adjustment length = 7 />

Sample Billing Run Configuration File

The following sample pin_bill_run_control.xml file contains these due date adjustments:

A 5-day adjustment for bill units associated with payment terms 1001 and 1002
A 7-day adjustment for all the other bill units in the billing run

Due date adjustments are configured in the bold elements.

<DOMList>
    <DOM>---03</DOM>
    <DOM>---07</DOM>
    <DOM>---15</DOM>
</DOMList>
<BillSegmentList>
    <BillSegment>101</BillSegment>
    <BillSegment>102</BillSegment>
</BillSegmentList>
<DueDateAdjustment Length=5 >
    <PaymentTerm id = 1001 />
    <PaymentTerm id = 1002 />
</DueDateAdjustment >
<DueDateAdjustment Length=7/>

For information about the DOMList and BillSegmentList parent elements, see "Including Only Specified Billing DOMs in Billing Runs" and "Including Only Specified Billing Segments in Billing Runs".

Validating Your Billing Run Configuration File Edits

After editing the XML file, you use the file name as a parameter when you run the pin_bill_day script. See "Specifying Due Date Adjustments in a Billing Run".

The script passes the file name to the pin_bill_accts utility, which validates the contents of the file against its schema definition. If the contents do not conform to the schema definition, the utility returns an error. The schema definition is in this file:

BRM_home/xsd/pin_bill_run_control.xsd

The XML file is not directly linked to its schema definition file. Instead, it is linked to this XSD reference file:

BRM_home/apps/pin_billd/business_configuration.xsd