12 Load Balancing Billing Runs

Learn how to apply load balancing to billing operations in Oracle Communications Billing and Revenue Management (BRM) by running billing based on the customer's accounting day of month (DOM).

Topics in this document:

• About Managing Billing Cycles

• Implementing Bill Cycle Management

Note:

Implementing this feature requires using opcodes to create a custom application.

About Managing Billing Cycles

Accounting cycles and billing cycles begin on a bill unit's billing day of month (DOM). By default, the DOM on which an account is created automatically becomes the billing DOM for all the account's bill units. This can result in an uneven distribution of a system's billing operations across each month.

To load-balance billing operations, you can use billing segments to assign accounts to billing DOMs. A billing segment is a user-defined category, such as wholesale, retail, and senior citizen. To implement bill cycle management, you create billing segments in your BRM system and then assign bill units to them. The billing segment determines which DOMs are available to the bill units.

A billing segment can be associated with any number of DOMs. For example, billing segment A might be associated with DOMs 1 through 31 and billing segment B might be associated with DOMs 1, 15, and 31. For each DOM with which it is associated, a billing segment contains the following information:

• A status (open, closed, or restricted) that determines whether the DOM can be assigned to the bill units that belong to the segment.

• The maximum number of accounts that can be associated with the DOM–billing segment pair.

• The maximum number of services that can be associated with the DOM–billing segment pair.

• The following data, which you must use third-party data warehousing software to gather:

  • The number of accounts currently associated with the DOM–billing segment pair.

  • The number of services currently associated with the DOM–billing segment pair.

  • The total amount of time that it took to process the bills associated with the DOM–billing segment pair during the previous billing run.

    Note:

    To accommodate the frequent updates that such data may require, BRM automatically refreshes cached billing segment data once a day (see "Updating Billing Segments").

BRM uses billing segment information with new bill cycle management functions in the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode to determine the accounting DOMs to which a bill unit can be assigned. For more information, see "Implementing Bill Cycle Management" and BRM Opcode Guide.

The status of the accounting DOMs in each billing segment determines whether and how a particular DOM can be assigned to the bill units associated with the billing segment as shown in Table 12-1.

Table 12-1 DOM Status Assignments

DOM Status	Manually Assignable? (1)	Automatically Assignable? (2)
open	Yes	Yes
restricted	Yes	No
closed	No	No

Note:

1. See "Manually Assigning a Billing DOM".
2. See "Automatically Assigning a Billing DOM".

You specify the status of accounting DOMs in the pin_billing_segment.xml file. For more information, see "Setting Up Billing Segments".

Note:

• Accounting DOMs not explicitly associated with a billing segment are considered closed for the segment. For example, if billing segment C is associated only with DOMs 1 and 2, DOMs 3 through 31 are closed for that segment and cannot be assigned to bill units that belong to the segment.

• If a billing segment is not associated with any accounting DOMs, all DOMs are open for the segment. In such cases, the default process, not the bill cycle management process, is used to assign an accounting DOM to the bill units that belong to the segment.

Implementing Bill Cycle Management

To implement bill cycle management:

1. Set up billing segments in your system. See "Setting Up Billing Segments".

2. Perform the following tasks programmatically or through a custom user interface:

   • Associate bill units with billing segments at account creation and account maintenance time. See "Associating Bill Units with Billing Segments".

   • (Optional) Select a billing DOM for bill units. See "Assigning Accounting Days of Month to Bill Units in Billing Segments".

3. (Optional) Customize the PCM_OP_CUST_POL_PREP_BILLINFO opcode to select the DOM most likely to have the lightest billing load of all available DOMs. See the chapter about billing in BRM Opcode Guide.

Setting Up Billing Segments

To set up billing segments in your system, edit the billing segment configuration file BRM_home/sys/data/config/pin_billing_segment.xml, and load its contents into the /config/billing_segment object in the BRM database.

Note:

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

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

2. Enter the appropriate information into the file. See "Editing the Billing Segment Configuration File".

3. Save the file.

4. Use the following command to run the "load_pin_billing_segment" utility from the directory in which the pin_billing_segment.xml file is located:

   load_pin_billing_segment pin_billing_segment.xml

   If you do not run the utility from the directory in which pin_billing_segment.xml is located, include the complete path to the file. For example:

   load_pin_billing_segment BRM_home/sys/data/config/pin_billing_segment.xml
   

   For more information, see "load_pin_billing_segment".

