1. Configuring Pipeline Rating and Discounting
  2. Configuring Pipeline Rating
  3. Configuring Pipeline Rating

2 Configuring Pipeline Rating

This chapter describes how to configure the Oracle Communications Billing and Revenue Management (BRM) pricing data and modules necessary for batch rating with Pipeline Manager.

About Configuring Function Modules for Pipeline Rating

Three groups of modules are involved in rating:

  • The pre-rating modules (FCT_ GlobalRating, FCT_CustomerRating, and FCT_RSC_Map) gather information and prepare the event data record (EDR) for rating.

  • The FCT_MainRating module applies charges and pricing to the EDR, creating charge breakdown data, including charge packets with charges.

  • The post-rating modules (FCT_RateAdjust and FCT_BillingRecord) make changes to the EDR after the charge data is included.

Multiple Pipeline Manager modules add and delete charge packet blocks to EDRs. Therefore, the value in the NUMBER_OF_CHARGE_PACKETS field does not reflect the actual number of charge packets in the charge breakdown record. You can get the correct number of charge packets by using the edrNumDatablocks function in a custom iScript module.

Depending on how your pipelines are set up, you need to configure some or all of these modules for rating.

About the Rating Data Modules

Configure the following data modules for rating:

About Using Filter Sets to Apply System Products and Discounts

Use filter sets to apply system products/charge offers and system discounts/discount offers to a select group of customers. For example, you can provide reduced international call rates for all customers with great credit.

When configured to use filter sets, the pipeline:

  1. Analyzes each EDR to determine whether it meets the criteria for a filter set.

  2. Adds any applicable system products/charge offers and system discounts/ discount offers, along with their priorities, to the EDR's list of purchased products/charge offers.

  3. Uses the product/charge offer and/or discount/discount offer when rating the EDR.

    Note:

    The actual product/charge offer or discount/discount offer the pipeline uses to rate the EDR depends on how your system is configured.

You use the following to configure your system for filter sets:

  • system_filterset_edr_field_values. This file specifies which EDR fields and values can be used as filter criteria. You must load this file into the BRM database prior to creating your filter sets.

  • IRL_UsageType. This iRule assigns usage types to an EDR. This signals the pipeline that the EDR qualifies for the special consideration that a filter set contains.

  • FCT_Filter_Set. This module determines whether an EDR qualifies for any filter sets, and, if it does, adds any applicable system products/charge offers and system discounts/discount offers to the EDR's list of purchased products/charge offers.

To configure BRM to use filters sets, perform the following tasks:

  1. Specify which EDR fields and values can be used as filter criteria and then load the data into the BRM database. See "Loading Filter Set Data into BRM".

  2. Define your filter sets by using a custom application. See "Defining Your Filter Sets".

  3. Configure the IRL_UsageType iRule to assign usage types to EDRs.

  4. Configure FCT_Filter_Set to apply system products/charge offers and discount/discount offers to specified market segments. See "FCT_Filter_Set".

  5. Connect the FCT_DiscountAnalysis module to the FCT_Filter_Set module. Use the FCT_DiscountAnalysis module's Filter_SetModule registry entry. See "FCT_DiscountAnalysis".

Loading Filter Set Data into BRM

You can specify the EDR fields and values that you can use as filter criteria. To do so, you edit the system_filterset_edr_field_values.en_US sample file in the BRM_home/sys/msgs/system_filter_set directory. BRM_home is the directory where you installed BRM components. For example, to use location as filter criteria, add these entries to the file: 

DETAIL.ASS_CAMEL_EXT.MSC_ADDRESS="London"
DETAIL.ASS_CAMEL_EXT.MSC_ADDRESS="Paris"

After defining the field values, you use the load_localized_strings utility to load the contents of the system_filterset_edr_field_values.locale file into the /strings object. To run the load_localized_strings utility, use this command: 

load_localized_strings system_filterset_edr_field_values.locale

Note:

If you are loading a localized version of this file, use the correct file extension for your locale.

Defining Your Filter Sets

You define your filter sets by creating a custom client application to call the filter set opcodes. BRM then stores data about each filter set in /filter_set/product objects in the BRM database.

Note:

To create and manage filter sets by using a custom client application, configure your application to call the filter set opcodes.

To create a filter set, perform the following:

  1. Create your system products/charge offers and system discounts/discount offers and associate them with specific service and event types. For example:

    • Create a system charge offer for /service/telco/gsm/telephony events that charges a flat rate of 5 cents per minute.

    • Create a system discount offer for /service/telco/gsm/sms events that provides a 20% discount for the first 10 minutes of usage.

  2. Create your filter sets by mapping filter criteria to system charge offers and system discount offers. When creating filter sets, you specify:

    • The conditions required for an EDR to qualify for a system charge offer or discount offer. That is, the list of required EDR fields and values for each filter set.

    • Applicable system products/charge offers and discounts/discount offers, along with their priority and validity dates.

    In Table 2-1, Filter_1 specifies that all GSM wireless calls made to Paris by customers with great credit qualify for a 20% discount.

    Table 2-1 Example Filters

    Filter name Filter criteria System charge offer or system discount offer Priority

    Filter_1

    DETAIL.ASS_GSMW_EXT.RECORD_TYPE="Great credit"

    DETAIL.ASS_CAMEL_EXT.MSC_ADDRESS="Paris"

    20% Discount

    3

    Filter_2

    DETAIL.ASS_GSMW_EXT.RECORD_TYPE="Great credit"

    Flat rate charge offer

    6

About Global Rating

Use global rating to rate every EDR by using the same set of charges. Global rating is performed by the FCT_ GlobalRating module. This module adds an associated charge breakdown record to the EDR. Each charge, or partial charge, from the global charges adds a charge packet.

Global rating is typically used for gathering data used for business planning. For example:

  • You can use global rating to calculate an average wholesale charge. You can then compare the average charge with the actual charge to find profit margins for different customer types.

  • You can use global rating to calculate an average retail charge. You can use this data to monitor unusual charge amounts that can indicate an error in a rating configuration.

