9 About Bill Run Management

This chapter describes Oracle Communications Billing and Revenue Management (BRM) bill run management and explains how to implement it.

Before reading this chapter, read "About Billing".

About Managing Billing Runs

Bill run management enables you to accomplish the following tasks:

About Reducing Billing Run Loads

By default, when you use the pin_bill_day script to run billing, the billing run includes all bill units (/billinfo objects) 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, bill run management enables you to 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.

For more information, see "Reducing Billing Run Loads".

Note:

For information about other ways to make your billing runs more efficient, see "Tuning Billing Performance" in BRM System Administrator's Guide.

Billing Only Specified Accounts and Bill Units

To bill a single account or a limited set of accounts when you run the pin_bill_day script, you specify the accounts and their bill units (/billinfo objects) in a modified version of the billing run configuration file (BRM_Home/apps/pin_billd/pin_bill_run_control.xml, where BRM_Home is the directory where you installed BRM components).

When you specify the accounts to bill, BRM does not perform a database search but retrieves the account and bill unit information directly.

Important:

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

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

  2. 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 ID of the account and bill unit.

    Important:

    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 ID 55612 and its bill unit with POID ID 34589:

    <BillingList>
    <Account>55612</Account>
    <Billinfo>34589</Billinfo>
</BillingList>

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

  4. Save the file under a different name and close it. For example, when billing a single account, include the account POID ID 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.

  5. 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 filename is in the same directory from which you run the pin_bill_day script, specify only the file name.

    • If filename is in a different directory from which you run the pin_bill_day script, you must 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. See "Manually Running the pin_bill_day Script".

      • 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 to Run in a Multischema Environment".

      Caution:

      When you run pin_bill_day with a filename, do not run it as a cron job. If you do, depending on the restrictions in filename, some bill units might never be billed.

About Managing Bill Due Dates

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.

To add flexibility to bill due dates, bill run management uses these features:

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

For more information, see "Managing Payment Terms".

About 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, 2004 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.

For more information, see "Managing Billing Calendars".

About Billing Run-Time Due Date Adjustments

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.

For more information, see "Specifying Due Date Adjustments in a Billing Run".

Reducing Billing Run Loads

This section explains how to split a daily billing run into smaller billing runs. Splitting a billing run enables you to reduce its load and duration.

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 execute 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 (/billinfo objects). You execute 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 execute 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:

  1. Set a systemwide billing delay.

    By default, auto-triggered billing is always enabled. To disable it, you must set a billing delay in your BRM system. See "Disabling Auto-Triggered Billing by Specifying Billing Delay".

    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 9-1:

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

    Description of Figure 9-1 follows
    Description of ''Figure 9-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.

  2. (Optional) Change the number of days auto-triggered billing is enabled at the end of each accounting cycle. See "Disabling Auto-Triggered Billing by Setting AutoTriggeringLimit".

For more information about auto-triggered billing, see "About Auto-Triggered Billing".

Splitting a Billing Run into Multiple Runs

To split a billing run triggered by the pin_bill_day script 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 (/billinfo objects) 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 "About Billing Segments".

    Caution:

    When you split a large billing run into smaller billing runs:

    • Be careful to 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:

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

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

    Note:

    You also edit this file to specify billing run-time due date adjustments. See "Specifying Due Date Adjustments in a Billing Run".

  2. Edit the file to restrict a billing run to bill units associated with one of the following:

  3. Save and close the file.

    Tip:

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

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

  5. 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 copy filename to the same directory from which you run the pin_bill_day script, specify only the file name.

    • If you run the command in a different directory from where filename is located, you must 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. See "Manually Running the pin_bill_day Script".

      • 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 to Run in a Multischema Environment".

      Caution:

      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 sponsor group owner's bill one cycle late:

  • Sponsor group owner account and member account have the same billing DOM.

  • Sponsor 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 "About Billing Segments".

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 XSD reference file BRM_Home/apps/pin_billd/business_configuration.xsd.

