11 Creating Custom Bill Items

This chapter describes how to create custom bill items and how Oracle Communications Billing and Revenue Management (BRM) assigns custom bill items to events. To use this feature, you must understand the following BRM concepts and tasks:

About Custom Bill Items

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

Bill items are also included in customer invoices, BRM reports, and customer service representative (CSR) applications as a way to summarize account activity in a billing cycle. For example, the Item Summary window in the Customer Center application shown in Figure 11-1 summarizes the total charges for service usage and cycle forward fees for an account:

Figure 11-1 Invoice Bill Items for Service Usage and Cycle Forward Fees

Description of Figure 11-1 follows
Description of ''Figure 11-1 Invoice Bill Items for Service Usage and Cycle Forward Fees''

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

About 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 Internet 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 11-2:

Figure 11-2 Rolled-Up Internet Usage Charges on Invoice

Description of Figure 11-2 follows
Description of ''Figure 11-2 Rolled-Up Internet Usage Charges on Invoice''

Individual bill items store a charge for a single event, such as purchasing a product. 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 11-3:

Figure 11-3 Individual Bill Items

Description of Figure 11-3 follows
Description of ''Figure 11-3 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:

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

Table 11-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

In Table 11-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 billinfo 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:

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:

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

  2. Add the following entry:

    – fm_act attach_item_to_event n

    where n can be 0, 1, or 2.

  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.

    For information about configuration files, see "Using Configuration Files to Connect and Configure Components" 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.

  • Roaming calls in a custom item object named /item/roaming.

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

Figure 11-4 Itemized List of GSM Usage

Description of Figure 11-4 follows
Description of ''Figure 11-4 Itemized List of GSM Usage''

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

How BRM Assigns Custom Bill Items to Events

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

  1. BRM assigns an item tag based on the event and service combination.

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

  3. BRM assigns an item type based on the item tag.

BRM can assign custom bill items to events during both real-time rating and batch rating. For details, see the following:

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.

  1. Open the BRM_Home/sys/data/pricing/example/config_item_tags.xml file.

  2. Add the following entry:

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

  3. Save and close the file.

  4. Open the BRM_Home/sys/data/pricing/example/config_item_types.xml file.

  5. Add the following entry:

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

  6. Save and close the file.

How Batch Rating Assigns Custom Bill Items

BRM batch rating uses the FCT_ItemAssign pipeline module to assign items based on event and service combinations and uses custom iScripts to assign items based on event attributes.

To assign items to events, Pipeline Manager performs these tasks:

  1. During initialization, the DAT_ItemAssign module loads the specified /config/item_types object into memory and reserves a pool of POID IDs. If the information in the DAT_ItemAssign config object changes, you can use the DAT_itemAssign module's Reload semaphore to refresh the configuration changes.

  2. Your custom iScript assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

  3. FCT_ItemAssign calls DAT_ItemAssign with the item tag in the DETAIL.ITEM_TAG EDR field.

  4. DAT_ItemAssign retrieves the item POID list from the DAT_AccountBatch module.

  5. DAT_ItemAssign retrieves the item type for the given item tag from the config/item_types object in memory and searches the POID list for a matching item type.

  6. If DAT_ItemAssign finds a matching POID, it returns that item POID (for example, 1 /item/new_york m m) to FCT_ItemAssign.

    If DAT_ItemAssign does not find a matching POID, it creates a new POID ID from the POID pool it reserved and returns the new POID ID to FCT_ItemAssign.

    When the DAT_ItemAssign module creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/new_york m m.

    If the DETAIL.ITEM_TAG field is NULL, DAT_ItemAssign returns a default item POID from the item POID list.

  7. The FCT_ItemAssign module assigns the item POID that it retrieves to the DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID EDR field for the product used for rating the event.

  8. For sponsored usage events, the following occurs:

    1. The FCT_BillingRecord module queries the DAT_ItemAssign module for items when required.

    2. The DAT_ItemAssign module returns the pre-created items of type /item/sponsor to FCT_BillingRecord for sponsored events.

    3. When the DAT_ItemAssign module creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/sponsor m m.

  9. Pipeline Manager generates the rated events.

You use Rated Event (RE) Loader to load the rated events into the BRM database and to update the account balances and create or update bill items. For more information, see "Understanding Rated Event Loader" in BRM Configuring Pipeline Rating and Discounting.

Figure 11-5 shows how items are assigned to events:

Figure 11-5 Assignment of Items to Events

