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. It includes information about using Pricing Center to create rate plans and price models as well as information about the function modules used during rating.
Before you read this document, you should be familiar with these topics:
Pipeline rating. See "About Pipeline Rating".
Real-time rating. See "About Real-Time Rate Plans" in BRM Setting Up Pricing and Rating.
Configuring pipeline rating involves two sets of tasks:
Creating rate plans, price models, and other data using Pricing Center. See "Creating Pipeline Rate Plans and Price Models" in BRM Setting Up Pricing and Rating.
Configuring rating function modules. See "About Configuring Function Modules for Pipeline Rating".
Three groups of modules are involved in rating:
The pre-rating modules (FCT_ GlobalRating, FCT_CustomerRating, FCT_SegRateNoCust, and FCT_RSC_Map) gather information and prepare the event data record (EDR) for rating.
The FCT_MainRating module applies rate plans and price models 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.
Use filter sets to apply system products and system discounts to a select group of customers. For example, you can provide reduced international call rates for all customers with great credit. You define the criteria to qualify for a filter set and the list of available products and discounts by using Pricing Center.
When configured to use filter sets, the pipeline:
Analyzes each EDR to determine whether it meets the criteria for a filter set.
Adds any applicable system products and system discounts, along with their priorities, to the EDR's list of purchased products.
Uses the product and/or discount when rating the EDR.
Note:
The actual product or discount the pipeline uses to rate the EDR depends on how your system is configured. See "How Pipeline Manager Chooses a Rate Plan" in BRM Managing Customers.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 in Pricing Center.
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 and system discounts to the EDR's list of purchased products.
To configure BRM to use filters sets, perform the following tasks:
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".
Define your filter sets by using Pricing Center. See "Defining Your Filter Sets".
Configure the IRL_UsageType iRule to assign usage types to EDRs. See "Configuring the IRL_UsageType iRule for Filter Sets" in BRM Setting Up Pricing and Rating.
Configure FCT_Filter_Set to apply system products and discounts to specified market segments. See "FCT_Filter_Set".
Connect the FCT_DiscountAnalysis module to the FCT_Filter_Set module. Use the FCT_DiscountAnalysis module's Filter_SetModule registry entry. See "FCT_DiscountAnalysis".
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. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.When you finish loading the file, confirm that pipeline rating is enabled in Pricing Center. In the C:\Program Files\Portal Software\PricingCenter\lib\custom.properties file, make sure the following entry is set to True:
pricingcenter.pipeline.rating=True
For information on loading the system_filterset_edr_field_values.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide. For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
You define your filter sets by using Pricing Center. 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. See "Managing Filter Sets" in BRM Developer's Guide.To create a filter set, perform the following in Pricing Center:
Create your system products and system discounts and associate them with specific service and event types. For example:
Create a system product for /service/telco/gsm/telephony events that charges a flat rate of 5 cents per minute.
Create a system discount for /service/telco/gsm/sms events that provides a 20% discount for the first 10 minutes of usage.
Create your filter sets by mapping filter criteria to system products and system discounts. When creating filter sets, you specify:
The conditions required for an EDR to qualify for a system product or discount. That is, the list of required EDR fields and values for each filter set.
Applicable system products and discounts, 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.
For detailed information on how to create filter sets, see Pricing Center Help.
Use global rating to rate every EDR by using the same set of rate plans. 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 rate plans 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 rate plans. You can use this entry in a semaphore.
Use least cost rating to rate EDRs by using the product that produces the lowest charge to customers. In this configuration, the pipeline:
Rates EDRs by using all products and rate plans associated with an EDR and applies any discounts.
Finds the rate plan and discount that produces the lowest charge.
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 product. All charge packets are listed in order of priority, highest priority first.
The ISC_LeastCost iScript calculates the total charge for each product and discount and flags the rate plan that produces the lowest charge. When the lowest charge is generated by a promotional product, the module also calculates the total savings between the promotional product and the lowest priority (base) product.
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 rate plan and calculate the discount for each charge packet.
To set up least cost rating:
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".
Configure FCT_CustomerRating for least cost rating by using the LeastCostRating entry. See "FCT_CustomerRating".
Configure the ISC_LeastCost iScript to find the lowest charge for customers. See "ISC_LeastCost".
To specify which EDRs are flagged for least cost rating:
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};
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 product 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
Product priority greater than 4
segmentContains("1234") and priority()>4;2
Configure the FCT_IRules module to point to IRL_LeastCostPerEDR.irl by using the following registry entries:
Important:
If you configure a pipeline to use filter sets, make sure IRL_LeastCostPerEDR runs after FCT_Filter_Set.You can calculate how much money your customers save when an event is rated with a promotional product rather than a base product by using promotional savings. Promotional savings allows you to calculate the difference in charges between a promotional product and the base product, so you can advertise the savings to your customers.
When configured for promotional savings, the pipeline:
Rates EDRs by using the highest priority product and the lowest priority (base) product.
Calculates the difference between the charge for the promotional product and the charge for the base product.
Applies the savings amount to the EDR.
Note:
The pipeline applies the savings amount only when the promotional product 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) product.
The ISC_LeastCost iScript calculates the charges for the highest and lowest priority products 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:
Specify your promotional savings criteria. See "Specifying the Rules to Qualify for Promotional Savings".
Configure FCT_CustomerRating for promotional savings by using the PromotionalSaving entry. See "FCT_CustomerRating".
Configure ISC_LeastCost to calculate the promotional savings amount. See "ISC_LeastCost".
To specify which EDRs are flagged for a promotional savings calculation:
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};
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 product 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
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".
Overlay promotions allow you to quickly and easily replace your existing products and discounts with special products and discounts 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 product to your price list that offers the same services but costs10% less and has a higher priority than the original product.
You do not need to create new zone models for promotional products. Promotional products can use the same zone models as standard products. For example, you can create two promotional products, CALL_USA and CALL_INDIA. You can give CALL_USA priority 4 and CALL_INDIA priority 2, while your base product has priority 0. There is no need to create special zone models for the promotional products. If a customer buys the promotional products, BRM uses them to rate calls to the US and India. Calls to other countries will be rated using the base product.
You create overlay promotions by using Pricing Center to create new products associated with the same service and event types as other products, but with higher product priorities. For details on creating products, see Pricing Center Help.
The capability to use overlay promotions is built into a pipeline, which:
Recognizes and uses product priorities.
Allows you to associate multiple products 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.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 have the same priority, the product 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 rate plan of that record and populates the INTERN_FOUND_PP_INDEX field with the index of that rate plan. 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 rate plan of that record and populates the INTERN_FOUND_PP_INDEX field with the index of that rate plan. 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".
You use Pricing Center to create an overlay promotion in the same way you create any other product, except that you assign it a higher priority than the product it is supplanting. You then add the promotional product to an add-on plan or deal.
When you make the new overlay promotion available to your customers and they purchase the promotion, it takes priority over your other products.
You can create multiple overlay promotion products. For example, you could create an overlay product for calls to the US and another for calls to India.
The effective period of an account's products and discounts can start when the products and discounts are first used to rate a subscriber's usage.
For more information, see "About Effective Periods That Start on First Usage" in BRM Setting Up Pricing and Rating.
If products or discounts are configured to start on first usage, you set up pipeline rating to set their validity periods when first usage occurs.
Note:
Resources that are granted by products and discounts can also start on first usage. To set resource validity when first usage occurs, you configure the batch discounting pipeline. See "About settIng the Validity of Resources Impacted by Discounts". For information about resources that start on first usage, see "About Balance Impacts That Become Valid on First Usage" in BRM Setting Up Pricing and Rating.When configured to set validity on first usage, the pipeline:
Suspends EDRs that use products or discounts configured to start on first usage until the product or discount validity periods are set.
EDRs are not suspended when first-usage resource 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 resources for any other events before the balance validity period has been set in the database.
Sends the product or discount 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 and discounts are locked.
If the event is discounted and the discount balance impact consumes a resource balance that starts on first usage, the pipeline sends the resource information to a file in the output stream.
BRM processes the file and sets the resource validity periods in the database. If the validity period of all first-usage resources are configured to be synchronized, BRM also sets the validity period of those resources.
Rates the events when the EDRs are recycled.
If the pipeline transaction is rolled back or canceled, the validity period of any product or discount that was set in the transaction is unset.
BRM uses the Account Synchronization Data Manager (DM) to synchronize product and discount validity periods in the BRM database and pipeline memory.
The following modules are involved in setting the effective periods of products and discounts:
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 and discounts 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 product or discount's validity period is already set in the database.
NEW_FirstUsage: Indicates that the product or discount is configured to start on first usage and that its validity period has not yet been initialized.
INIT_FirstUsage: Indicates that the product or discount's validity period has been initialized but has not yet been stored in the database.
If the validity periods of all first-usage resources in the deal should be synchronized, DAT_AccountBatch retrieves a list of the balance groups that have first-usage validity and are associated with the products or discounts in the deal. For information about synchronizing first-usage validity of resources, see "About Synchronizing First-Usage Validity of Resources in Deals" in BRM Setting Up Pricing and Rating.
The FCT_ApplyBalance module. See "About settIng the Validity of Resources Impacted by Discounts".
The OUT_GenericStream module and related modules. See "Configuring Pipeline Output for First-Usage Products, Discounts, and Resources".
To set the validity for products and discounts that start on first usage, you must also perform these tasks:
Configure BRM recycling to recycle suspended EDRs. For more information, see "Setting Up Recycling for Events whose Product or Discount Validity Starts on First Usage".
Use Universal Event (UE) Loader to update the validity periods in the BRM database. See "About Updating Validity Period Information in the BRM Database".
Use the FCT_FirstUsageNotify module to suspend EDRs while BRM sets the validity periods of products and discounts 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 product and a discount that start on first usage for the first time, the EDR is suspended and recycled twice: once to set the product validity period and again to set the discount validity period. This is because the product may grant resources that can be impacted by the discount, so the product's purchase and cycle events need to be processed before the discount is evaluated.
The FCT_FirstUsageNotify module performs the following tasks:
Checks whether the products and discounts used to rate an EDR have validity periods that start on first usage.
If a product or discount 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.
Notifies the DAT_AccountBatch module that the validity period of the product or discount is being set.
Sends the product and discount validity information to a separate output stream.
Continues to flag for suspense and recycling subsequent EDRs that use the products or discounts 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, discount, or resource validity should not be set for EDRs that will be otherwise suspended.
In the batch rating pipeline, you configure two output streams: one for files containing products and discounts that start on first usage, and another for files containing resources that start on first usage.
To create the first-usage output streams, configure the following:
The OUT_GenericStream module. See "Configuring First-Usage Output Streams".
The DataDescription section of the registry. See "Specifying the First-Usage Format and Mapping Files in the DataDescription Registry".
Configure the OUT_GenericStream module to write the first-usage products, discounts, and resources to an output file.
The default output grammar description files are:
For products and discounts, FirstUsageNotify_OutGrammar.dsc.
For resources, FirstUsageResource_OutGrammar.dsc.
In the EXT_OutFileManager section of the registry, specify the temporary file specifications as follows:
For first-usage products and discounts:
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 resources:
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".
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 and AAA Responses".
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, discounts, and resources:
Load the first-usage validity Universal Event Mapper templates. See "Loading the First-Usage Validity Templates".
Configure the ConfigurableValidityHandler batch handler. See "Configuring the ConfigurableValidityHandler Batch Handler".
Configure Batch Controller. See "Configuring Batch Controller to Start the ConfigurableValidityHandler Batch Handler".
BRM provides two Universal Event (UE) Mapper event import templates that are used by UE Loader to process the first-usage product, discount, and resource files output by the OUT_GenericStream module:
FirstUsageProductsDiscounts.xml: This template defines the format of the first-usage product and discount files.
FirstUsageResources.xml: This template defines the format of the first-usage resource 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
For more information, see "pin_uei_deploy" in BRM Developer's Guide.
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, discounts, and resources 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.
Batch Controller polls the pipeline output directories and starts the ConfigurableValidityHandler batch handler when a data file is ready to be loaded.
Important:
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:
Open the Batch Controller Infranet.properties file in BRM_Home/apps/batch_controller.
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
|
Save and close the file.
Stop and restart Batch Controller.
For more information about configuring Batch Controller, see "Controlling Batch Operations" in BRM System Administrator's Guide.
To suspend and recycle EDRs while product and discount 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".
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. For more information, see "About Automatic Rerating of Out-Of-Order Events" in BRM Setting Up Pricing and Rating.
Customer rating assigns a rate plan 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 rate plan code. The FCT_MainRating module uses the rate plan code to rate the event.
To assign the rate plan, the FCT_CustomerRating module does the following:
If the service that generated the event includes a service-level rate plan extended rating attribute (ERA), that rate plan is used.
If you're using subscription services, and a subscription service and member service both own a service-level rate plan ERA, the member service's ERA has priority and is used for selecting the rate plan. For information about subscription services, see "Managing Customers' Subscription-Level Services" in BRM Managing Customers.
If there is no service-level rate plan ERA, but there is an account-level rate plan ERA, that rate plan is used.
If there is no rate plan ERA, the rate plan from the BRM price list associated with the last product found is used when there is more than one product available.
For more information, see "How Pipeline Manager Chooses a Rate Plan" in BRM Managing Customers.
To configure customer rating, see "FCT_CustomerRating".
When you configure the FCT_CustomerRating module, you can assign a default rate plan and default segment to use if no customer information for the A number is found.
Use the DefaultRateplan entry to specify the default rate plan name in case there is not enough information to assign a rate plan. 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".
The FCT_CustomerRating module can also choose a rate plan to perform multi-segment rating. In that case, the module reads the segment that applies to the data in the CUST_A data block and uses the rate plans defined for that segment in the IFW_SEGRATE_LNK database table. The module creates one charge packet for each rate plan. You create segments by using Pricing Center.
For information about multi-segment rating, see "About Multi-Segment Rating".
You define service-level agreement (SLA) codes in Pricing Center 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. See "Setting Up Usage Scenario Mapping" in BRM Setting Up Pricing and Rating.
Use multi-segment rating to collect business data about your rate plans. With multi-segment rating, you use multiple rate plans on the same EDR and compare the rating results.
A segment is a set of rate plans that you define in Pricing Center. When the EDR is rated, a charge packet is created for each rate plan in the segment, and each rate plan is rated in parallel. This provides information on the results of rating the same data when rating is performed by different rate plans.
You can use two methods of assigning segments to EDRs:
Use the FCT_CustomerRating module to assign segments by using the segment defined in the account. Use the business intelligence segment ERA to assign segments to customer accounts.
Use the FCT_SegRateNoCust module to assign segments when you don't have accounts for the EDRs. For example, you might want to use a test system that doesn't have access to account data. In that case, you configure FCT_SegRateNoCust to assign segments based on the source network ID.
In either case, when the segment has been found, the modules create an associate charge breakdown record and a charge packet for each rate plan. The subsequent modules, such as the FCT_MainRating module, use those charge packets to add rating data.
To set up and use multi-segment rating, do the following:
Create segments in Pricing Center. A segment consists of the following:
The rate plan to use for rating.
The dates that specify when the segment is valid.
If you use account data to assign rate plans for segment rating, assign the business intelligence segment ERA to customer accounts.
If you use the business intelligence segment ERA, configure FCT_CustomerRating to find the rate plans. See "FCT_CustomerRating".
If you use source networks to find segments, configure FCT_SegRateNoCust. See "FCT_SegRateNoCust".
Use the FCT_SegRateNoCust module Segments registry entry to specify the segment to use for each source network. Each rule defines the connection between the source network and the segment. For example:
26201 = SegmentD1 26202 = SegmentD2
Important:
You cannot change these mappings during runtime.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. 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 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.
To set up RSC mapping, do the following:
Use Pricing Center to create RSC maps and RSC map groups.
Use Pricing Center to create SLA codes and link them to RSC map groups.
Configure FCT_RSC_Map. See "FCT_RSC_Map".
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 rate plan 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.
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 rate plan. The module uses the rate plan to rate the EDR. To rate the EDR, the module uses information about dates, times, and the price model 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 rate plan configuration that apply to an EDR to find the correct price model to use for rating. If a single event is rated by using different time periods, such as peak and off-peak, more than one price model can be used. If an event is mapped to a price model selector, the model selector's rules are evaluated to choose a price model.
If the rate plan configuration includes an alternative price model, the module creates a new charge packet. The EDR is rated again by using the alternative price model. The charge packet is flagged with the A (Alternative) price model 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 resource that is used. (The resources are defined in the price model.)
To configure main rating, see "FCT_MainRating".
You use rate adjustments to provide discounts based on date, time, service, and other event attributes. See "About Pipeline Rate Adjustments" in BRM Setting Up Pricing and Rating.
To set up rate adjustment, do the following:
Create rules that specify which EDRs to adjust and how to adjust them. You have two options:
Create rate adjustment rules in Pricing Center. In this case, the rate adjustment data is stored in the Pipeline Manager database. See "About Pipeline Rate Adjustments" in BRM Setting Up Pricing and Rating.
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".
Configure FCT_RateAdjust. See "FCT_RateAdjust".
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.
Important:
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 rate plan to adjust. |
|
3 |
Rate plan version |
Specifies the rate plan 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:
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 rule that is valid on weekends between 13:00 and 14:00, you have to set the following:
|
|
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. |
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 rate plan, and resources.
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 resource. If there are different G/L IDs for the same resource, a balance impact packet is created for each G/L ID.
To configure FCT_BillingRecord, see "FCT_BillingRecord".
Important:
Don't use FCT_BillingRecord in a CIBER roaming revenue assurance environment. For more information, see "Billing Consolidation with CIBER Roaming and Revenue Assurance".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. In contrast, FCT_BillingRecord does not use record type 984, which is used for multi-segment rating.
The charge packet must use the following:
The standard price model type: PRICEMODEL_TYPE = S
A retail rate plan: 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. See "Defining Currency Exchange Rates" in BRM Setting Up Pricing 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 resource 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. See "About Balance Monitoring and Pipeline Rating" in BRM Managing Accounts Receivable.
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. See "About Convergent BRM Systems" in BRM System Administrator's Guide.
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".
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:
Resource type
Price model type
Currency type
Note:
This iScript accesses only EDR fields. It doesn't access the database.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. See "Adding Invoice Data to Pipeline Output" in BRM Designing and Generating Invoices.