For more information about the XSD reference file, see "About Validating XML Configuration Files" in BRM System Administrator's Guide.

Managing Bill Due Dates

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

About Configurable Bill Due Dates and Delayed Billing

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.

For information about delayed billing, see "Setting Up Delayed Billing".

Managing Payment Terms

A payment term specifies how to calculate the due date of a bill. See "About Payment Terms".

To manage payment terms, you perform these tasks:

Setting Up 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.

Caution:

The utility that loads payment terms into the database overwrites existing payment terms. When updating payment terms, you cannot load new terms only. You must load the complete set of payment terms each time you run the utility.

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

    By default, the file is in the BRM_Home/sys/data/config directory.

  2. Enter the appropriate information into the file. See "Editing the Payment Terms Configuration File".

  3. Save and close the file.

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

    Important:

    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

  5. Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  6. To verify that the payment term information was loaded, display the /config/payment_term object by using one of the following features:

    • Object Browser

    • robj command with the testnap utility

    For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

  7. 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 "Customizing Bill Due Date Calculations for Payment Terms".

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.

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

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 the following table.

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 9-1:

Table 9-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 "Customizing Bill Due Date Calculations for Payment Terms".

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>

Validating Your Payment Terms Configuration File Edits

After editing the contents of the XML file, you use the "load_pin_payment_term" utility to load the contents of the file into the /config/payment_term object in the BRM database. See "Setting Up Payment Terms".

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

For more information, see "About Validating XML Configuration Files" in BRM System Administrator's Guide.

Updating Payment Terms

To update payment term data, re-edit the payment term configuration file, and then run the "load_pin_payment_term" utility to load the updated contents of the file into the /config/payment_term object in the BRM database (see "Setting Up Payment Terms").

Caution:

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

Updating the pin.conf File to Use Payment Terms

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

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

  2. Add the following line:

    - cm_cache fm_cust_pol_paymentterm_cache 256, 40960, 64

  3. Save and close the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Assigning Payment Terms to Bill Units

To assign a payment term to a bill unit (/billinfo object), 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.

Caution:

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.

Managing Billing Calendars

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. See "About Billing Calendars".

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

Caution:

The utility that loads billing calendars into the database 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.

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

    By default, the file is in the BRM_Home/sys/data/config directory.

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

  3. Save and close the file.

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

    Important:

    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

  5. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  6. To verify that the billing calendars were loaded, display the /config/calendar objects by using one of the following features:

    • Object Browser

    • robj command with the testnap utility

    For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

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.

Important:

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 9-2:

Table 9-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 "How BRM Calculates Bill Due Dates".

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 9-3:

Table 9-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 (a recurring 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

For more information, see "About Validating XML Configuration Files" in BRM System Administrator's Guide.

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.

Caution:

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. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

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 "Functions for Calculating Payment Due Dates".

Specifying Due Date Adjustments in a Billing Run

Use billing run-time due date adjustments to add days to the due dates of bills in a billing run triggered by the pin_bill_day script. You can specify the same adjustment for all the bills in the billing run, or you can specify different adjustments for bills associated with different payment terms. See "About Billing Run-Time Due Date Adjustments".

Important:

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 "Setting Up Payment Terms".

To specify billing run-time due date adjustments:

  1. 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 "Splitting a Billing Run into Multiple Runs".

  2. Specify the appropriate due date adjustments in the file. See "Editing the Billing Run Configuration File to Adjust Bill Due Dates".

  3. Save and close 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".

  4. 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 copy filename to the same directory from which you run the pin_bill_day script, specify only the file name.

    • If you run the command in a different directory from where filename is located, you must 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. See "Manually Running the pin_bill_day Script".

      • 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 to Run in a Multischema Environment".

      Caution:

      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 "How BRM Calculates Bill Due Dates".

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 "About 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

For more information, see "About Validating XML Configuration Files" in BRM System Administrator's Guide.

How BRM Calculates Bill Due Dates

The PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode calculates bill due dates. It is called by the PCM_OP_BILL_MAKE_BILL opcode and the PCM_OP_BILL_MAKE_CORRECTIVE_BILL opcode.

Important:

By default, the due date calculation is based on the time that billing is actually run, not on the time that a bill unit is ready to be billed.

When called by the PCM_OP_BILL_MAKE_BILL opcode or the PCM_OP_BILL_MAKE_CORRECTIVE_BILL opcode, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode checks the PIN_FLD_PAYMENT_TERM value in the /payinfo object associated with the bill's /billinfo object and then performs the following operations:

  • If the field has no payment term ID or if the ID is 0, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses the default process of calculating the due date rather than using the bill run management process (see "About Bill Run Management"). The default process involves the fm_bill_pol_default_calc_due_t function and either the PIN_FLD_DUE_DOM value or the PIN_FLD_RELATIVE_DUE_T value in the /payinfo object.

  • If the payment term ID is greater than 0, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses one of the following bill run management functions to calculate the payment due date:

    • fm_utils_add_n_days

    • fm_bill_pol_add_n_bus_days

    • fm_bill_pol_get_nthweekdayofmonth

    For more information, see "Customizing Bill Due Date Calculations for Payment Terms".

After calculating the due date, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode checks the due date adjustment value in the PIN_FLD_DUE_DATE_ADJUSTMENT field of its input flist. If the value is greater than 0, it adds the value to the due date.

The PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode then returns the payment due date to PCM_OP_BILL_MAKE_BILL, which puts it in the PIN_FLD_DUE_T field of the /bill object.

Customizing Bill Due Date Calculations for Payment Terms

You can customize how PCM_OP_BILL_POL_CALC_PAYMT_DUE_T calculates due dates for regular bills as well as for corrective bills.

When the PCM_OP_BILL_MAKE_CORRECTIVE_BILL opcode calls PCM_OP_BILL_POL_CALC_PAYMT_DUE_T to calculate the due date for a corrective bill, it identifies the bill from the PIN_FLD_NAME parameter. The possible values in PIN_FLD_NAME are PIN_OBJ_NAME_CORRECTIVE_BILL, PIN_OBJ_NAME_CORRECTIVE_BILL_NOW, PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND.

The value in PIN_FLD_NAME can be used to validate that PCM_OP_BILL_POL_CALC_PAYMT_DUE_T is calculating the due date for a corrective bill and, if necessary, provide custom logic to calculate due dates for the corrective bill.

For each payment term in your system, you must customize the PCM_OP_BILL_POL_CALC_PYMT_DUE_T "fm_bill_pol_calc_pymt_due_t" function to specify which function and parameters to use to calculate the due dates of the bills associated with the payment term. To customize the function:

  1. In the function's switch statement, add a case for each payment term defined in your /config/payment_term object.

    The ID (constant expression) of each case should correspond to the ID of a payment term element in the PIN_FLD_PAYMENT_TERMS array of /config/payment_term. For example, if the array contains payment term element 1001, add case 1001 to the statement.

    Note:

    Case numbers 1 through 1000 are for BRM use only.

  2. In each case, call the appropriate function with the appropriate parameters. See "Functions for Calculating Payment Due Dates".

Functions for Calculating Payment Due Dates

To calculate payment due dates for bills associated with a payment term, call one of these functions in the corresponding case in "fm_bill_pol_calc_pymt_due_t":

  • For payment terms that add any type of day (business, weekend, holiday, and so on) to the billing cycle end date, use this function:

    fm_utils_add_n_days(n, &due_t)

    For an example, see case TERM1 in the "fm_bill_pol_calc_pymt_due_t" code sample.

    Parameters

    • n specifies the number of days to add to the billing cycle end date. The value can be any positive integer.

    • &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). n is added to this date.

  • For payment terms that add only business days to the billing cycle end date, use this function:

    fm_bill_pol_add_n_bus_days(ctxp, n, "default", &due_t, ebufp)

    For an example, see case TERM2 in the "fm_bill_pol_calc_pymt_due_t" code sample.

    Parameters

    • ctxp points to a communication channel between the client application and the database.

    • n specifies the number of business days to add to the billing cycle end date. The value can be any positive integer.

    • default is the case-sensitive name of the default billing calendar. See "About Billing Calendars".

      To use a different calendar, replace default with the value in the PIN_FLD_NAME field of the /config/calendar object that you want to use.

      Note:

      • This function automatically skips weekends, so you do not need to include Sundays and Saturdays in billing calendars used only by this function.

      • If the CM cache does not contain the specified /config/calendar object, the function uses the default process of calculating the payment due date rather than the bill run management process.

    • &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). n is added to this date.

    • ebufp is a pointer to the error buffer that contains any errors that occur when the function tries to retrieve the specified calendar from the database.

  • For payment terms that specify a particular day of month, use this function:

    fm_bill_pol_get_nthweekdayofmonth(d, n, &due_t)

    For an example, see case TERM3 in the "fm_bill_pol_calc_pymt_due_t" code sample.

    Parameters

    • d is a day of the week. The value can be 0 (Sunday), 1 (Monday), 2 (Tuesday), 3 (Wednesday), 4 (Thursday), 5 (Friday), or 6 (Saturday).

    • n is the ordinal rank of d in a month. The value can be 1 (first d of the month), 2 (second d of the month), 3 (third d of the month), or 4 (fourth d of the month).

    • &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object).

      Important:

      If &due_t is after d n of the month, d n of the next month is used.

      For example, if d = 2, n = 3, and &due_t = April 19, 2004, the payment due date is April 20, 2004 (third Tuesday of April).

      But, if d = 2, n = 3, and &due_t = April 21, 2004, the payment due date is May 18, 2004 (third Tuesday of the next month).

  • You can also create custom functions to calculate payment due dates:

    custom_function(custom_parameter, &due_t, ebufp)

    • &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). The function must take due_t as a parameter.

    • ebufp is a pointer to the error buffer that contains any errors that occur when the function tries to retrieve an object from the database. If the function uses BRM objects, this parameter is required.