5. Activate the feature that automatically refreshes billing segment data in the Connection Manager (CM) cache. See "Automatically Refreshing Billing Segment Data".

6. Stop and restart the CM.

   Note:

   • If the data does not need to be added to the CM cache until the next time the cache is automatically refreshed, you do not have to do this.

   • If an error occurs at CM startup, the space allocated to billing segment data in the CM cache may not be sufficient to accommodate the size of your billing segment data. See "Increasing the Size of the CM Cache for Billing Segment Data".

7. To verify that the billing segment information was loaded, display the /config/billing_segment object by using one of the following features:

   • Object Browser

   • robj command with the testnap utility

   For general instructions on using testnap, see "Using the testnap Utility to Test BRM" 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 Segment Configuration File

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

To edit this configuration file, open it in an XML editor or a text editor and then perform these tasks:

• To add billing segments to the file, see "Defining Billing Segments".

• To associate the billing segments with billing DOMs. See "Associating Billing Segments With Accounting Days of Month".

Defining Billing Segments

In the billing segment configuration file, billing segments are defined as BillingSegment child elements of the BillingSegments parent element.

A BillingSegment child element consists of a billing segment ID and a description (string):

<BillingSegmentConfiguration>
   <BillingSegments>
      <BillingSegment ID="int ">string</BillingSegment>
   </BillingSegments>
</BillingSegmentConfiguration>

To create a billing segment, add a BillingSegment child element to the BillingSegments parent element. In the child element, specify values for the items listed in Table 12-2.

Table 12-2 XML Elements in Billing Segment

XML Element or Attribute	Description	Possible Values
ID	A number that identifies the billing segment in the BRM database. When a bill unit is linked to a billing segment, this number is put in the PIN_FLD_BILLING_SEGMENT field of the /billinfo object. An array of all the billing segment IDs is stored in the /config/billing_segment object.	To use bill cycle management to assign billing DOMs to bill units in the segment, specify any integer greater than or equal to 101. Note: ID 0 triggers BRM to use the non-bill-cycle-management assignment process.
string	A character string that describes the type of accounts in the billing segment (for example, wholesale or retail).	Minimum length is 1 character. Maximum length is 1023 characters. Note: This string is mapped to the PIN_FLD_DESCR field in the /config/billing_segment object, which can be used to populate a list of billing segments in a user interface (UI). When creating the string, take any UI length restrictions into account.

Associating Billing Segments With Accounting Days of Month

In the billing segment configuration file, the DomAssignments parent element contains DomAssignment child elements, each of which associates a billing segment with a DOM:

<BillingSegmentConfiguration>
   <DomAssignments>
      <DomAssignment billingSegmentRef="int" status=" status " dom=" ---gDay "
       maxAccounts="int" maxServices="int">
         <NumAccounts>int</NumAccounts>
         <NumServices>int</NumServices>
         <TotalProcessTime>duration</TotalProcessTime>
      </DomAssignment>
   </DomAssignments>
</BillingSegmentConfiguration>

To create a billing segment–DOM association, add a DomAssignment child element to the DomAssignments parent element. In the child element, specify values for the items listed in Table 12-3.

Note:

• You must add one DomAssignment child element for every billing segment–DOM association. For example, to associate billing segment 101 with DOMs 1 through 31, you must add 31 DomAssignment child elements. The billingSegmentRef value of each child element will be the same (101), but each child element will have a different dom value.

• If a billing segment is not explicitly associated with any accounting DOMs, all DOMs are open for the segment.

• An array of all the billing segment and DOM pairs in a BRM system (PIN_FLD_MAP) is stored in the /config/billing_segment object.

Table 12-3 DOM Assignments