To configure global rating, see "FCT_CustomerRating". Use the EdrRatePlans registry entry to specify the global charges. You can use this entry in a semaphore.

About Least Cost Rating

Use least cost rating to rate EDRs by using the charge offer that produces the lowest charge to customers. In this configuration, the pipeline:

  1. Rates EDRs by using all products/charge offers associated with an EDR and applies any discounts.

  2. Finds the charge and discount that produces the lowest charge.

  3. Applies the lowest charge to the customer's balance impact.

    Note:

    An EDR can qualify for either least cost rating or overlay promotion. It cannot qualify for both. See "About Overlay Promotions".

You use the following modules to find the lowest possible charge for an event:

  • The IRL_LeastCostPerEDR iRule screens EDRs for least cost rating. It compares each EDR against conditions that you specify. When an EDR meets the criteria, the module flags the EDR for least cost rating.

  • The FCT_CustomerRating module checks whether an EDR is flagged for least cost rating, and, if it is, generates breakdown records and associated charge packets for each charge offer. All charge packets are listed in order of priority, highest priority first.

  • The ISC_LeastCost iScript calculates the total charge for each charge offer and discount and flags the charge that produces the lowest charge. When the lowest charge is generated by a promotional charge offer, the module also calculates the total savings between the promotional charge offer and the lowest priority (base) charge offer.

You configure the modules in a discounting pipeline that includes the FCT_DiscountAnalysis module and the FCT_Discount module. These modules find any applicable discounts for each charge and calculate the discount for each charge packet.

Configuring Least Cost Rating

To set up least cost rating:

  1. Specify your least cost rating criteria. See "Specifying the Rules to Qualify for Least Cost Rating". To do so, you edit and configure the IRL_LeastCostPerEDR iRule. See "IRL_LeastCostPerEDR".

  2. Configure FCT_CustomerRating for least cost rating by using the LeastCostRating entry. See "FCT_CustomerRating".

  3. Configure the ISC_LeastCost iScript to find the lowest charge for customers. See "ISC_LeastCost".

Specifying the Rules to Qualify for Least Cost Rating

To specify which EDRs are flagged for least cost rating:

  1. Edit the pipeline_home/iScriptLib/iScriptLib_Standard/IRL_LeastCostPerEDR.irl file to include your rules for least cost rating. pipeline_home is the directory where you installed Pipeline Manager. The variables in the file correspond to positions in the IRL_LeastCostPerEDR.data file.

    For example, this rule specifies that EDRs matching the conditions in position 1 will have their DETAIL.CUST_A.LEAST_COST EDR field set to the value in position 2 of the IRL_LeastCostPerEDR.data file: 

    CONDITION:

SetLeastCostDefault ();
${1};

RESULT:
edrLong(DETAIL.CUST_A.LEAST_COST) = ${2};

  2. Edit the pipeline_home/iScriptLib/iScriptLib_Standard/IRL_LeastCostPerEDR.data file to include the conditions required for least cost rating. Use Boolean operators to specify the combinations of market segments and charge offer priorities for testing whether EDRs qualify for least cost rating. You can create any number of entries.

    For example, this rule specifies that only EDRs that meet both of these criteria are flagged for least cost rating (DETAIL.CUST_A.LEAST_COST set to 2):

    • MARKET_SEGMENT EDR field = 1234

    • Charge offer priority greater than 4

    segmentContains("1234") and priority()>4;2

  3. Configure the FCT_IRules module to point to IRL_LeastCostPerEDR.irl by using the following registry entries:

    Note:

    If you configure a pipeline to use filter sets, make sure IRL_LeastCostPerEDR runs after FCT_Filter_Set.

    See "IRL_LeastCostPerEDR".

About Calculating the Promotional Savings

You can calculate how much money your customers save when an event is rated with a promotional charge offer rather than a base charge offer by using promotional savings. Promotional savings allows you to calculate the difference in charges between a promotional charge offer and the base charge offer, so you can advertise the savings to your customers.

When configured for promotional savings, the pipeline:

  1. Rates EDRs by using the highest priority charge offer and the lowest priority (base) charge offer.

  2. Calculates the difference between the charge for the promotional charge offer and the charge for the base charge offer.

  3. Applies the savings amount to the EDR.

    Note:

    The pipeline applies the savings amount only when the promotional charge offer generates the lowest charge.

You use the following modules to calculate promotional savings:

  • The IRL_PromotionalSavingPerEDR iRule screens EDRs for promotional savings. It compares each EDR against your specified criteria. When an EDR meets the criteria, the module flags the EDR for promotional savings.

  • The FCT_CustomerRating module checks whether an EDR is flagged for promotional savings, and, if it is, generates separate charge breakdown records and associated charge packets for the highest priority (promotional) and lowest priority (base) charge offer.

  • The ISC_LeastCost iScript calculates the charges for the highest and lowest priority products/charge offers and calculates the total savings amount.

See "How Pipeline Modules Process Overlay Promotions" for information about how the processing of overlay promotions and promotional savings are related.

To set up promotional savings:

  1. Specify your promotional savings criteria. See "Specifying the Rules to Qualify for Promotional Savings".

  2. Configure FCT_CustomerRating for promotional savings by using the PromotionalSaving entry. See "FCT_CustomerRating".

  3. Configure ISC_LeastCost to calculate the promotional savings amount. See "ISC_LeastCost".

Specifying the Rules to Qualify for Promotional Savings

To specify which EDRs are flagged for a promotional savings calculation:

  1. Edit the pipeline_home/iScriptLib/iScriptLib_Standard/IRL_PromotionalSavingPerEDR.irl file to include your rules for qualifying for a promotional savings calculation. The variables in the file correspond to positions in the IRL_PromotionalSavingPerEDR.data file.

    For example, this rule specifies that EDRs matching the conditions in position 1 will have their DETAIL.CUST_A.PROMOTIONAL_SAVING EDR field set to the value in position 2:

    CONDITION:

${1};

RESULT:
edrLong( DETAIL.CUST_A.PROMOTIONAL_SAVING ) = ${2};

  2. Edit the pipeline_home/iScriptLib/iScriptLib_Standard/IRL_PromotionalSavingPerEDR.data file to include your conditions for qualifying for a promotional savings calculation. Use Boolean operators to specify the required combination of filter sets and charge offer priorities. You can create any number of entries.

    For example:

    productName("Standard GSM Telephony", "Highest") and priority("Highest") > 4 and usageStartTimeGreaterThan("20040101000000", "Highest") and serviceType("/service/telco/gsm/telephony", "Highest"); 2

productName("Standard GSM Telephony", "Base") and priority("Base") < 4 and usageStartTimeGreaterThan("20040101000000", "Base") and serviceType("/service/telco/gsm/telephony", "Base"); 2

  3. Configure the FCT_IRules module to run the IRL_PromotionalSavingPerEDR iRule. Use the PromotionalSaving entry to specify the path to your IRL_PromotionalSavingPerEDR iRules file.

    For more information, see "IRL_PromotionalSavingPerEDR".

About Overlay Promotions

Overlay promotions allow you to quickly and easily replace your existing products/charge offers and discounts/discount offers with special products/charge offers and discounts/discount offers that take precedence. For example, you may want to offer a special 10% discount for three months to your existing customers who have paid all their bills on time. To do this, you add a charge offer that offers the same services but costs10% less and has a higher priority than the original charge offer.

You do not need to create new zone models for promotional products/charge offers. Promotional products/charge offers can use the same zone models as standard products/charge offers. For example, you can create two promotional products/charge offers, CALL_USA and CALL_INDIA. You can give CALL_USA priority 4 and CALL_INDIA priority 2, while your base charge offer has priority 0. There is no need to create special zone models for the promotional charge offers. If a customer buys the promotional products/charge offers, BRM uses them to rate calls to the US and India. Calls to other countries will be rated using the base product/charge offer.

The capability to use overlay promotions is built into a pipeline, which:

  • Recognizes and uses product/charge offer priorities.

  • Allows you to associate multiple products/charge offers with the same service and event.

  • Allows you to rate calls using overlay promotions only.

    Note:

    The overlay promotions feature interacts with least cost rating and promotional savings. An EDR can qualify for either least cost rating or overlay promotion. It cannot qualify for both.

How Pipeline Modules Process Overlay Promotions

The overlay promotions feature requires no special configuration of pipeline modules. The following modules are involved in the processing of overlay promotions:

  • FCT_CustomerRating. The module creates a list of associated charge breakdowns and corresponding charge packets ordered from highest to lowest priority. If two products/charge offers have the same priority, the charge offer with the earliest start time is given a higher priority.

    The module then determines whether an EDR qualifies for least cost rating or overlay promotions. If the EDR qualifies for overlay promotions, the module further checks whether the EDR qualifies for promotional savings.

    Note:

    An EDR can qualify for either least cost rating or overlay promotion. It cannot qualify for both. If the EDR qualifies for overlay promotion, it may also qualify for promotional savings.

    If the EDR is eligible for least cost rating, FCT_CustomerRating performs these tasks:

    • Enables least cost rating by setting the DETAIL.CUST_A.LEAST_COST field to 2.

    • Disables promotional savings and overlay promotion by setting the DETAIL.CUST_A.PROMOTIONAL_SAVING and DETAIL.CUST_A.PROMOTION fields to 1.

    If the EDR is eligible for overlay promotions and promotional savings, FCT_CustomerRating performs these tasks:

    • Enables promotional savings by setting the DETAIL.CUST_A.PROMOTIONAL_SAVING field to 2.

    • Disables overlay promotions and least cost rating by setting the DETAIL.CUST_A.PROMOTION and DETAIL.CUST_A.LEAST_COST fields to 1.

    If the EDR qualifies for overlay promotions but not promotional savings, FCT_CustomerRating performs these tasks:

    • Enables overlay promotions by setting the DETAIL.CUST_A.PROMOTION field to 2.

    • Disables least cost rating and promotional savings by setting the DETAIL.CUST_A.LEAST_COST and DETAIL.CUST_A.PROMOTIONAL_SAVING fields to 1.

  • FCT_PreRating. The module populates the zoning information for each charge breakdown record in the EDR:

    • If least cost rating is used, the module finds the zoning information for all charge breakdown records. See "About Least Cost Rating".

    • If promotional savings or overlay promotion is used, the module finds the zoning information for at least one charge breakdown record. See "About Overlay Promotions".

  • FCT_MainRating. The module functions differently depending on whether the EDR is rated in least cost rating, overlay promotion, or promotional savings mode:

    • Least cost mode. The module rates all charge breakdown records. If it fails to rate any charge breakdown record, it returns an error. See "About Least Cost Rating".

    • Overlay promotion mode. The module tries to rate charge breakdown records starting with the highest priority record. If rating is successful for a charge breakdown record, the module selects the charge of that record and populates the INTERN_FOUND_PP_INDEX field with the index of that charge. The module then deletes all other charge breakdown records from the container.

    • Promotional savings mode. The module tries to rate charge breakdown records, starting with the highest priority record. If rating is successful for a charge breakdown record, the module selects the charge of that record and populates the INTERN_FOUND_PP_INDEX field with the index of that charge. The module continues rating charge breakdown records until it reaches the last record. It then checks for and selects the last successfully rated record. The module keeps the first and last successful charge breakdown records in the EDR container but deletes all others. See "About Calculating the Promotional Savings".

About Rating with Products and Discounts Whose Validity Starts on First Usage

The effective period of an account's products/charge offers and discounts/discount offers can start when the products/charge offers and discounts/discount offers are first used to rate a subscriber's usage.

If products/charge offers or discounts/discount offers are configured to start on first usage, you set up pipeline rating to set their validity periods when first usage occurs.

Note:

Balance Elements that are granted by products/charge offers and discounts/discount offers can also start on first usage. To set balance element validity when first usage occurs, you configure the batch discounting pipeline. See "About Setting the Validity of Balance Elements Impacted by Discounts".

When configured to set validity on first usage, the pipeline:

  1. Suspends EDRs that use products/charge offers or discounts/discount offers configured to start on first usage until the product/charge offer and discount/discount offer validity periods are set.

    EDRs are not suspended when first-usage balance element validity is set because the pipeline calculates and stores the validity period in memory. The pipeline uses the stored validity period if it needs to consume balance elements for any other events before the balance validity period has been set in the database.

  2. Sends the charge offer or discount offer information to a file in the output stream.

    BRM processes the file, sets the validity periods in the database, and charges any applicable purchase and cycle fees. While their validity periods are being set, the products/charge offers and discounts/discount offers are locked.

  3. If the event is discounted and the discount balance impact consumes a balance element balance that starts on first usage, the pipeline sends the balance element information to a file in the output stream.

    BRM processes the file and sets the balance element validity periods in the database. If the validity period of all first-usage balance elements are configured to be synchronized, BRM also sets the validity period of those balance elements.

  4. Rates the events when the EDRs are recycled.

If the pipeline transaction is rolled back or canceled, the validity period of any charge offer or discount offer that was set in the transaction is unset.

BRM uses the Account Synchronization Data Manager (DM) to synchronize charge offer and discount offer validity periods in the BRM database and pipeline memory.

The following modules are involved in setting the effective periods of products/charge offers and discounts/discount offers:

  • The FCT_FirstUsageNotify module. See "About Suspending EDRs for Products and Discounts that Start on First Usage".

  • The DAT_AccountBatch module determines if an account's products/charge offers and discounts/discount offers start on first usage, determines the state of the validity period, and calculates the validity periods based on the EDR timestamp. It sends this information to the FCT_Account module.

    The state of a validity period is used for coordinating the validity-setting and EDR-suspension processes. The state can be one of the following:

    • NOT_FirstUsage: Indicates that the charge offer or discount offer's validity period is already set in the database.

    • NEW_FirstUsage: Indicates that the charge offer or discount offer is configured to start on first usage and that its validity period has not yet been initialized.

    • INIT_FirstUsage: Indicates that the charge offer or discount offer's validity period has been initialized but has not yet been stored in the database.

    If the validity periods of all first-usage balance elements in the bundle should be synchronized, DAT_AccountBatch retrieves a list of the balance groups that have first-usage validity and are associated with the products/charge offers or discounts/discount offers in the bundle.

  • The FCT_ApplyBalance module. See "About Setting the Validity of Balance Elements Impacted by Discounts".

  • The OUT_GenericStream module and related modules. See "Configuring Pipeline Output for First-Usage Products, Discounts, and Balance Elements".

To set the validity for products/charge offers and discounts/discount offers that start on first usage, you must also perform these tasks:

About Suspending EDRs for Products and Discounts that Start on First Usage

Use the FCT_FirstUsageNotify module to suspend EDRs while BRM sets the validity periods of products/charge offers and discounts/discount offers that start on first usage. See "FCT_FirstUsageNotify".

Note:

To recycle and rate EDRs that are suspended while validity is being set, you must configure BRM standard recycling. See "Configuring Standard Recycling".

If a call details record (CDR) uses both a charge offer and a discount offer that start on first usage for the first time, the EDR is suspended and recycled twice: once to set the charge offer validity period and again to set the discount offer validity period. This is because the charge offer may grant balance elements that can be impacted by the discount offer, so the charge offer's purchase and cycle events need to be processed before the discount offer is evaluated.

The FCT_FirstUsageNotify module performs the following tasks:

  1. Checks whether the products/charge offers and discounts/discount offers used to rate an EDR have validity periods that start on first usage.

  2. If a product/charge offer and discount/discount offer starts on first usage, flags the EDR for suspense and recycling by setting the ERR_FIRST_USAGE_VALIDITY_NEEDS_INITIALIZING error code and the FirstUsageValidity recycle key in the EDR.

  3. Notifies the DAT_AccountBatch module that the validity period of the charge offer or discount offer is being set.

  4. Sends the charge offer and discount offer validity information to a separate output stream.

  5. Continues to flag for suspense and recycling subsequent EDRs that use the products/charge offers or discounts/discount offers with first-usage validity until the validity period is set.

FCT_FirstUsageNotify predetermines whether the FCT_Reject module will reject an EDR. FCT_FirstUsageNotify does not process EDRs that will be rejected because product/charge offer, discount/discount offer, or balance element validity should not be set for EDRs that will be otherwise suspended.

Configuring Pipeline Output for First-Usage Products, Discounts, and Balance Elements

In the batch rating pipeline, you configure two output streams: one for files containing products/charge offers and discounts/discount offers that start on first usage, and another for files containing balance elements that start on first usage.

To create the first-usage output streams, configure the following:

Configuring First-Usage Output Streams

Configure the OUT_GenericStream module to write the first-usage products/charge offers, discounts/discount offers, and balance elements to an output file.

The default output grammar description files are:

  • For products/charge offers and discounts/discount offers, FirstUsageNotify_OutGrammar.dsc.

  • For balance elements, FirstUsageResource_OutGrammar.dsc.

In the EXT_OutFileManager section of the registry, specify the temporary file specifications as follows:

  • For first-usage products/charge offers and discounts/discount offers:

    OutputPath = ./data/out/firstUsage/prod_disc
OutputPrefix = test_PROD
OutputSuffix = .out_1
TempPrefix = .
TempDataPath    = ./data/out/firstUsage/prod_disc
TempDataPrefix  = prod.tmp.
TempDataSuffix  = .data_1

  • For first-usage balance elements: 

    OutputPath = ./data/out/firstUsage/resources
OutputPrefix = test_RES
OutputSuffix = .out_1
TempPrefix = .
TempDataPath    = ./data/out/firstUsage/resources
TempDataPrefix  = res.tmp.
TempDataSuffix  = .data_1

    See "OUT_GenericStream".