fm_bill_pol_calc_pymt_due_t

This is the default implementation of the fm_bill_pol_calc_pymt_due_t function in the fm_bill_pol_calc_pymt_due_t.c file:

switch (ptt)
    {
        case TERM1: /* Add 17 days to the billing cycle end date */
            fm_utils_add_n_days(17, &due_t);
            break;
    
        case TERM2: /* Add 14 business days to the billing cycle end date */
            fm_bill_pol_add_n_bus_days(ctxp, 14, "default", &due_t, ebufp);
            if (PIN_ERR_IS_ERR(ebufp))
            {
                PIN_ERR_LOG_EBUF(PIN_ERR_LEVEL_ERROR,
                "fm_bill_pol_calc_pymt_due_t: Error while using Payment Term 2", ebufp);
                goto cleanup;
            }
            /***********************************************************
            * If due_t is not changed, it means that there
            * are no /config/calendar objects available in the CM cache.
            * In this case, use the default TERM0 implementation.
            ***********************************************************/
            if (due_t == *eff_tp)
            {
                PIN_ERR_LOG_MSG(PIN_ERR_LEVEL_WARNING, "Switching to default calculation");
                fm_bill_pol_default_calc_due_t(&due_t, eff_tp, r_due_t, due_dom, ebufp);
            }
    
            break;
    
        case TERM3: /* Make the due date the 3rd Tuesday of the month */
            fm_bill_pol_get_nthweekdayofmonth( 2, 3, &due_t);
            break;
    
        /* Add implementation for handling more payment terms here */
    
        default: /* TERM0 for backward compatibility */
            fm_bill_pol_default_calc_due_t(&due_t, eff_tp, r_due_t, due_dom, ebufp);
    }