XML Element or Attribute	Description	Possible Values
billingSegmentRef	The billing segment ID value in the ID attribute of a BillingSegment child element in the BillingSegments parent element.	See the billingSegmentId entry in the table in "Defining Billing Segments".
status	The status of a DOM for the billing segment.	One of the following: open restricted closed Important: These values are case sensitive.
dom	A billing DOM.	Any two-digit value from 01 through 31.
(Optional) maxAccounts	Maximum number of accounts that can be associated with the DOM–billing segment pair.	Any non-negative integer.
(Optional) maxServices	Maximum number of services that can be associated with the DOM–billing segment pair.	Any non-negative integer.
(Optional) NumAccounts	Number of accounts currently associated with the DOM–billing segment pair.	Any non-negative integer. Note: This information is generated by third-party data warehousing software.
(Optional) NumServices	Number of services currently associated with the DOM–billing segment pair.	Any non-negative integer. Note: This information is generated by third-party data warehousing software.
(Optional) TotalProcessTime	Total amount of time (in seconds) that it took to process the bills associated with the DOM–billing segment pair during the previous billing run.	Any duration type value. For example, P1Y3M2DT1H20M30S (1 year, 3 months, 2 days, 1 hour, 20 minutes, and 30 seconds). The "load_pin_billing_segment" utility converts this value into seconds. Note: This information is generated by third-party data warehousing software.

Sample Billing Segment Configuration File

The following is a sample pin_billing_segment.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">
   <BillingSegmentConfiguration>
      <BillingSegments>
         <BillingSegment ID="101">First Billing Segment</BillingSegment>
         <BillingSegment ID="102">Second Billing Segment</BillingSegment>
         <BillingSegment ID="103">Third Billing Segment</BillingSegment>
      </BillingSegments>
      <DomAssignments>
         <DomAssignment billingSegmentRef="101" status=" restricted " dom="  ---31  "
          maxAccounts="7400" maxServices="70033">
            <NumAccounts>4</NumAccounts>
            <NumServices>5</NumServices>
            <TotalProcessTime>PT20S</TotalProcessTime>
         </DomAssignment>
         <DomAssignment billingSegmentRef="102" status="open" dom="---07" maxAccounts="7400"
          maxServices="733">
            <NumAccounts>76</NumAccounts>
            <NumServices>5</NumServices>
            <TotalProcessTime>P1D</TotalProcessTime>
         </DomAssignment>
      </DomAssignments>
   </BillingSegmentConfiguration>
</BusinessConfiguration>

Validating Your Billing Segment Configuration File Edits

After editing the contents of the XML file, you use the "load_pin_billing_segment" utility to load the contents of the file into the /config/billing_segment object in the database. See "Setting Up Billing Segments".

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. By default, the schema definition is BRM_home/xsd/pin_billing_segment.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.

Updating Billing Segments

To update billing segment data, re-edit the billing segment configuration file, and then run the "load_pin_billing_segment" utility to load the updated contents of the file into the /config/billing_segment object in the BRM database. See "Setting Up Billing Segments".

Note:

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

Adding Updated Billing Segment Data to the CM Cache

To add newly loaded billing segment data to the CM cache, do one of the following:

• Manually refresh the cache by stopping and restarting the CM after running the load utility.

• Automatically refresh the cache. See "Automatically Refreshing Billing Segment Data".

  Note:

  If a re-edited billing segment configuration file is significantly larger than the previous version of the file, you might have to increase the space allocated to the data in your CM cache to prevent an error from occurring at CM startup. See "Increasing the Size of the CM Cache for Billing Segment Data".

Automatically Refreshing Billing Segment Data

To refresh billing segment data automatically:

1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