Specifying the First-Usage Format and Mapping Files in the DataDescription Registry

Configure the first-usage stream formats, input mapping, and output mapping in the batch pipeline DataDescription registry section as follows:

DataDescription
{ 
   Standard 
   { 
   ModuleName = Standard 
   Module 
   { 
   StreamFormats
   {
      FIRST_USAGE_NOTIFY_OUTPUT=./formatDesc/Formats/FirstUsageNotify/FirstUsageNotify.dsc 
      FIRST_USAGE_RESOURCES=./formatDesc/Formats/FirstUsageNotify/FirstUsageResource.dsc
   }
   . . .
   OutputMapping
   {
      FIRST_USAGE_PROD_DISC=./formatDesc/Formats/FirstUsageNotify/FirstUsageNotify_OutMap.dsc
      FIRST_USAGE_RESOURCES=./formatDesc/Formats/FirstUsageNotify/FirstUsageResource_OutMap.dsc

   }
   }
   }
}

For more information, see "Configuring Output for Rated Events".

About Updating Validity Period Information in the BRM Database

You use UE Loader to update validity periods in the BRM database when first usage occurs.

You use the ConfigurableValidityHandler batch handler to run the UE Loader utility (uel).

Perform the following tasks to update validity periods for first-usage products/charge offers, discounts/discount offers, and balance elements:

Loading the First-Usage Validity Templates

BRM provides two Universal Event (UE) Mapper event import templates that are used by UE Loader to process the first-usage product/charge offer, discount/discount offer, and balance element files output by the OUT_GenericStream module:

  • FirstUsageProductsDiscounts.xml: This template defines the format of the first-usage product/charge offer and discount files.

  • FirstUsageResources.xml: This template defines the format of the first-usage balance element files.

You must load these templates into the BRM database by running the pin_uei_deploy utility.

For example:

pin_uei_deploy -c -t FirstUsageProductsDiscounts -i BRM_home/formatDesc/Formats/FirstUsageNotify/FirstUsageProductsDiscounts.xml 

pin_uei_deploy -c -t FirstUsageResources -i BRM_home/formatDesc/Formats/FirstUsageNotify/FirstUsageResources.xml
Configuring the ConfigurableValidityHandler Batch Handler

BRM provides the ConfigurableValidityHandler batch handler for loading first-usage validity data. You must configure ConfigurableValidityHandler to run the following utilities:

  • pin_rel: This utility loads data for events that are rated in batches.

  • uel: This utility loads validity period data for products/charge offers, discounts/discount offers, and balance elements when they are used for the first time.

  • pin_load_rerate_jobs: You must also configure to run this utility if you configured Pipeline Manager to detect and rerate events that are rated out of order. This utility creates rerate jobs for the events that were rated out of order.

For more information, see "About Using a Single Batch Handler to Run Multiple Loading Utilities".

To configure the ConfigurableValidityHandler batch handler, you edit the handler's configuration file (BRM_home/apps/pin_rel/ConfigurableValidityHandler_config.values). You specify handler, processing, and staging directories for each loading utility that this batch handler runs.

Configuring Batch Controller to Start the ConfigurableValidityHandler Batch Handler

Batch Controller polls the pipeline output directories and starts the ConfigurableValidityHandler batch handler when a data file is ready to be loaded.

Note:

If you use the ConfigurableValidityHandler batch handler, do not configure Batch Controller to run a separate instance of the handlers that load pipeline batch-rated events, out-of-order rerating requests, or first-usage validity data. (You may configure a separate instance of the Rated Event (RE) Loader handler that loads suspended events into /suspended_usage objects.) If you have already configured Batch Controller to run the out-of-order event handler (OODHandler), remove those entries or comment them out.

To configure Batch Controller to start the ConfigurableValidityHandler batch handler:

  1. Open the Batch Controller Infranet.properties file in BRM_home/apps/batch_controller.

  2. Edit the file to include entries for the ConfigurableValidityHandler batch handler.

    Note:

    • If you have already configured the Batch Controller Infranet.properties file for RE Loader, you can use the existing RE Loader entries and most of their values or you can change them. Entries that you must change are marked with an asterisk (*).

    • If you have not yet configured the Batch Controller Infranet.properties file for RE Loader, you must add ConfigurableValidityHandler values for all of the following entries.

    Table 2-2 lists the entries you must set and the default values used for RE Loader:

    Table 2-2 Entries for RE Loader

    Entry Description

    batch.random.events

    Identifies this specific configuration for triggering Batch Controller. For example:

    batch.random.events   CdrFileEvent

    event_name.name

    (Optional) A name for the configuration identifier. For example:

    CdrFileEvent.name   CdrFileEvent

    event_name.handlers

    The batch handler identifier. For example:

    CdrFileEvent.handlers   ConfigurableValidityHandler

    The default is relHandler.

    event_name.file.location

    The full path to the pipeline output directory where the rated-event files are deposited. For example:

    CdrFileEvent.file.location   /export/portal/integRate

    event_name.file.pattern

    The rated-event output file name.

    You can use an asterisk (*) to represent zero or more characters in the file name. No other wildcards (metacharacters) are supported.

    For example:

    CdrFileEvent.file.pattern   cdr*.dat

    *handler_name.name

    The name of the batch handler that is run. For example:

    ConfigurableValidityHandler.name ConfigurableValidityHandler

    Note: If you did not change the default RE Loader value for event_name.handlers, this entry should be: 

    relHandler.name   ConfigurableValidityHandler

    handler_name.max.at.lowload.time

    handler_name.max.at.highload.time

    The number of batch handler instances that can run concurrently during periods of low load and high load usage. Typical default settings are 6 at low load and 3 at high load. For example: 

    ConfigurableValidityHandler.max.at.highload.time   3
