Creating Custom Bill Items

16 Creating Custom Bill Items

Learn how to create custom bill items and how Oracle Communications Billing and Revenue Management (BRM) assigns custom bill items to events.

Topics in this document:

About Custom Bill Items

Bill items enable you to track a customer's balance for a type of event. For example, a bill item tracks all charges for service usage or all charges for cycle fees during a billing cycle.

By default, BRM tracks balances in the following bill items: cycle arrears items, cycle forward items, cycle forward arrears items, cycle tax items, cycle incentive items, and usage items.

You can create custom bill items to further aggregate charges and to provide more descriptive information in your invoices, reports, and CSR applications. For example, if you charge customers for password changes, you can track password changes separately and list the charges on invoices under “password change" rather than “usage."

About Defining Custom Bill Items

When you create a custom bill item, you define the following:

The bill item name. This is the item name displayed on customer invoices, reports, and CSR applications.
How to track charges. You specify whether a bill item stores one charge only or accumulates multiple charges. See "Tracking Charges in Bill Items".
How to store the item in the database. You can either pre-create a custom /item object in the database or have BRM create one for you. See "About Creating /item Objects".
The type of events you want the bill item to track. You do this by assigning bill items either to an event and service combination or to event attributes. See "About Assigning Custom Bill Items to Events".

Tracking Charges in Bill Items

When you create a custom bill item, you specify whether the item accumulates charges or tracks each charge separately.

Cumulative bill items accumulate charges throughout the billing cycle. All events of the same type are consolidated into a single /item object. For example, if a customer has three broadband sessions during a billing cycle, BRM stores all of the charges in one /item object. The customer's invoice also lists one item with the total rolled-up charge for all three sessions, as shown in Figure 16-1:

Figure 16-1 Rolled-Up Broadband Usage Charges on Invoice

Description of "Figure 16-1 Rolled-Up Broadband Usage Charges on Invoice"

Individual bill items store a charge for a single event, such as purchasing a charge offer. A separate /item object is created for each event of the same type. For example, if a customer purchases three ring tones during a billing cycle, BRM stores the charges in three separate /item objects. The customer's invoice also lists three separate bill items and their charges, as shown in Figure 16-2:

Figure 16-2 Individual Bill Items

Description of "Figure 16-2 Individual Bill Items"

You specify whether a custom bill item is cumulative or individual in the config_item_types.xml file. See "Mapping Item Tags to Item Types".

About Creating /item Objects

You create your custom bill items in the database by subclassing the /item object. For example, you can create an /item/password object for storing password charges.

For usage events, you can specify whether BRM pre-creates the custom bill item before any event occurs or creates it during the rating process. In this case, the item is created when a service object is created for an account and when billing is run.

About Assigning Custom Bill Items to Events

You assign custom bill items to events in either of two ways:

Assign bill items to a specific event and service combination. See "About Using Event and Service Combinations to Assign Bill Items".
Assign bill items to events based on event attributes. See "About Using Event Attributes to Assign Bill Items".

About Using Event and Service Combinations to Assign Bill Items

You can assign a bill item to each event and service combination that you support. For example, you can map the event and service combinations to a bill item object as shown in Table 16-1:

Table 16-1 Event and Service Combinations for Bill Item Object