2. Uncomment the fm_cust billing_segment_config_refresh_delay entry by deleting the number sign (#) at the beginning of the entry.

3. (Optional) Change the refresh frequency.

   By default, this entry is set to 86400 (24 hours, in seconds). This refreshes the cache once a day. To change the frequency, replace this value with the appropriate number of seconds.

   For example, to refresh the data only once a week, change the value to 604800 (60 seconds x 60 minutes x 24 hours x 7 days).

4. Stop and restart the CM.

   Note:

   To turn off the refresh feature, see "Preventing Automatic Updates of Billing Segment Data".

Increasing the Size of the CM Cache for Billing Segment Data

If your billing segment configuration file contains a lot of data, you might need to increase the space allocated to that data in the CM cache to prevent an error from occurring at CM startup:

1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

2. Increase cache_size in the following entry:

   - cm_cache fm_cust_billing_segment number_of_entries, cache_size, hash_size
   

   The default is 51200 bytes.

   For example, change this:

   - cm_cache fm_cust_billing_segment 1, 51200, 1
   

   To this:

   - cm_cache fm_cust_billing_segment 1, 102400, 1
   

3. Increase cache_size in the following entry:

   - cm_cache fm_cust_dom_map number_of_entries, cache_size, hash_size
   

   The default is 102400 bytes.

   For example, change this:

   - cm_cache fm_cust_dom_map 1, 102400, 1
   

   To this:

   - cm_cache fm_cust_dom_map 1, 204800, 1
   

4. Stop and restart the CM.

Preventing Automatic Updates of Billing Segment Data

To prevent your system from automatically refreshing billing segment data in the CM cache:

1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

2. Comment out the fm_cust billing_segment_config_refresh_delay entry by inserting a number sign (#) at the beginning of the entry.

3. Stop and restart the CM.

   Note:

   By default, this feature is turned off. To turn it on, see "Automatically Refreshing Billing Segment Data".

Associating Bill Units with Billing Segments

All the billing segments in a BRM system are defined in the /config/billing_segment object. Within that object, the PIN_FLD_BILLING_SEGMENTS array contains the ID and description (PIN_FLD_DESCR) of each billing segment.

To link a bill unit to a billing segment, put the ID of the billing segment into the PIN_FLD_BILLING_SEGMENT field of the /billinfo object.

Note:

Every bill unit in an account and every nonpaying bill unit associated with the account must belong to the same billing segment. If you try to associate the bill units with different billing segments, BRM returns an error.

To change a bill unit's billing segment, you need to run the PCM_OP_CUST_UPDATE_CUSTOMER opcode. See BRM Opcode Guide.

Changing a Bill Unit's Billing Segment

You can change a bill unit's billing segment in one of two ways:

• Change the billing segment but not the billing DOM

  To change a bill unit's billing segment but not its billing DOM, call the PCM_OP_CUST_UPDATE_CUSTOMER opcode with the new billing segment ID to put in the PIN_FLD_BILLING_SEGMENT field of the /billinfo object.

  Note:

  The status of the DOM in the new billing segment must be open. If it is not, an error is returned.

• Change the billing segment and the billing DOM

  To change both a bill unit's billing segment and its billing DOM, call PCM_OP_CUST_UPDATE_CUSTOMER with the following /billinfo field values:

  • A new billing segment ID to put in the PIN_FLD_BILLING_SEGMENT field.

  • A new billing DOM to put in the PIN_FLD_ACTG_FUTURE_DOM field. The status of the DOM must be open in the specified billing segment.

  To change only a bill unit's billing DOM, see "Changing a Bill Unit's Billing DOM".

Assigning Accounting Days of Month to Bill Units in Billing Segments

When a bill unit is associated with a billing segment, one of the available billing DOMs in the segment must be assigned to the bill unit. A DOM's availability depends in part on the status of the DOM.

DOMs can be assigned in either of the following ways:

• Manually Assigning a Billing DOM

• Automatically Assigning a Billing DOM

To change a bill unit's billing DOM, see "Changing a Bill Unit's Billing DOM".

Manually Assigning a Billing DOM

To assign billing DOMs to new or existing bill units manually, create an application that enables customer service representatives to select one of the open or restricted DOMs in the billing segment with which a bill unit is associated.

Note:

Essentially, the CSR is selecting the bill unit's billing DOM.

The PIN_FLD_MAP array in the /config/billing_segment object contains all the billing segment–DOM pairs configured in your system.

For each pair, the status of the DOM is stored in the PIN_FLD_STATUS field.

To validate the CSR's selection, the application should call PCM_OP_CUST_UPDATE_CUSTOMER. That opcode calls the PCM_OP_CUST_SET_BILLINFO opcode, which calls the PCM_OP_CUST_POL_PREP_BILLINFO and the PCM_OP_CUST_POL_VALID_BILLINFO policy opcodes.

To link a bill unit to an billing DOM, put the DOM value (1-31) into the PIN_FLD_ACTG_CYCLE_DOM field of the /billinfo object.

Automatically Assigning a Billing DOM

If a billing DOM is not manually selected for a bill unit after the unit is assigned to a billing segment, the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode automatically assigns a DOM to the bill unit.

The policy opcode assigns DOMs whose status is open; it cannot assign DOMs whose status is restricted.

Changing a Bill Unit's Billing DOM

To change a bill unit's billing DOM, call PCM_OP_CUST_UPDATE_CUSTOMER with the new DOM to put the PIN_FLD_ACTG_CYCLE_DOM field of the /billinfo object.

Note:

The status of the new DOM must be open in the bill unit's billing segment. If it is not, an error is returned.

To change a bill unit's billing segment, see "Changing a Bill Unit's Billing Segment".