ConfigurableValidityHandler.max.at.lowload.time   6

    *handler_name.start.string

    The full path to the ConfigurableValidityHandler handler. For example:

    ConfigurableValidityHandler.start.string   BRM_home/apps/pin_rel/ConfigurableValidityHandler.pl

    Note: If you did not change the default RE Loader value for event_name.handlers, this entry should be: 

    relHandler.start.string   BRM_home/apps/pin_rel/ConfigurableValidityHandler.pl

  3. Save and close the file.

  4. Stop and restart Batch Controller.

Setting Up Recycling for Events whose Product or Discount Validity Starts on First Usage

To suspend and recycle EDRs while product/charge offer and discount/discount offer validity is being set, you must configure BRM standard recycling. See "Configuring Standard Recycling".

For information about standard recycling, see "About Standard Recycling".

To recycle events suspended due to first-usage validity, you run the pin_recycle utility. Use the -k parameter and specify the FirstUsageValidity recycle key. For example: 

pin_recycle -k FirstUsageValidity

For more information, see "Using Standard Recycling to Recycle Suspended EDRs" and "pin_recycle".

About First-Usage Validity for Events Rated Out of Order

In the batch rating pipeline, if events are rated in a different order than they occurred, validity periods that are based on first usage may be incorrectly set. This can happen if the first event rated, which initiated the validity period, wasn't actually the first usage event. To correct the validity periods, you must rerate the events. Rerating corrects the order of the events and resets the validity period based on the actual first-usage event.

About Customer Rating

Customer rating assigns a charge to an EDR based on customer data. The FCT_CustomerRating module performs customer rating. The module creates an associated charge breakdown record and one charge packet, which includes the charge code. The FCT_MainRating module uses the charge code to rate the event.

To assign the charge, the FCT_CustomerRating module does the following:

  • If the service that generated the event includes a service-level charge extended rating attribute (ERA), that charge is used.

    If you're using subscription services, and a subscription service and member service both own a service-level charge ERA, the member service's ERA has priority and is used for selecting the charge.

  • If there is no service-level charge ERA, but there is an account-level charge ERA, that charge is used.

  • If there is no charge ERA, the charge associated with the last product/charge offer found is used when there is more than one product/charge offer available.

To configure customer rating, see "FCT_CustomerRating".

Assigning a Default Charge and Default Segment for Customer Rating

When you configure the FCT_CustomerRating module, you can assign a default charge and default segment to use if no customer information for the A number is found.

  • Use the DefaultRateplan entry to specify the default charge name in case there is not enough information to assign a charge. You can change this value by using a semaphore.

  • Use the DefaultSegment entry to specify if segment rating is used, the default segment to use if no segment is found. You can change this value by using a semaphore.

See "FCT_CustomerRating".

About Customer Rating and Service Level Agreements

You define service-level agreement (SLA) codes in Pricing Center or Pipeline Configuration Center (PCC) to map service level agreements (SLAs) to a usage-scenario (USC) group, rate-service class (RSC) group, and rule set. The SLA mapping is stored in the IFW_SLA database table.

During customer rating, if the FCT_CustomerRating module finds an SLA code, the module looks up the code in the IFW_SLA database table and adds the following data to the charge packet:

  • RSC group

  • USC group

  • Rule set

Pipeline Manager can use any one of these to determine the rate for the service level usage:

  • The RSC group is used by the FCT_RSC_Map module to find the RSC map. FCT_RSC_Map maps the usage class, usage type, service code, and impact category to a new service class. See "About Setting Up RSC Mapping".

  • The USC group is used by the FCT_USC_Map module to find the USC map. FCT_USC_Map maps the usage class, usage type, service code, service class, and zone to a new usage type and impact category.

About Rate-Service Class Mapping

You map a rate-service class (RSC) to perform rating based on the quality of service (QoS) when you set up service-level agreements (SLAs). RSC mapping is performed by the FCT_RSC_Map module, which maps the usage class, usage type, service code, and impact category to a new service class.

You create RSC map groups to provide a different service class for each level of service quality. You link the RSC map group to an SLA code in Pricing Center or Pipeline Configuration Center (PCC). The FCT_CustomerRating module looks up the SLA code and adds the associated RSC group to the charge packet (see "About Customer Rating and Service Level Agreements"). FCT_RSC_Map uses the RSC group to evaluate the EDR and find the correct RSC map.

The RSC map group is specified in the INTERN_SLA_RSC_GROUP field of the EDR. This field is filled in by FCT_CustomerRating when the product/charge offer includes a service-level agreement ERA. If INTERN_SLA_RSC_GROUP is empty, the default RSC group is used. You specify the default RSC group in the DefaultRscGroup entry of the FCT_RSC_Map registry.

About Setting Up RSC Mapping

To set up RSC mapping, do the following:

  1. Use Pricing Center or Pipeline Configuration Center (PCC) to create RSC maps and RSC map groups.

  2. Use Pricing Center or PCC to create SLA codes and link them to RSC map groups.

  3. Configure FCT_RSC_Map. See "FCT_RSC_Map".

About RSC Maps

To assign a new service class to the EDR, FCT_RSC_Map reads data from the EDR and evaluates it according to the RSC map. An RSC map includes one or more mapping rules that specify the data that must be matched to apply the new service class.

When you create RSC maps, you create a mapping rule for each new service class. You can also define the order in which the rules are evaluated. The new service class is derived from the first rule that matches the data. If no matching rule is found, FCT_RSC_Map uses the default RSC map as defined in the registry. If no default value exists, no mapping is performed.

You can use the following EDR data to create an RSC mapping rule:

  • The charge used to rate the EDR

  • The QoS requested

  • Usage class

  • Usage type

  • Service code

  • Service class

  • Impact category

When you create the mapping rules, you can use regular expressions. For information on the regular expressions you can use, see "About Using Regular Expressions when Specifying the Data to Extract".

To create a valid mapping, the data in the EDR must match with all of the mapping data.

About Main Rating

The FCT_MainRating module carries out the pipeline rating functionality.