Event and Service Combination	Item Object
/event/session/telco/gsm /service/telco/gsm/*	/item/gsm_usage
/event/session/telco/gprs /service/telco/gprs/*	/item/gprs_usage
/event/session/email /service/email	/item/email_usage

Event and Service Combination

Item Object

/event/session/telco/gsm

/service/telco/gsm/*

/item/gsm_usage

/event/session/telco/gprs

/service/telco/gprs/*

/item/gprs_usage

/event/session/email

/service/email

/item/email_usage

In Table 16-1, BRM separates charges for GSM usage, GPRS usage, and email usage into three /item objects and displays each item separately on customer invoices.

You can assign one bill item to one event and service combination or assign one bill item to multiple event and service combinations. For example, you can assign /item/voice to any event and service combination that provides voice service.

You can also create multiple item configurations (sets of item-to-event-and-service mappings) to apply to different types of bill units. This enables you to avoid creating unnecessary bill items in your BRM system. See "Improving Performance by Using Multiple Item Configurations" in BRM System Administrator's Guide.

Note:

A large number of items per account or bill unit (/billinfo object) can decrease system performance. Additionally, account creation and billing failures can occur when there are a large number of item types for an account or service that results in the maximum lengths for PIN_FLD_ITEM_POID_LIST and PIN_FLD_NEXT_ITEM_POID_LIST fields to be exceeded. Item POIDs are appended to PIN_FLD_ITEM_POID_LIST and PIN_FLD_NEXT_ITEM_POID_LIST in the /account object when a new item type is created for an account or service. The following options are recommended when creating custom item types:

Limit the number of item types such that if a customer uses all the event and service combinations defined in the config_item_tags.xml and config_item_types.xml, the number of item poids for an account or service does not exceed 2000 bytes. See "Assigning Item Tags Based on Event and Service Combinations".
Create item types with PRECREATE set to FALSE. By setting PRECREATE to FALSE, the items are created only when the particular event occurs for the service. This enables minimal items to be created during account creation or billing. See "Mapping Item Tags to Item Types".

To assign event and service combinations to bill items, you perform these tasks:

Map event and service combinations to item tags by editing the config_item_tags.xml file. See "Assigning Item Tags Based on Event and Service Combinations".
Map item tags to item types by editing the config_item_types.xml file. See "Mapping Item Tags to Item Types".

You can configure how BRM assigns event and service combinations to bill items by adding the – fm_act attach_item_to_event n entry in the CM pin.conf file, where n can be 0, 1, or 2. If the value of n is:

0: BRM does not assign events without balance impact to any item. The events that have balance impact are assigned to items according to the event and service combinations defined in the appropriate /config/item_tags object. This is the default value.
1: BRM assigns any event to items. This includes events without any balance impact.
2: BRM assigns any event to items. If the event has a service and the event and service combination is not defined in a /config/item_tags object, BRM assigns the event to the default item (/item/misc) on the account and not on service.

To add the attach_item_to_event entry:

Open the Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf, where BRM_home is the directory in which you installed BRM components).
Add the following entry:
```
– fm_act attach_item_to_event n
  
```
where n can be 0, 1, or 2.
Save and close the file.
Stop and restart the CM.

For information about configuration files, see "Using Configuration Files" in BRM System Administrator's Guide.

About Using Event Attributes to Assign Bill Items

You can provide even more granularity in your reports, invoices, and CSR applications by assigning items by event attribute. This enables you to assign multiple items to the same event and service combination.

For example, for the event and service combination of /event/session/telco/gsm and /service/telco/gsm/*, you can separate events by the following:

Calls that originated in New York in a custom item object named /item/new_york.
Calls that originated in California in a custom item object named /item/california.

In the example shown in Figure 16-3, the customer's invoice displays an itemized list of GSM usage:

Figure 16-3 Itemized List of GSM Usage

Description of "Figure 16-3 Itemized List of GSM Usage"

To assign items based on event attributes, you perform the following tasks:

Map event attributes to an item tag by customizing a policy opcode. See "Assigning Item Tags Based on Event Attributes".
Map items tags to item types by editing the config_item_types.xml file. See "Mapping Item Tags to Item Types".

How BRM Assigns Custom Bill Items to Events

BRM assigns bill items to events during the rating process by performing the following tasks:

BRM assigns an item tag based on the event and service combination.
If customized to do so, the BRM custom API takes the assigned item tag as input and then assigns a different item tag based on the event's attributes.
BRM assigns an item type based on the item tag.

Cumulative Custom Item for Taxes

The following example shows a custom item that stores all taxes from all tax suppliers in a single bill item for each billing cycle.

Open the BRM_home/sys/data/pricing/example/config_item_tags.xml file.

Add the following entry:

<ItemTagElement>
<ItemTag>cycle_tax</ItemTag> <EventType>/event/billing/cycle/tax</EventType> <ServiceType>/account</ServiceType> </ItemTagElement>

Save and close the file.
Open the BRM_home/sys/data/pricing/example/config_item_types.xml file.

Add the following entry:

<ItemTypeElement>
<ItemTag>cycle_tax</ItemTag>
<ItemDescription>Cycle Tax</ItemDescription>
<ItemType precreate="false" type="cumulative">/item/cycle_ tax</ItemType>
</ItemTypeElement>

Save and close the file.

Setting Up BRM to Assign Custom Bill Items to Events

To assign items to events and to update the items in the BRM database for billing and tracking:

Create the custom bill item in the database by subclassing the /item storable class. See "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.

Note:

Before creating a bill item, you must know the event and service type whose balance impacts you want stored with the new item.
Map event and service combinations to item tags in the appropriate item configuration. See "Assigning Item Tags Based on Event and Service Combinations".
Map event attributes to item tags. See "Assigning Item Tags Based on Event Attributes".
Map item tags to item types in the appropriate item configuration. See "Mapping Item Tags to Item Types".

Assigning Item Tags Based on Event and Service Combinations

You map event and service combinations to custom item tags by editing the config_item_tags.xml file. You then load the item tags into a /config/item_tags object by using the load_config_item_tags utility. See "load_config_item_tags".

Every item tag in the item tags file must have a corresponding item type defined in the config_item_types.xml file. If you make changes to the config_item_tags.xml file after you load it into the database, you must make corresponding changes to the item types and load the config_item_types.xml file again. See "Mapping Item Tags to Item Types".

To assign item tags:

Open the BRM_home/sys/data/pricing/example/config_item_tags.xml file in a text editor.
Verify that the value of the following optional tag is correct:
```
<Name>Item_Configuration_Name</Name> 
```
Where Item_Configuration_Name is the name of the item configuration to which the item tags defined in this XML file belong.

The name of the BRM system's default item configuration is Default. If the value of this tag is Default, or if this tag is not included in the file, your custom tags are added to the default item configuration.

To add a new item configuration to your system, enter a unique item configuration name in this XML file and in the corresponding config_item_types.xml file.

To modify an existing item configuration in your system, enter that configuration's name in this XML file and in the corresponding config_item_types.xml file.

For more information about item configurations, see "Improving Performance by Using Multiple Item Configurations" in BRM System Administrator's Guide.
Add custom tags to the file by following the instructions in the file.

Note:

Tag names must be unique.

For example, to store GSM calls in a custom bill item, add the following entry:
```
<ItemTagElement> 
    <ItemTag>GSM</ItemTag> 
    <EventType>/event/delayed/session/telco/GSM/*</EventType> 
    <ServiceType>/service/telco/GSM/*</ServiceType>
</ItemTagElement>
```
where:
- The ItemTag element specifies the unique name for the item tag.
- The EventType element specifies the parent /event storable class.
- The ServiceType element specifies the parent /service storable class.
Save the file. You can save the file with a different name and location or use the original file.
Run the following command:
```
load_config_item_tags config_item_tags_file 
```
where config_item_tags_file is the name and path of your config_item_tags.xml file.

Note:

The load_config_item_tags utility replaces the entire contents of the /config/item_tags object whose PIN_FLD_NAME value matches the Name value in the config_item_tags.xml file with the contents of that file. If you are updating a set of item tags, you cannot load new items only. You must load complete sets of items each time you run the load_config_item_tags utility.
Stop and restart CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

To verify that the item tags were loaded, use Object Browser in Developer Center or the testnap utility's robj command to display the specified /config/item_tags object. See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Assigning Item Tags Based on Event Attributes

You assign item tags based on event attributes by customizing the BRM API.

Setting Up Online Charging to Assign Items Based on Event Attributes

You set up online charging to assign items to events based on event attributes by using the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode. By default, this policy opcode does nothing. However, you can customize it to find events with specific flist fields, assign the appropriate item tag, and then return the item tag in the PIN_FLD_ITEM_TAG output flist field. See BRM Opcode Guide.

Mapping Item Tags to Item Types

You map the item tags that you defined in the config_item_tags.xml file or policy opcode to item types by using the config_item_types.xml file. You then load the mappings into the appropriate /config/item_types object by using the load_config_item_types utility.

Note:

The load_config_item_types utility replaces the entire contents of the specified /config/item_types object whose PIN_FLD_NAME value matches the Name value in the config_item_types.xml file with the contents of that file. If you are updating a set of mappings, you cannot load new mappings only. You must load complete sets of mappings each time you run the load_config_item_types utility.
If the config_item_types.xml file does not contain a PIN_FLD_NAME value, the /config/item_types object whose PIN_FLD_NAME value is Default is replaced.

To map item tags to item types:

Open the BRM_home/sys/data/pricing/example/config_item_types.xml file in an XML editor or a text editor.
Verify that the value of the following tag is correct:
```
<Name>Item_Configuration_Name</Name>
```
where Item_Configuration_Name is the name of the item configuration to which the item types defined in this XML file belong.

The name of the BRM system's default item configuration is Default. If the value of this tag is Default, or if this tag is not included in the file, your custom mappings are added to the default item configuration.

To add a new item configuration to your system, enter a unique item configuration name in this XML file and in the corresponding config_item_tags.xml file.

To modify an existing item configuration in your system, enter that configuration's name in this XML file and in the corresponding config_item_tags.xml file.

For more information about item configurations, see "Improving Performance by Using Multiple Item Configurations" in BRM System Administrator's Guide.
Map the item tags you created to custom item types by following the instructions in the file.

For example, to map the item tag new_york to the item type /item/new_york, add the following entry:
```
<ItemTypeElement>
    <ItemTag>new_york</ItemTag> 
    <ItemDescription>Calls from New York</ItemDescription>
    <ItemType precreate="false" type="cumulative">/item/new_york</ItemType> 
</ItemTypeElement>
```
where:
- The ItemTag element specifies the name of the item tag.
- The ItemDescription element specifies the item name that is displayed in customer invoices, reports, and CSR applications.
- The precreate element specifies whether BRM pre-creates the item for the service type: true specifies to pre-create the item in the database, and false specifies to create the item when the event occurs.
  
  Note:
  
  BRM pre-creates items for usage events only. It does not pre-create items for purchase or cycle fee events.
- The type element specifies whether to track balances separately or to consolidate balances: cumulative specifies that this bill item stores charges for all events of the same type in a billing cycle; individual specifies to create a separate item for each event. See "Tracking Charges in Bill Items" for more information.
  
  Note:
  If you have set precreate to false for the usage or delayed events that are rated using Pipeline Manager, do not set the type to individual.
- The ItemType element specifies the name of the custom /item object. In this example, BRM stores the item charges in the /item/new_york object.
Save the file. You can save the file with a different name and location or use the original file.
Run the following command:
```
load_config_item_types config_item_types_file  
```
where config_item_types_file is the name and path of your config_item_types.xml file.

Caution:

The load_config_item_types utility replaces the entire contents of the /config/item_types object whose PIN_FLD_NAME value matches the Name value in the config_item_types.xml file with the contents of that file. If you are updating a set of mappings, you cannot load new item types only. You must load complete sets of mappings each time you run the load_config_item_types utility.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

To verify that the item tags were loaded, use Object Browser in Developer Center or the testnap utility's robj command to display the specified /config/item_types object. See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Assigning Bill Items to Event Balance Impacts

All events contain, or can contain, a balance impact. You can use custom /item types to separately track charges in individual balance impacts of an event. For example, even though only one BRM event is recorded for a service, if you charge for both connection time and the amount of bytes transferred during a session, the two charges can be tracked separately.

PIN_FLD_ITEM_TAGS is an array in the output flist of the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode. The PIN_FLD_ITEM_TAGS enables you to create an item tag for one or more balance impacts. You choose from an event, which balance impacts to use, and what item tags they are assigned to. The item type is assigned using the matching element ID of the item tag and balance impact.

The following example, lists the account POID and custom item tags in flist array format. Balance impacts with element IDs 2 and 3 have item types assigned based on the item tags TransferVolume and ConnectionPeriod. All other balance impacts have an item type assigned based on the item tag SessionUsage.

0     PIN_FLD_POID                POID [0] 0.0.0.1 /account 182477 0
0     PIN_FLD_ITEM_TAG             STR [0] SessionUsage
0     PIN_FLD_ITEM_TAGS          ARRAY [2] allocated 20, used 3
1     PIN_FLD_ITEM_TAG             STR [0] TransferVolume
0     PIN_FLD_ITEM_TAGS          ARRAY [3] allocated 20, used 3
1     PIN_FLD_ITEM_TAG             STR [0] ConnectionPeriod

Note:

If a PIN_FLD_ITEM_TAGS array element is not specified for a balance impact, the balance impact will have an item assigned based on the PIN_FLD_ITEM_TAG element at the top level of the policy opcode output.

To assign bill items to event balance impacts:

Create your custom balance impact item tags and types. See "Setting Up BRM to Assign Custom Bill Items to Events".
Map your custom balance impact item tags to your custom balance impact item types. See "Mapping Item Tags to Item Types".
Customize the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode with the appropriate business logic to:
1. Determine the element ID of the required balance impact of the event in the input flist of the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode.
2. Create a PIN_FLD_ITEM_TAGS array element in the output flist of the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode with the element ID being the same as the balance impact ID from step a.
3. Set the field PIN_FLD_ITEM_TAGS of the PIN_FLD_ITEM_TAGS array element to the custom value of the item tag that you require for the balance impact.
  
  For information about customizing policy opcodes, see Using the Policy Opcode Source Files in BRM Developer's Guide.
Assign your custom items to event balance impacts during the rating process.

By default, any item tag specified for a sharing group owner's balance impact is ignored and an item of type /item/sponsor is used. A custom item type can be assigned for a sharing group owner's balance impact only in the following situations:

The SplitSponsorItemByMember business parameter is enabled. See "Splitting Sponsored Charges into Multiple Items".
A custom item tag is specified for the sharing group owner's balance impact in the PIN_FLD_ITEM_TAGS array.

Creating Custom Sponsored Bill Items

By default, BRM accumulates the charges for all charge sharing member services and accounts belonging to one owner in a single /item object.

You can create custom sponsored bill items that divide the accumulated charges across the members of the charge sharing group.

To create custom sponsored bill items:

Enable the SplitSponsorItemByMember business parameter. See "Splitting Sponsored Charges into Multiple Items".

The charges are broken down into:
- One /item/sponsor object for each charge sharing member service instance.
- One /item/sponsor object for account-level charges for all member accounts.
The sponsored items point to the owner account object and to the sharing member service. If the shared charges are at the member account level, the service pointer is NULL.
Create your custom balance impact /item/sponsor tags and types. See "Setting Up BRM to Assign Custom Bill Items to Events" and "Assigning Bill Items to Event Balance Impacts".

Note:

When configuring a custom item type for sharing group owner's balance impacts, specify the base type without the component sponsor in the item type string. For example, to use peak_usage for sponsored peak usage charges, configure the tag as /item/peak_usage. BRM automatically uses the correct sponsor subtype /item/sponsor/peak_usage at the time of rating.
Assign the custom sponsored items to event balance impacts during the rating process.

Splitting Sponsored Charges into Multiple Items

By default, splitting sponsored charges into multiple sponsored items is disabled. You can enable splitting sponsored charges for online charging, offline charging, or both.

If you split sponsored charges for offline charging, you do not have the option of disabling the pre-updater step of the Rated Event (RE) Loader. This is because the pre-updater stored procedure assigns sponsored items to events when the splitting option is enabled.

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

To enable splitting sponsored charges into multiple items:

Go to BRM_home/sys/data/config.

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

pin_bus_params -r SplitSponsorItemByMember -bus_params_billing.xml

In the XML file, change disabled to enabled:

<SplitSponsorItemByMember>disabled</SplitSponsorItemByMember>

Do one of the following:
- To enable splitting of sponsored charges for both online charging and offline charging, change disabled to enabled.
- To enable splitting of sponsored charges for only online charging, change disabled to onlyRealTime.
- To enable splitting of sponsored charges for only offline charging, change disabled to onlyBatch.
```
<SplitSponsorItemByMember>disabled</SplitSponsorItemByMember>
  
```
Save the file as bus_params_billing.xml.
Load the XML file into the BRM database:
```
pin_bus_paramsbus_params_billing.xml
```
Stop and restart the CM.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see BRM System Administrator's Guide.