Description of Figure 11-5 follows
Description of ''Figure 11-5 Assignment of Items to Events''

How Real-Time Rating Assigns Custom Bill Items

BRM real-time rating uses the PCM_OP_ACT_USAGE opcode to assign items by event and service combination and uses the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode to assign items by event attribute.

To assign items to usage events, BRM performs these tasks:

  1. PCM_OP_ACT_USAGE uses the appropriate /config/item_tags object to assign the item tag associated with the event and service combination.

  2. PCM_OP_ACT_USAGE calls the PCM_OP_BILL_POL_GET_ITEM_TAG policy opcode. If configured to do so, the policy opcode assigns a different item tag based on the event's attributes. By default, this policy opcode does nothing.

  3. PCM_OP_ACT_USAGE uses the appropriate /config/item_types object to assign the item type associated with the item tag.

  4. PCM_OP_ACT_USAGE assigns the event to an /item object, based on the item type:

    • Cumulative items: If the item already exists in the database, BRM assigns the event to the existing /item object. If the /item object does not already exist, BRM creates an /item object and then assigns the event to it.

    • Individual items: BRM creates a new /item object and assigns the event to it.

      Note:

      If no match is found, BRM assigns the event to either the account-level or the service-level /item/misc object, depending on whether the event belongs to an account or service.

  5. PCM_OP_ACT_USAGE updates the item balance totals and then records the event in the database.

About Bill Items and Universal Event Loader

If you use Universal Event (UE) Loader to load events that correspond to a cumulative bill item, you might see more than one bill item in BRM. To ensure that UE Loader handles cumulative bill items correctly, UE Loader must group events by account. You define this setting when you create the event template in the UE Mapper. For more information, start Developer Center and see UE Mapper Help.

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:

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

  2. Map event and service combinations to item tags in the appropriate item configuration. See "Assigning Item Tags Based on Event and Service Combinations".

  3. Map event attributes to item tags. See "Assigning Item Tags Based on Event Attributes".

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

  1. Open the BRM_Home/sys/data/pricing/example/config_item_tags.xml file in a text editor.

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

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

  4. Save the file. You can save the file with a different name and location or use the original file.

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

    Caution:

    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.

  6. 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. The method for assigning item tags differs for batch rating and real-time rating:

Setting Up Batch Rating to Assign Items Based on Event Attributes

To set up Pipeline Manager to assign item tags to events based on event attributes:

  1. Configure the following Pipeline Manager modules:

    • DAT_ItemAssign

    • FCT_ItemAssign

    • FCT_BillingRecord

  2. Create a custom iScript that assigns item tags based on event attributes. See "Creating a Custom iScript to Assign Item Tags".

  3. Load the rated events into the BRM database to update account balances and to create or update bill items. See "Loading the Rated Events into the BRM Database".

Creating a Custom iScript to Assign Item Tags

Create a custom iScript that assigns item tags based on event attributes and fills in the DETAIL.ITEM_TAG field in the EDR container. For information about creating an iScript and for the scripting language reference, see "Creating iScripts and iRules" in BRM Developer's Guide.

To enable your custom iScript to run in a pipeline, you must add an entry for it in the wireless.reg registry file. Configure this iScript to run after FCT_Account and before FCT_BillingRecord.

Sample registry entry:

# iScript to populate DETAIL.ITEM_TAG
#
IScript
{
  ModuleName = FCT_IScript
  Module
  {
   Active      = TRUE
   Source      = File
   Scripts
   {
    ItemTag
    {
     #iScript file that you created
     FileName = ./ISC_ItemTag.isc
    }
   }
  }
} 
# end of iScript

Loading the Rated Events into the BRM Database

You use Rated Event (RE) Loader to load rated events into the BRM database. Before updating items in the database, RE Loader checks the updater flag in the RE Loader Infranet.properties file. If the flag value is 1, RE Loader creates in the database the new item objects that were added. By default, the flag is set to 1.

For information on running RE Loader, see "Loading Prerated Events" in BRM Configuring Pipeline Rating and Discounting.

Setting Up Real-Time Rating to Assign Items Based on Event Attributes

You set up real-time rating 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.

For information about customizing policy opcodes, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.

Mapping Item Tags to Item Types

You map the item tags that you defined in the config_item_tags.xml file, custom iScript, 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.

Caution:

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:

  1. Open the BRM_Home/sys/data/pricing/example/config_item_types.xml file in an XML editor or a text editor.

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

  3. 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 "About Tracking Charges in Bill Items."

      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.

  4. Save the file. You can save the file with a different name and location or use the original file.

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

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