When an EDR is ready for rating, it includes all the data needed by FCT_MainRating; for example, the service class, usage class, zone, and charge. The module uses the charge to rate the EDR. To rate the EDR, the module uses information about dates, times, and the pricing to apply charges. When rating is finished, the EDR contains complete charge breakdown data, including charge packets with charges.

FCT_MainRating uses criteria in the charge configuration that apply to an EDR to find the correct pricing to use for rating. If a single event is rated by using different time periods, such as peak and off-peak, more than one pricing can be used. If an event is mapped to a price selector, the model selector's rules are evaluated to choose a pricing.

If the charge configuration includes an alternative pricing, the module creates a new charge packet. The EDR is rated again by using the alternative pricing. The charge packet is flagged with the A (Alternative) pricing type.

During main rating, the module checks for the RUM group associated with the service code. At least one charge packet is added to the EDR for each RUM assigned to the RUM group. A single charge packet is generated for each time period, RUM, and balance element that is used. (The balance elements are defined in the pricing.)

To configure main rating, see "FCT_MainRating".

About Rate Adjustment

You use rate adjustments to provide discounts based on date, time, service, and other event attributes.

To set up rate adjustment, do the following:

  1. Create rules that specify which EDRs to adjust and how to adjust them. You have two options:

    • Create rate adjustment rules in Pricing Center or Pipeline Configuration Center (PCC). In this case, the rate adjustment data is stored in the Pipeline Manager database.

    • Create a file that defines usage scenario maps. In this case, the FCT_RateAdjust module reads the file. For information on creating the file, see "Creating a Rate Adjustment Rules File".

  2. Configure FCT_RateAdjust. See "FCT_RateAdjust".

Creating a Rate Adjustment Rules File

The rate adjustment rules can be defined in an ASCII file:

  • Each rule consists of a list of fields. The following table describes the meaning of each field.

  • Every new line defines an adjustment rule.

  • Fields are separated by semicolons (;).

  • Comment lines start with #.

  • Empty lines are allowed.

    Note:

    The value of the field rank is ignored. The evaluation order of the rules is given by the order of the rules within the file.

Table 2-3 lists the fields in the file:

Table 2-3 Fields in a Rate Adjustment File

Position Field Description

1

Rank

Specifies the evaluation order of the rules.

This is ignored because the evaluation order is specified within the file.

2

Rate plan

Specifies the charge to adjust.

3

Rate plan version

Specifies the charge version.

4

Valid from

Specifies the start date for the rate adjustment.

This can be either a date with the format YYYYMMDD or a weekday with an optional timestamp; for example:

  • 19990524

  • SAT

  • MON16:00

If the field is left empty, the earliest possible date (19010101) is used.

5

Valid to

Specifies the end date for the rate adjustment.

This can be either a date with the format YYYYMMDD or a weekday with an optional timestamp.

If the field is left empty, the latest possible date (20370205) is used.

6

Time from

Specifies the start time for the rate adjustment.

The format is HH:MM.

The default is 00:00.

7

Time to

Specifies the end time for the rate adjustment.

The format is HH:MM.

Example: To set up a discount that is valid on weekends between 13:00 and 14:00, you have to set the following:

  • ValidFrom = SAT

  • ValidTo = SUN

  • TimeFrom = 13:00

  • TimeTo = 14:00

8

Quantity value

Specifies the maximum quantity value for an EDR container. If this maximum is exceeded, the mapping rule will not be used. If this field is left empty or if a 0 is specified, the rule is valid for every quantity value.

Example: You can use this entry to avoid discounting for calls longer than 120 seconds by setting the field to 120.

9

Usage class

Specifies the compare pattern for the usage class.

10

Usage type

Specifies the compare pattern for the usage type.

11

Service code

Specifies the compare pattern for the service code.

12

Service class

Specifies the compare pattern for the service class.

13

Impact category

Specifies the compare pattern for the impact category.

14

Source network

Specifies the compare pattern for the source network.

15

Destination network

Specifies the compare pattern for the destination network.

16

Discount type

Specifies the discount type.

17

Discount value

Specifies the discount value.

18

Comment

Specifies the rate adjustment name.

About Consolidation for BRM Billing

The FCT_BillingRecord module consolidates charge packets and discount packets into an associated BRM billing record in the EDR. This data is loaded as a rated event by RE Loader.

The associated BRM billing record includes the POIDs of the /account object and the /service object and the POID of the item that receives the balance impact. If an event affects more than one customer balance, an associated BRM billing record is created for each balance.

An associated BRM billing record can contain one or more balance impact packets. The data in a balance impact packet is loaded into an /event object balance array. Therefore, the data includes information about the charged amount, the charge, and balance elements.

The balance impact packet also includes data in the PIN_INFO_STRING field. This field contains the information about the individual charge packets.

Each balance impact packet includes data for one balance impact per balance element. If there are different G/L IDs for the same balance element, a balance impact packet is created for each G/L ID.

To configure FCT_BillingRecord, see "FCT_BillingRecord".

Note:

Don't use FCT_BillingRecord in a CIBER roaming revenue assurance environment. For more information, see "Billing Consolidation with CIBER Roaming and Revenue Assurance".

How the FCT_BillingRecord Module Works

FCT_BillingRecord uses the data in the EDR to determine if the charges should be included in the associated BRM billing record. To do so, the module checks the following data. If any of these do not match, no associated billing record is created.

  • The record type must be 981. This record type is created by the FCT_CustomerRating module for customer rating.

  • The charge packet must use the following:

    • The standard pricing type: PRICEMODEL_TYPE = S

    • A retail charge: RATEPLAN_TYPE = R

    • A currency type that matches the currency type specified in the FCT_BillingRecord module registry. The options are Home, Billing, and Rating.

    • A currency that matches one of the entries specified in the FCT_BillingRecord module registry. See "FCT_BillingRecord".

If the charge packet meets the criteria, the module sums the amount, discount, and quantity for each BRM balance element and creates the associated BRM billing record and one or more balance impact packets.

For balance monitoring, FCT_BillingRecord generates a monitor packet for each monitor group.

To get data, FCT_BillingRecord connects to the following data modules:

  • The DAT_AccountBatch module, which provides data about items.

  • The DAT_ItemAssign module, which provides data about items assigned for sponsorship events.

  • The DAT_Currency module, which provides data for converting currency symbols to numeric values.

  • The DAT_BalanceBatch module, which provides the ObjectCacheType value from the /balance_group object.

Billing Consolidation with CIBER Roaming and Revenue Assurance

For CIBER roaming and revenue assurance, use the ISC_PostRating iScript instead of FCT_BillingRecord.

ISC_PostRating adds all the retail and wholesale charges and puts them in the DETAIL.RETAIL_CHARGED_AMOUNT_VALUE and DETAIL.WHOLESALE_CHARGED_AMOUNT_VALUE fields.

Note:

ISC_PostRating and FCT_BillingRecord perform similar billing consolidation, but ISC_PostRating doesn't load balance impact data into the database.

See "ISC_PostRating".

How the ISC_PostRating iScript Works

ISC_PostRating sets the following attributes:

  • Wholesale and retail impact category

  • Charged amount value

  • Amount currency

  • Tax treatment

for an EDR based on these values specified in the Pipeline Manager registry:

  • Balance Element type

  • Pricing type

  • Currency type

    Note:

    This iScript accesses only EDR fields. It doesn't access the database.

Adding Pipeline Rating Data to an Invoice

When you rate usage by using pipeline rating, information about how events are rated are stored in the EDR. You can display this information on invoices. For example, if a call spans two rates, for peak and off-peak time, you can display the rate used for each part of the call. For example:

Table 2-4 Displaying Pipeline Rating Data

Date/time Called number Duration Average rate per unit Total charge

12/12/2003 1200

4085551212

10min

$0.125

$1.25

12/12/2003 1200

4085551212

5min

$0.15

$0.75

12/12/2003 1200

4085551212

5min

$0.10

$0.50

In the example shown in Table 2-4, the data is stored in the INTERN_PRICE_MDL_STEP_INFO EDR field.

To add pipeline rating invoice data to your invoices, you need to configure the OUT_GenericStream module AddInvoiceData registry entry to add the data to the BRM billing record.

Specifying Invoice Data from Pipeline Manager and Custom Applications

If you process events that originate in Pipeline Manager or a custom application, you can create a template to specify the event invoice data so that it can be included in your invoices.

BRM provides a default template file (pin_invoice_data_map) located in BRM_home/sys/data/config. This file includes a default INTEGRATE template for Pipeline Manager invoice data. You can modify the INTEGRATE template or add new templates to the file.

To use this feature, you must do the following:

Using Data Map Templates

Templates in the pin_invoice_data_map file define the fields in invoice data records. If you use different invoice record formats, you can create a template for each record format. The data map file can include any number of templates.

When you define templates, you specify the BRM flist fields that map to the invoice record fields. When the invoice data is processed, the fields are passed in an flist to the invoicing opcodes for processing.

The default INTEGRATE template defines Pipeline Manager invoice data. You can modify the INTEGRATE template or create new templates.

To create or modify templates in the pin_invoice_data_map file:

  1. Open the BRM_home/data/config/pin_invoice_data_map file.

  2. Change the INTEGRATE template or add a new template to the end of the file. Use the following syntax: 

    ID template_name
field_level   field_name
field_level   field_name
field_level   field_name
...

    where:

    • template_name is the name of the template.

    • field_level is the level of the field in the flist.

    • field_name is the associated BRM field.

    For example:

    ID INTEGRATE
0 PIN_FLD_CALLING_NUMBER
0 PIN_FLD_CALLED_NUMBER
. . . 
0 PIN_FLD_BAL_IMPACTS
1 PIN_FLD_RATE_TAG
1 PIN_FLD_AMOUNT

  3. Save and close the file.

The order of the fields in the template must correspond to the order of the fields in the invoice record. Any custom invoice data records that you process must follow these rules:

  • Fields must be separated by a pound symbol: #

  • Arrays and substructs must be enclosed in angle brackets: < >

  • Each balance impact element must end with a pipe symbol: |

    Note:

    The pipe is optional after the last element.

  • The first field in the record must be the name of the corresponding invoice data template and be preceded by the @ symbol.

    For example: @INTEGRATE

  • The template name in the record must match the template name in the load_pin_invoice_data_map file.

Loading the Invoice Data Map Templates

After defining invoice data map templates, load them into the BRM database.

Note:

When you run load_pin_invoice_data_map, it overwrites the existing invoice data templates. If you are updating a set of templates, you cannot load new templates only. You must load complete sets of invoice data templates each time you run load_pin_invoice_data_map.

Note:

To connect to the BRM database, load_pin_invoice_data_map needs a configuration file in the directory from which you run the utility.

If you defined a custom field for invoicing, you must add the full path name of the mapping file to the load_pin_invoice_data_map utility's pin.conf file.

To load the data map templates:

  1. Go to the directory that contains the utility's configuration file.

  2. Run the following command, which loads the data map template:

    load_pin_invoice_data_map -d -v pin_invoice_data_map

Enabling Event Caching

Pipeline Manager caches invoice data before sending it to BRM for processing. Therefore, you must enable event caching to include Pipeline Manager invoice data in your invoices.

To enable event caching:

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

  2. Set the event_cache entry to 1: 

    - fm_inv event_cache 1

  3. Save and close the file.

Adding Invoice Data to Pipeline Output

To add data from a pipeline to your invoices, configure the OUT_GenericStream module to add the data to the BRM billing record.

To output invoice data, add the following registry parameter to all OUT_GenericStream modules:

AddInvoiceData = TRUE

This parameter is read by the output grammar. When set to TRUE, the output module adds invoice data to each BRM billing record.

Using the pin_virtual_time Utility with Pipeline Manager

If you use pin_virtual_time to test charging and billing, you need to set the VirtualTime parameter for the DAT_BalanceBatch module to True to ensure that balances are calculated correctly.