Note:

Tag names must be unique.

Note:

Associate the event with the EAI framework publishing opcode (opcode number 1301).

To verify that the item types 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.

Verifying Item-Tag-to-Item-Type Mapping

You can generate a log file that contains the item-tag-to-item-type mapping information from the DAT_ItemAssign memory.

To generate a log file of the mapping:

  1. Create a semaphore registry file with following entry:

    ifw.DataPool.ItemAssignDataModule.Module.PrintData=TagTypeMap.txt

  2. Copy the file into the semaphore directory. The default directory for semaphore files is BRM_Home/opt/ifw/semaphore.

Pipeline Manager generates the TagTypeMap.txt file, which contains the tag and type mapping from the DAT_ItemAssign module memory.

For example, the file contains entries as follows:

Total number of Tag and Type Mapping entries: 3
-----------------------------------------------------------
Tag : Type
-----------------------------------------------------------
cycle_forward : /item/cycle_forward
misc : /item/misc
newyork: /item/newyork

For more information, see "Semaphore File Syntax" in BRM System Administrator'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 as well as 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:

  1. Create your custom balance impact item tags and types. See "Setting Up BRM to Assign Custom Bill Items to Events".

  2. Map your custom balance impact item tags to your custom balance impact item types. See "Mapping Item Tags to Item Types".

  3. 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 "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.

  4. Assign your custom items to event balance impacts during the rating process as shown in "How Batch Rating Assigns Custom Bill Items to Events for Balance Impacts".

By default, any item tag specified for a sponsor balance impact is ignored and an item of type /item/sponsor is used. A custom item type can only be assigned for a sponsor balance impact if:

How Batch Rating Assigns Custom Bill Items to Events for Balance Impacts

BRM batch rating uses the FCT_ItemAssign pipeline module to assign items based on event and service combinations and uses custom iScripts to assign items based on event attributes and balance impacts. The FCT_BillingRecord pipeline module converts impacts from products (ChargePacket), discounts (DiscountPacket), and taxes (TaxPacket) to balance impacts.

For more information on creating a custom iScript for balance impacts, see "Creating a Batch Rating iScript for Balance Impacts".

To assign custom bill items to events for balance impacts, Pipeline Manager performs the following tasks:

  1. During initialization, the DAT_ItemAssign module loads the appropriate /config/item_types object into memory and reserves a pool of POID IDs. If the information in the DAT_ItemAssign config object changes, you can use the DAT_itemAssign module's Reload semaphore to refresh the configuration changes.

  2. Your custom iScript does the following:

    1. Assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

    2. Changes the item POID for a specific balance impact in the event, using the following ChargePacket, DiscountPacket, and TaxPacket EDR tag container fields:

      • DETAIL.ASS.CBD.CP.ITEM_TAG

      • DETAIL.ASS.CBD.DP.ITEM_TAG

      • DETAIL.ASS.CBD.TP.ITEM_TAG

  3. If the ChargePacket, DiscountPacket, and TaxPacket EDR container tag field values are NULL, FCT_ItemAssign calls DAT_ItemAssign with the item tag from the DETAIL.ITEM_TAG EDR field.

    If the ChargePacket, DiscountPacket, and TaxPacket EDR container tag field values are not NULL, FCT_ItemAssign calls DAT_ItemAssign with the item tag from the ChargePacket, DiscountPacket, and TaxPacket EDR container fields and the item tag from the DETAIL.ITEM_TAG EDR field.

  4. DAT_ItemAssign retrieves the item POID list from the DAT_AccountBatch module.

  5. DAT_ItemAssign retrieves the item type for the given item tag from the config/item_types object in memory and searches the POID list for a matching item type.

  6. If DAT_ItemAssign finds a matching POID, it returns that item POID (for example, 1 /item/new_york m m) to FCT_ItemAssign.

    If DAT_ItemAssign does not find a matching POID, it creates a new POID ID from the POID pool it reserved and returns the new POID ID to FCT_ItemAssign.

    When DAT_ItemAssign creates new items, it updates DAT_AccountBatch with the new items it created; for example, 1 /item/new_york m m.

    If the DETAIL.ITEM_TAG field is NULL, DAT_ItemAssign returns a default item POID from the item POID list.

  7. The FCT_ItemAssign module does the following:

    1. Assigns the item POID that it retrieves to the DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID EDR field for the product used for rating the event.

    2. Assigns the item POID that it retrieves from ChargePacket, DiscountPacket, and TaxPacket EDR container tag fields respectively to:

      • DETAIL.ASS.CBD.CP.ITEM_POID

      • DETAIL.ASS.CBD.DP.ITEM_POID

      • DETAIL.ASS.CBD.TP.ITEM_POID

    Note:

    If no item tags are configured for ChargePacket, DiscountPacket, and TaxPacket, FCT_ItemAssign replaces the corresponding packet's item POID with the updated POID from DETAIL.CUST_A.PRODUCT.SERVICE_USED_ITEM_POID.

  8. For sponsored usage events, the following occurs if the SplitSponsorItemByMember business parameter is enabled:

    1. Pipeline Manager receives input from the config_item_tags.xml and config_item_type.xml files to determine the sponsor item type.

    2. Assigns a type-only POID; for example, /item/sponsor/usage-1.

    3. The RE Loader assigns an appropriate sponsor item instance to the sponsor balance impacts.

  9. Pipeline Manager generates the rated events.

You use RE Loader to load the rated events into the BRM database and to update the account balances and create or update bill items. For more information, see "Understanding Rated Event Loader" in BRM Configuring Pipeline Rating and Discounting.

Creating a Batch Rating iScript for Balance Impacts

BRM batch rating uses custom iScripts to assign items based on event attributes.

Create a custom iScript that does the following:

  1. Assigns an item tag based on event attributes to the DETAIL.ITEM_TAG EDR field.

  2. Changes the item POID for a specific balance impact in an event, using the following fields in the EDR container:

    • DETAIL.ASS_CBD.CP.ITEM_TAG

    • DETAIL.ASS_CBD.DP.ITEM_TAG

    • DETAIL.ASS_CBD.TP.ITEM_TAG

To enable your custom iScript to run in a pipeline, you must add an entry for it in the wireless.reg registry file. Configure this iScript to run after FCT_Apply_Balance and before FCT_ItemAssign.

See "Creating a Custom iScript to Assign Item Tags" and "Assigning Item Tags Based on Event Attributes" for more information.

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 sponsored members of the account.

To create custom sponsored bill items:

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

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

    Important:

    When configuring a custom item type for sponsor balance impacts, specify the base type without the component sponsor in the item type string. For example, to use peak_usage for sponsor 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.

  3. Assign the custom sponsor items to event balance impacts during the rating process. See "How Batch Rating Assigns Custom Bill Items to Events for Balance Impacts".

Splitting Sponsored Charges into Multiple Items

By default, splitting sponsored charges into multiple sponsor items is disabled. You can enable the SplitSponsorItemByMember business parameter for real time rating, batch rating, or both.

To enable splitting sponsored charges into multiple items:

  1. Go to the BRM_Home/sys/data/config directory, where BRM_Home is the directory in which you installed BRM components.

  2. Run the following command, which creates an editable XML file from the billing instance of the /config/business_params object:

    pin_bus_params -r SplitSponsorItemByMember -bus_params_billing.xml

    This command creates the XML file named bus_params_billing.xml.out in your working directory. To place this file in a different directory, specify the path as part of the file name.

  3. Open the bus_params_billing.xml.out file.

  4. Search for the following line.

    <SplitSponsorItemByMember>disabled</SplitSponsorItemByMember>

  5. Do one of the following:

    • To enable splitting sponsor charges for both real time rating and batch rating, change disabled to enabled.

    • To enable splitting sponsored charges for only real time rating, change disabled to onlyRealTime.

    • To enable splitting sponsored charges for only batch rating, change disabled to onlyBatch.

      Important:

      If you set SplitSponsorItemByMember to onlybatch, 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 sponsor items to events when the splitting option is enabled.

  6. Save this file as bus_params_billing.xml.

  7. Go to the BRM_Home/sys/data/config directory, which includes support files used by the pin_bus_params utility.

  8. Run the following command, which loads this change into the appropriate /config/business_params object.

    pin_bus_params PathToWorkingDirectory/bus_params_billing.xml

    where PathToWorkingDirectory is the directory in which bus_params_billing.xml resides.

    Caution:

    BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM billing configurations.

    Note:

    To run this command from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  9. Read the object with the testnap utility or Object Browser to verify that all fields are correct.

    See "Using testnap" in BRM Developer's Guide for general instruction on using the testnap utility. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

  10. Stop and restart the CM. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  11. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.