29 Configuring Comprehensive Rerating

This chapter describes how to configure your Oracle Communications Billing and Revenue Management (BRM) system for comprehensive rerating using pin_rerate.

Note:

This documentation does not apply to rerating only pipeline-batch-rated events by using a batch rerating pipeline.

For an overview of comprehensive rerating, see "About Comprehensive Rerating Using pin_rerate".

Before reading this chapter, you should be familiar with the Pipeline Manager architecture. See BRM Configuring Pipeline Rating and Discounting.

About Configuring Comprehensive Rerating

How you configure rerating depends on whether you rerate real-time-rated and pipeline-batch-rated events concurrently or, if you do not use Pipeline Manager for batch rating, rerate only real-time-rated events. See one of the following sections:

You perform the following configurations for both concurrent rerating and real-time-event only rerating:

You can also configure BRM to automatically create rerate jobs when the following events occur:

Configuring Concurrent Rerating of Pipeline-Rated and Real-Time-Rated Events

Important:

Before you can configure concurrent rerating, you must have installed and configured Pipeline Manager and the Account Synchronization Data Manager (DM).

To configure concurrent rerating of both pipeline-rated and real-time-rated events, perform these tasks:

Configuring a Real-Time Rerating Pipeline

A real-time rerating pipeline is configured similarly to a batch rerating pipeline, but with fewer preprocessing and post-rating modules. This is because most of the enrichment data is provided in the input flist received from the CM.

You typically create a separate instance of Pipeline Manager for real-time rerating. The default registry file is BRM_Home/conf/wirelessRealtime.reg.

To configure a real-time rerating pipeline, perform the following tasks:

Figure 29-1 shows the real-time rerating pipeline architecture:

Figure 29-1 Real-Time Rerating Pipeline Architecture

Description of Figure 29-1 follows
Description of ''Figure 29-1 Real-Time Rerating Pipeline Architecture''

Configuring Multiple Real-Time Rerating Pipelines

To improve performance or scalability, you configure multiple instances of real-time rerating pipelines. For example, you can increase performance by configuring multiple pipelines to process rerate requests in parallel or by configuring multiple real-time rerating pipelines to process different rerate requests: for example, by configuring one pipeline that rerates only GPRS events and another that rerates only GSM events. See "Configuring Multiple Instances of a Pipeline" in BRM System Administrator's Guide.

Configuring the Real-Time Rerating Data Pool

Configure the following data modules:

  • DAT_Zone

  • Rateplan

  • DAT_Calendar

  • DAT_TimeModel

  • DAT_PriceModel

  • Dayrate

  • DAT_Currency

  • DAT_USC_Map

See "Configuring the Data Pool" in BRM System Administrator's Guide

Configuring the Modules in the Real-Time Rerating Pipeline

Configure the following modules in the real-time rerating pipelines:

  • Configure the INP_Realtime input module. Specify the flist-to-EDR mapping file used for rerating in the OpcodeMapping registry entry. For example:

    OpcodeMapping = ./formatDesc/Formats/Realtime/rate_event.xml

  • Configure the NET_EM module:

  • Configure the output module to add any customizations to the output flist.

  • Configure these function modules:

    • FCT_ServiceCodeMap

    • FCT_CustomerRating

    • FCT_PreRating

    • FCT_IRules

    • FCT_USC_Map

    • FCT_RSC_Map

    • FCT_MainRating

    • FCT_Dayrate

    • FCT_RateAdjust

    • FCT_Rounding

    • FCT_DiscountAnalysis

    • FCT_Discount

Configuring NET_EM to Route Rerate Requests Based on the Event Field Value

To configure NET_EM to route rerate requests to multiple real-time rerating pipelines based on the type of event, you set the FieldName and FieldValue NET_EM module registry entries.

Important:

If you use event routing based on the event field value, ensure that the input events contain the expected field name and field values specified in the NET_EM module registry. Otherwise, NET_EM will not be able to route the events.

By using the ”.” notation, you can specify a field at any level in the input event flist to be used to route the event. For example, this substruct and field:

PIN_FLD_EVENT
     PIN_FLD_POID

is represented like this:

PIN_FLD_EVENT.PIN_FLD_POID

In the NET_EM registry below, if PIN_FLD_EVENT.PIN_FLD_POID is a GSM event, the rerate request is routed to any one of the two instances of the GSM rerating pipeline (RealtimeReratingGSM). If the event is a GPRS event, the rerate request is routed to any one of the two instances of the GPRS rerating pipeline (RealtimeReratingGPRS).

DataPool 
{
     RealtimePipeline
     {
          ModuleName = NET_EM
          Module
          {
               ThreadPool 
               { 
                   Port = 14579
                   Threads = 4
               }

               ReratingOpcode
               {
                   OpcodeName = PCM_OP_RATE_PIPELINE_EVENT
                   FieldName = PIN_FLD_EVENT.PIN_FLD_POID
                   GSMEvent
                   {
                     FieldValue = /event/delayed/session/telco/gsm
                     PipelineName = RealtimeReratingGSM
                     NumberOfRTPipelines = 2
                   }
                   GPRSEvent
                   {
                     FieldValue = /event/delayed/session/gprs
                     PipelineName = RealtimeReratingGPRS
                     NumberOfRTPipelines = 2
                   }
               }
               
          }
     }
}

Adding Real-Time Rerating Pipeline Data to the IFW_PIPELINE Table

Pipeline Manager stores information about pipelines in the IFW_PIPELINE table. The pipelines that are preconfigured in the Pipelines section of the default registry file (Pipeline_home/conf/wirelessRealtime.reg) are inserted into the IFW_PIPELINE table during Pipeline Manager installation.

Important:

  • If you are not using the default registry file, and you have configured new real-time rerating pipelines, you must manually insert the pipelines into the IFW_PIPELINE table by using SQL commands. Otherwise, you will receive an error at system startup.

  • If you are using the default registry file and have changed the default pipeline names or you have configured additional pipelines, you must manually insert the new pipelines into the IFW_PIPELINE table.

The following example shows SQL commands to insert RealtimeReratingGSM and RealtimeReratingGPRS pipelines into the IFW_PIPELINE table:

% sqlplus pin/password@databaseAlias

SQL>INSERT INTO IFW_PIPELINE ( PIPELINE, NAME, EDRC_DESC ) VALUES ( 'RealtimeReratingGSM', 'GSM Realtime Rerating Pipeline', 'ALL_RATE'); 

SQL>INSERT INTO IFW_PIPELINE ( PIPELINE, NAME, EDRC_DESC ) VALUES ( 'RealtimeReratingGPRS', 'GPRS Realtime Rerating Pipeline', 'ALL_RATE'); 

SQL>commit;

Configuring the Batch Rating Pipeline and pin_rerate to Synchronize Processing

To enable pin_rerate and the batch rating pipeline to synchronize processes, perform the following tasks:

Configuring Rerating Business Events and Event Notification

The pin_rerate utility and the batch rating pipeline synchronize processing by passing business events by way of the Account Synchronization DM. To generate business events, pin_rerate uses event notification.

The business events and notification events used for rerating are defined in configuration files provided with the Account Synchronization DM:

  • The notification events used for rerating are specified by the following entries in the Account Synchronization DM notification list (BRM_Home/sys/data/config/pin_notify_ifw_sync):

    1301    0    /event/notification/rerating/start
    1301    0    /event/notification/rerating/end
    1301    0    /event/notification/rerating/PrepareToRerate
    1301    0    /event/notification/rerating/ReratingCompleted
    
  • The business events used for rerating are specified in the Account Synchronization DM EAI payload configuration file (BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml).

You configure these files when you install and configure the Account Synchronization DM. See BRM Synchronization Queue Manager.

Configuring Pipeline Manager to Handle Business Events from pin_rerate

To enable pin_rerate and Pipeline Manager to send and receive business events through the Account Synchronization DM, perform these tasks:

Creating the Acknowledgment Queue

The Account Synchronization DM uses database queues to send business events to Pipeline Manager. A default database queue is created for this purpose when you install the Account Synchronization DM.

You must create an additional database queue for Pipeline Manager to post acknowledgment events that are dequeued and processed by pin_rerate.

Note:

Only one business event queue and one acknowledgment queue is required for each instance of Pipeline Manager in your system. You do not need to create additional acknowledgment queues if one has already been created.

To create an acknowledgment queue, use the pin_ifw_sync_oracle.pl utility. For example:

pin_ifw_sync_oracle.pl create -q ACK_QUEUE -t ack_queue_t -l user/password@database

Configuring Access to Queues in a Multischema System

You can run BRM and Pipeline Manager in a multischema environment. For example, you might have a schema for BRM that uses the PIN logon, a schema for Account Synchronization queue that uses the PINQ logon, and a schema for the instance of Pipeline Manager that uses the INTEGRATE logon.

In such cases, you must create a global synonym for the Account Synchronization acknowledgment queue. This enables the user of the BRM schema to access the acknowledgment queue in the Account Synchronization schema.

  1. Using SQL*Plus, log in to your database as the SYSTEM user and create a global user synonym:

    sqlplus system/manager@DatabaseAlias
    
    CREATE PUBLIC SYNONYM ACCT_SYNC for PINQ.ACCT_SYNC 
    

    where PINQ is the login for the schema that includes the Account Synchronization stored procedures and acknowledgment queue.

    Note:

    The rerating stored procedures run in the PIN schema (the BRM schema).
  2. Add the global synonym to the pin_rerate configuration file (BRM_Home/app/pin_rerate/pin.conf):

    - pin_rerate ack_queue PINQ.ACK_QUEUE
    

Configuring the DAT_Listener Module

Pipeline Manager responds to business events sent by pin_rerate by posting acknowledgment events. You must configure the DAT_Listener module to post acknowledgment events to the Account Synchronization acknowledgment queue. Set the AckQueueName entry to specify the name of the acknowledgment queue.

Sample DAT_Listener registry:

Listener
{
     ModuleName = DAT_Listener
     Module
     {
          InfranetConnection = ifw.DataPool.LoginQueue
          QueueName = QUEPIN117
          AckQueueName = ACK_QUEUE
          MQAckServerName = ACK_QUEUE_SERVER
          LogEvents = TRUE
     }
}

Configuring pin_rerate to Receive Acknowledgment Events from Pipeline Manager

To enable pin_rerate to receive acknowledgment events from Pipeline Manager, perform the following tasks:

Loading the Stored Procedure for Rerating

The pin_rerate utility uses stored procedures to dequeue acknowledgment events from the database queue and to purge rerate jobs (for more information on purging rerate jobs, see "Parameter for Purging Rerate Jobs").

Note:

Before loading the pin_rerate stored procedures, you must have Account Synchronization installed and configured.

To load the stored procedure:

Oracle:

On Oracle systems, you manually load the rerating stored procedures job_rerate_procedures_pkb.plb and job_rerate_procedures_oracle.plb into your BRM database:

  1. Connect to your database using SQL*Plus:

    sqlplus user/password@database
    

    where user and password are your user name and password, and database is the service name for the BRM database.

  2. At the SQL*Plus prompt, enter the following commands:

    @BRM_Home/sys/dm_oracle/data/job_rerate_procedures_pkg_oracle.plb
    @BRM_Home/sys/dm_oracle/data/job_rerate_procedures_oracle.plb
    

    where BRM_Home is the directory in which BRM is installed.

Configuring pin_rerate to Dequeue Events from the Acknowledgment Queue

Configure the pin_rerate utility to dequeue events from the acknowledgment queue that you created in "Creating the Acknowledgment Queue".

Add the following entry in the pin_rerate configuration file (BRM_Home/app/pin_rerate/pin.conf):

- pin_rerate ack_queue ACK_QUEUE

where ACK_QUEUE is the name of the acknowledgment queue.

Configuring Standard Recycling

BRM rerating uses standard recycling for two purposes:

  • To load EDRs suspended during rerating into the BRM database.

  • To retrieve suspended EDRs from the BRM database and recycle them when rerating is complete.

For configuration instructions, see "Configuring Standard Recycling" in BRM Configuring Pipeline Rating and Discounting.

Configuring Rerating When You Do Not Use a Batch Rating Pipeline

If you do not use Pipeline Manager for batch rating, perform the following tasks to configure pin_rerate to rerate only real-time-rated events:

Specifying Whether the Batch Rating Pipeline Is Enabled

When the batch pipeline is enabled, pin_rerate generates notification events to synchronize processing with the batch pipeline by way of the Account Synchronization DM. When the batch pipeline is disabled, pin_rerate does not generate notification events because synchronization is not needed.

pin_rerate checks a field in the rerate instance of the /config/business_params object, to determine if the batch rating pipeline is enabled or disabled:

  • To rerate both real-time-rated and pipeline-rated events concurrently, the batch rating pipeline entry must be set to enabled.

  • To rerate only real-time-rated events, the batch rating pipeline entry must be set to disabled.

The default is enabled.

You modify the /config/business_params object by using the pin_bus_params utility.

To specify whether the batch pipeline is enabled or disabled:

  1. Use this command to create an editable XML file from the rerate instance of the /config/business_params object:

    pin_bus_params -r BusParamsRerate bus_params_rerate.xml 
    

    This command creates the XML file named bus_params_rerate.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

  2. Search the XML file for following line:

    <BatchRatingPipeline>enabled</BatchRatingPipeline>
    
  3. Set the entry as needed:

    • enabled: To rerate both real-time-rated and pipeline-rated events concurrently.

    • disabled: To rerate only real-time-rated events when you do not use Pipeline Manager for batch rating.

      Caution:

      BRM uses the XML in this file to overwrite the existing rerate instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM billing configuration.
  4. Save the file and change the file name from bus_params_rerate.xml.out to bus_params_rerate.xml.

  5. Use the following command to load the change into the /config/business_params object:

    pin_bus_params bus_params_rerate.xml 
    

    You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility.

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

  7. Stop and restart the Connection Manager (CM).

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

Setting the Rerating Event Cache Size (Fetch Size)

By default, BRM rerating caches 10,000 events in system memory for processing. Depending on your system memory, you can set the event_fetch_size in the Connection Manager's configuration file to specify the number of events retrieved from the database and cached in the system memory for processing.

To set the event cache size:

  1. Open the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf) using a text editor.

  2. Uncomment the - fm_subscription event_fetch_size entry.

  3. Edit the event_fetch_size value. The default is 10000.

    - fm_subscription event_fetch_size 10000
    
  4. Save the file.

  5. Stop and restart the CM.

Configuring the Number of Accounts Per Job and Number of Jobs per Transaction

By default, BRM assigns 10 accounts to each rerate job and creates 2 rerate jobs per transaction. For example, if the total number of accounts to rerate is 10,000, BRM creates 1000 rerate jobs. It creates the rerate jobs in 500 separate transactions: 2 jobs in each transaction.

To change the default number of accounts per job and the number of rerate jobs created per transaction, perform the following tasks:

  1. Open the pin_rerate configuration file (BRM_Home/apps/pin_rerate/pin.conf).

  2. Set the number of accounts assigned to each rerate job by adding the following line:

    - pin_rerate per_job accounts_per_job
    

    where accounts_per_job is the number of accounts to assign to each job.

  3. Set the number of jobs created per transaction by adding the following line:

    - pin_rerate per_transaction jobs_per_transaction
    

    where jobs_per_transaction is the number of jobs to create in each transaction.

  4. Save and close the file.

    Caution:

    Setting the pin_rerate per_job entry to a small number, for example 1, will result in many rerate jobs being created. Too many rerate jobs can affect your system's performance due to the rerate steps performed for each rerate job. Processing multiple accounts in one rerate job reduces the total number of rerate steps performed compared to processing those same accounts in multiple rerate jobs.

Configuring Rerating to Reset First-Usage Validity Periods

Perform this task if your price plan includes products, discounts, or balance impacts that become valid on first usage (when customers use the products and discounts or consume the resource balance for the first time).

For information about first-usage validity, see "About Effective Periods That Start on First Usage" and "About Balance Impacts That Become Valid on First Usage".

When rerated events are associated with products, discounts, or resource balances that start on first usage, rerating resets their validity periods, if necessary. For example, if the first event rated, which initiated a product's validity period, was not actually the first event to use the product's service, rerating corrects the order of the events and resets the validity period based on the actual first-usage event.

To configure rerating for first-usage validity, perform the tasks in the following sections:

Configuring the Real-Time Rerating Pipeline to Set Product Validity Periods

If your products are configured to start when they are first used, configure the ISC_FirstProductRealtime iScript in the real-time rerating pipeline.

When products start on first usage, the real-time rerating pipeline adds the account's first-usage product and discount information to the EDR. ISC_FirstProductRealtime sets the validity period in the BRM database for products that were used to rate the event and that start on first usage. This triggers any purchase and cycle fees.

Configuring Event Notification for Rerating Cycle Events Triggered by First Usage

To ensure that BRM can rerate cycle events that are triggered because of first usage, you must add cycle-event notification events to your event notification list (the default notification list is BRM_Home/sys/data/config/pin_notify). BRM provides a list of default cycle-event notification events in the pin_notify_rerate file. Use this file to update your pin_notify file.

To configure event notification for rerating cycle events triggered by first usage:

  1. Open the pin_notify and pin_notify_rerate files in BRM_Home/sys/data/config.

  2. Copy the entries in the pin_notify_rerate file to the end of the pin_notify file.

  3. Save and close the pin_notify file and close the pin_notify_rerate file.

  4. Load the contents of the pin_notify file into the /config/notify object in the BRM database by running the load_pin_notify utility.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Configuring Rerating for Accounts Associated With Subscription Service Transfer

When a subscription service is transferred from one subscriber account to another, rerating the original account can affect the subscription service balances transferred to the new account. However, by default, the rerating process only selects accounts for rerating based on your specified search criteria. This means that, when an account selected for rerating is associated with a subscription service transfer, the other accounts to which the subscription service was transferred are not selected for rerating.

To rerate all accounts associated with a subscription service transfer, you configure the LineManagement business configuration parameter. When this parameter is enabled, the rerating process searches for any subscription service transfers for the account that is rerated, and adds the accounts to which the subscription service was transferred during the rerating time specified to the rerate request.

For example:

  1. Subscription service X is originally owned by Account A and transferred to Account B on June 15.

  2. On June 20, the service is transferred again from Account B to Account C.

  3. On July 10, Account A is selected for rerating and the rerating time specified is June 1. Rerating also selects Accounts B and C because the subscription service transfer to Account B and C occurred after June 1. Accounts A, B, and C are grouped together to form a single rerate request.

  4. Account A is rerated from June 1 to July 10, Account B is rerated from June 15 to July 10, and Account C is rerated from June 20 to July 10. Rerating selects the events for accounts A, B, and C, and rerates the events in chronological order, resulting in correct subscription service balance updates.

    Note:

    If rerating fails for any one of the accounts in the rerate request, rerating fails for all the accounts in the rerate request. For more information, see "How Failed Rerate Jobs Are Processed".

During rerating, each account is locked only for as long as it takes to rerate its events. However, in case of a subscription service transfer, related accounts are locked for the duration of rerating events associated with all of those accounts. In the example above, accounts A, B, and C remain locked until rerating of all three accounts is complete.

By default, the LineManagement parameter is disabled and cached at CM startup. To change the default value, you modify the rerate instance of the /config/business_params object by using the pin_bus_params utility. For information on this utility, see "pin_bus_params" in BRM Developer's Guide.

To enable rerating of accounts associated with a subscription service transfer:

  1. Run this command to create an editable XML file from the rerate instance of the /config/business_params object:

    pin_bus_params -r BusParamsRerate bus_params_rerate.xml  
    

    This command creates the XML file named bus_params_rerate.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

  2. Search the XML file for following line:

    <LineManagement>0</LineManagement> 
    
  3. Change 0 to 1.

    Caution!:

    BRM uses the XML in this file to overwrite the existing rerate instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRM's billing configuration.
  4. Save the file and change the file name from bus_params_rerate.xml.out to bus_params_rerate.xml.

  5. Go to the BRM_Home/sys/data/config directory.

  6. Run the command:

    pin_bus_params PathToWorkingDirectory/bus_params_rerate.xml 
    

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

    Note:

    To run this command from a different directory, see the description for pin_bus_params in BRM Developer's Guide.
  7. Read the object with the testnap utility or the Object Browser to verify that all fields are correct.

    See "Using testnap" in BRM Developer's Guide for general instructions on using testnap.

    See "Reading objects by using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

  8. Stop and restart the Connection Manager (CM). For more information, see "Starting and stopping the BRM system" in BRM System Administrator's Guide.

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

About Automatic Rerating of Backdated Events

Note:

Automatic rerating does not mean that rerating occurs immediately when an event is backdated. Automatic rerating means that rerate jobs (/job/rerate and /job_rerate/rerate objects) are automatically created.

When backdated events occur, BRM uses event notification to automatically create rerate jobs to rerate the backdated events. The accounts in the rerate jobs are rerated the next time you run "pin_rerate" to process rerate jobs; you do not need to specify the accounts and events in the pin_rerate command line. For more information about pin_rerate, see "Using the pin_rerate Utility".

BRM supports automatic rerating of backdated events in the following cases:

  • When purchase or cancellation of a product, discount, or deal is backdated.

  • When adjustment to a non-currency resource is backdated.

  • When an extended rating attribute (ERA) modification is backdated.

Table 29-1 shows the entries in the CM configuration file used to create rerate jobs for backdated events:

Table 29-1 Configuration File Entries for Rerate Jobs

Entry Description

backdate_trigger_auto_rerate

Specifies whether automatic rerating is enabled.

backdate_window

Specifies the minimum time difference needed between the current time and the backdated event time for triggering automatic rerating.

num_billing_cycles

Specifies the maximum number of billing cycles allowed between the current time and the backdated event time of a backdated operation.


Important:

All of these conditions must be met to trigger automatic rerating. Otherwise, the backdated event is not rerated.

By default, BRM creates rerate jobs for backdated events when the following conditions are met:

  • Automatic rerating is enabled.

  • The backdated event time is at least one hour earlier than the current time.

  • The backdated event date is not older than one billing cycle.

You can change the default backdated time and date thresholds in the CM configuration file. See "Configuring Automatic Rerating of Backdated Events".

You can backdate beyond the number of billing cycles specified in the num_billing_cycles entry without requesting to automatically rerate. For more information, see "Backdating beyond Configured Billing Cycles without Automatic Rerating Request".

For more information about using pin_rerate, see "pin_rerate".

About Backdated Deal, Product, and Discount Purchase

Automatic rerating of backdated deal, product, and discount purchases is triggered when the difference between the current time and the backdated event purchase, cycle, or the usage start time is greater than the time specified by the backdate_window parameter.

BRM then validates that the backdated purchase occurred within the number of billing cycles specified by the num_billing_cycles parameter. If the validation is successful, the account is automatically rerated the next time you run pin_rerate.

For example, a subscriber's billing day is on the first day of the month. The subscriber purchases a product on July 19 at 5:00 a.m. The CSR backdates the purchase start date to July 15. If the backdate_window is set to 1 hour and num_billing_cycles is set to 1 cycle, BRM validates that the purchase start time is on or before 4:00 a.m., July 19, and that the purchase start date is not earlier than June 1 (one billing cycle). Because both conditions are met and automatic rerating is enabled, when pin_rerate is run with -rerate parameter on July 20, BRM automatically rerates all the account's events that occurred after midnight of July 14 to July 20.

About Backdated Deal, Product, and Discount Cancellation

Automatic rerating of backdated deal, product, and discount cancellation is triggered when the difference between the current time and the purchase, cycle, or the usage end time is greater than the time specified by the backdate_window parameter.

BRM then validates that the backdated cancel occurred within the number of billing cycles specified by the num_billing_cycles parameter. If the validation is successful, the account is automatically rerated the next time you run pin_rerate.

The following example demonstrates how fees are prorated and charges are reversed when a backdate product cancellation occurs.

In this example, the backdate parameters are as follows:

  • backdate_window is 2 hours.

  • num_billing_cycles is 2 cycles.

The subscriber's product includes the following:

  • IP product purchase fee: $10

  • IP product monthly cycle forward fee: $20 (with proration enabled)

  • IP product cancellation fee: $50

  • IP usage fee: $1 per minute

  • Email product monthly cycle forward fee: $8

  1. On January 1, the subscriber purchases the product.

    Account balance = $10 IP product purchase fee + $20 IP monthly cycle forward fee + $8 email cycle forward fee = $38

  2. On January 20, the subscriber generates a usage of $10 for the IP service.

    Account balance = $38 + $10 usage = $48

  3. On February 1, when billing is run:

    Account balance = $48 + $20 IP monthly cycle forward fee (for February) + $8 email monthly cycle forward fee (for February) = $76

  4. On February 10 at 5:00 p.m., the subscriber cancels the IP product. The CSR backdates the product cancellation to January 10. BRM automatically creates a rerate job and the backdate cancel event is rerated by running pin_rerate. After backdate cancellation of the IP Product:

    • A $50 IP product cancellation fee is applied.

    • The IP product monthly cycle forward fee for January is prorated and charged for 10 days only.

    • The $10 IP service usage fee is reversed.

    • The IP product monthly cycle forward fee for February is reversed.

    Account balance = $10 IP purchase fee + $20 IP monthly cycle forward fee (for January) - $14.19 prorated IP monthly cycle forward fee refund + $8 email monthly cycle forward fee (for January) + $50 IP product cancellation fee + $8 email cycle forward fee (for February) = $81.81

  5. On March 1, when billing is run:

    Account balance = $81.81 + $8 email cycle forward fee (for March) = $89.81

BRM validates that the purchase end time is on or before 3:00 p.m., February 10, and that the purchase end date is not earlier than December 1 (two billing cycles). When both conditions are met and automatic rerating is enabled, when "pin_rerate" is run, BRM automatically rerates all the account's events that occurred after midnight January 10 to February 10.

About Backdated Adjustment of Non-Currency Resources

When you backdate an adjustment of a non-currency resource and automatic rerating is enabled, BRM automatically rerates all the associated events the next time you run pin_rerate with the -rerate parameter.

Note:

  • The adjustment event is rerated only if the adjustment is for a non-currency resource.

  • The adjustment must be backdated so that it can be used to rerate the events.

In the following example, the billing date is the first day of the month:

On February 15, the free minutes resource is adjusted from 100 to 500 and the adjustment is backdated to be effective January 15. The backdate_window is 24 hours and num_billing_cycles is 1 cycle. When pin_rerate is run on February 20 with the -rerate parameter, BRM automatically rerates all the relevant events from January 15 to February 20 and applies the balance changes to the current billing cycle. It creates adjustment events for the events that occurred from January 15 to February 1 and shadow events for the events that occurred from February 1 to February 20. Billing events that previously occurred on February 1, such as billing-time discounts, rollovers, and folds, are recalculated based on the new adjustment and are reapplied.

About Backdated ERA Modifications

BRM automatically rerates backdated ERA modifications when the validity start time or end time is backdated and automatic rerating is enabled.

For example, a subscriber changes their service-level agreement from Silver to Gold on July 12. The CSR backdates the change to July 1 to let the subscriber apply the Gold-level benefits to all usage for July. The next time you run pin_rerate, BRM rerates all the relevant events for the account that occurred between July 1 and the current time.

Configuring Automatic Rerating of Backdated Events

To configure automatic rerating of backdated events, you perform the following tasks:

Setting Thresholds That Trigger Automatic Rerating

BRM automatically rerates certain backdated events based on the default CM configuration settings. See "About Automatic Rerating of Backdated Events".

To change the default settings:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

  2. To turn automatic rerating on or off, set the backdate_trigger_auto_rerate entry: 1 = enabled; 0 = disabled.

    - fm_subs backdate_trigger_auto_rerate 1
    
  3. To specify the minimum time difference necessary to trigger automatic rerating, set the backdate_window entry. This is the amount of time in seconds between the current time and the backdated time. The default is 3600 seconds.

    - fm_subs backdate_window 3600
    
  4. To specify the maximum number of billing cycles allowed between the current time and the backdated event date for triggering automatic rerating, Set the num_billing_cycles entry. The default is 1 billing cycle.

    - fm_subs num_billing_cycles 1
    
  5. Save and close the file.

  6. Stop and restart the CM.

Configuring Event Notification for Rerating Backdated Events

When a backdated event occurs, BRM rerating uses event notification to trigger automatic rerating of the event.

Although any subclass of the /event class can be used to trigger event notification, BRM rerating generates the nonpersistent /event/notification/auto_rerate event specifically to use for event notification.

By default, when this event occurs, BRM creates a rerate job.

Before you can use BRM rerating, you must configure the event notification feature as follows:

  1. If your system has multiple configuration files for event notification, merge them.

  2. Ensure that the merged file includes the following information from the BRM_Home/sys/data/config/pin_notify file:

    # Rerating related event notification
    3787    0    /event/notification/auto_rerate
    
  3. (Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list.

  4. (Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger.

  5. Load your final event notification list into the BRM database.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Backdating beyond Configured Billing Cycles without Automatic Rerating Request

You can backdate an event beyond the configured number of billing cycles without requesting to automatically rerate such an event.

To do so:

  1. Ensure that automatic rerating is enabled for backdated events. If necessary, enable it by setting the backdate_trigger_auto_rerate entry in CM configuration file to 1. For more information on backdate_trigger_auto_rerate, see the description of pricing and rating pin.conf entries in BRM System Administrator's Guide.

  2. Enable the AllowBackdateNoRerate business parameter in the /config/business_params object by using the pin_bus_params utility. For more information, see pin_bus_params in System Administrator's Guide.

  3. After you enable the AllowBackdateNoRerate business parameter, you must manually rerate any events backdated beyond the number of billing cycles specified in the num_billing_cycles entry.

    For information on manually rerating events, see "Using the pin_rerate Utility".

    For information on num_billing_cycles, see the description of Billing pin.conf entries in BRM System Administrator's Guide.

Enabling the AllowBackdateNoRerate Business Parameter

To set the AllowBackdateNoRerate business parameter to enabled:

  1. Go to BRM_Home/sys/data/config directory.

  2. Create an editable XML file of the subscription instance from the /config/business_params object by using the following command:

    pin_bus_params -r -c "Subscription" bus_params_subscription.xml

    BRM places the XML file named bus_params_subscription.xml.out in your working directory. To place this file in a different directory, specify the full path as part of the file name.

  3. Locate the AllowBackdateNoRerate entry in the bus_params_subscription.xml.out file.

  4. Set the value of AllowBackdateNoRerate to enabled, if necessary.

    <AllowBackdateNoRerate>enabled</AllowBackdateNoRerate>

    Caution:

    BRM uses the XML in this file to overwrite the existing subscription instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM subscription configuration.
  5. Save this updated file as bus_params_subscription.xml.

  6. Load the modified XML file containing the business parameters for billing into the appropriate /config/business_params object in the BRM database.

    pin_bus_params bus_params_subscription.xml

    You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see the description of pin_bus_params in BRM System Administrator's Guide.

  7. Read the object with the testnap utility or Object Browser to verify that all fields are correct. BRM stores one of the following values for AllowBackdateNoRerate:

    • 0 to indicate disabled.

    • 1 to indicate enabled.

    For more information on reading objects by using the Object Browser, see BRM Managing Customers. For instructions on using the testnap utility, see BRM Developer's Guide.

  8. Stop and restart Connection Manager. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

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

About Automatic Rerating of Out-of-Order Events

Events are processed by Pipeline Manager in the order that call details records (CDRs) are received. If the CDRs are sent out of order to Pipeline Manager, the events are processed out of order as well. Usually, this is not a problem; however, correct rating sometimes depends on rating events in chronological order (for example, when usage counters are used).

You can configure BRM to detect events that must be rated in chronological order and rerate them. To use out-of-order rerating, you define the criteria for when an out-of-order event must be rerated. When an event is rated, the FCT_EventOrder module uses the criteria and the event timestamps to determine if the event needs to be rerated.

About Detecting Out-of-Order Events

To enable out-of-order rerating, you configure criteria BRM uses to detect when events qualify for out-of-order rerating. Events must be rated in chronological order only when resources from the same balance group are affected, so the balance group is assumed as part of the detection criteria. If an account owns more than one service instance, each using a different balance group, out-of-order detection is applied to only the balance group associated with the event (the criteria name and balance group combination that is stored in the /profile/event_ordering object).

Pipeline Manager loads your detection criteria configuration at startup as follows:

  • The DAT_PortalConfig module retrieves data from the /config/event_order_criteriaobject and loads it into its memory. This data specifies the criteria for determining if an event qualifies for out-of-order detection. The criteria is based on:

    • Service types

    • Event types

    • Products

    • Discounts

    • A combination of service types, event types, products, and discounts

    For more information, see "About Out-of-Order Rerating Criteria".

    Note:

    This feature supports branding. You can have a different configuration for each brand.
  • The DAT_AccountBatch module retrieves data from the /profile/event_ordering profile object and loads it into its memory. This data includes the timestamp for the last time an event was processed for a particular billing cycle with the criteria specified in the /config/event_order_criteria object and the balance group determined when an EDR is found to be out of order.

    Note:

    If an out-of-order event comes in from a previous billing cycle after billing has run for that cycle (for example, when delayed billing is configured), the event is handled by default as if it is part of the current billing cycle.

How BRM Rerates Out-of-Order Events

The overall process for rerating out-of-order events is as follows:

  1. Pipeline Manager loads your detection criteria configuration at startup. See "About Detecting Out-of-Order Events".

  2. An event is rated in the pipeline and is rated by the rating and discounting modules.

  3. The FCT_EventOrder module gets the out-of-order detection criteria from the DAT_PortalConfig module to determine if the event needs to be rerated.

    In addition, FCT_EventOrder gets data from the DAT_AccountBatch module that specifies the latest event processed time for each appropriate criterion and balance group combination for an active billing cycle.

  4. FCT_EventOrder determines whether the event needs to be rerated:

    • If the event is out of order, the module proceeds to the next step.

    • If the event is not out of order, FCT_EventOrder triggers an update to the last event processed time in the DAT_AccountBatch memory. A record (record type = 850) is added to the pipeline output to update the /profile/event_ordering object with the new event's start time.

  5. The event data record (EDR) is kept in the FCT_EventOrder module's shared memory until after the transaction commits, when it is then sent to a rerate-request file. When Batch Controller detects this file, it starts the OODHandler batch handler to process it. The rerate-request file contains multiple accounts for which out-of-order events were detected.

    Note:

    Rerate-request file names use the following format:

    outputPrefix_pipelineName_transactionID_sequenceNumber.xml
    

    where:

    outputPrefix is the prefix specified by the OutputPrefix entry in the FCT_EventOrder module registry. The default is ood.

    pipelineName is the name of the pipeline; in the following example, the name is ALL_RATE.

    transactionID is the transaction ID.

    sequenceNumber is the sequence number of the job.

    For example:

    ood_ALL_RATE_14_0.xml
    
  6. The OODHandler batch handler processes the out-of-order rerate-request file, moves it to the BRM_Home/apps/pin_ood_handler/process directory, and calls the "pin_load_rerate_jobs" utility.

  7. The pin_load_rerate_jobs utility creates an input flist with the following rerate output file data:

    • Account

    • Balance Group

    • CriteriaName

    • Rerate Start Time

    • Service

    It then calls the PCM_OP_ACT_USAGE opcode in calc-only mode, which generates a notification event (/event/notification/activity/out_of_order) that triggers the PCM_OP_ACT_HANDLE_OOD_EVENT opcode. PCM_OP_ACT_USAGE passes the data to PCM_OP_ACT_HANDLE_OOD_EVENT.

  8. PCM_OP_ACT_HANDLE_OOD_EVENT calls the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode.

  9. PCM_OP_RERATE_INSERT_RERATE_REQUEST checks for duplicate rerate jobs in the rerate-request file and calls other opcodes to create a rerate job out of the file.

  10. The rated event is loaded into the BRM database by Rated Event (RE) Loader. If the event qualifies for out-of-order detection (and the event is in order), RE Loader updates the account's /profile/event_ordering object.

    Note:

    The /profile/event_ordering object stores data for the current and next billing cycles and for closed billing cycles. To clean up data for closed billing cycles, see "Purging Event Ordering Profile Data for Closed Billing Cycles".

About Out-of-Order Rerating Criteria

When the FCT_EventOrder module checks for out-of-order events, it uses the following criteria:

  • The timestamp of the event. If the event is later than the latest event that is under consideration, the event is not out of order.

  • The out-of-order detection criteria in which the event is defined in the /config/event_order_criteria object. If the event is not defined in any criteria in the /config/event_order_criteria object, it is assumed the event does not need to be rated in chronological order.

  • The last event processed time for each balance group and the name of the trigger-dependant rerating criteria for that event for a billing cycle in the account's /profile/event_ordering object. If the event has a later timestamp than the latest event processed time for an event that uses the same balance group and criteria name, the event is not out of order.

Define the criteria for the events you must rate in chronological order in the /config/event_order_criteria object. The data stored in the /config/event_order_criteria object consists of two parts:

  • The name of the criterion.

  • One or more parameters, such as a service or event type or a product name or discount name.

Your configuration can use as many parameters as you require. Table 29-2 provides examples of out-of-order criteria and what they mean for out-of-order detection:

Table 29-2 Criteria for Out-of-Order Detection

Criteria Out-of-Order Detection

Criteria name: GSM_TEL_SERVICE

Parameter: /service/gsm/telephony

All events for the GSM telephony service should be considered for out-of-order rerating.

Criteria name: GSM_EVENTS

Parameter: /event/delayed/session/telco/gsm/telephony

Parameter: /event/delayed/session/telco/gsm/sms

Parameter: /event/delayed/session/telco/gsm/fax

All GSM events should be considered for out-of-order rerating.

Criteria name: GSM_Product

Parameter: GSM Voice Product

All events for a specific product should be considered for out-of-order rerating.

All EDRs that are rated by the GSM Voice Product will be considered for out-of-order rerating.


For detailed information on defining your criteria, see "Defining Out-of-Order Criteria".

Setting Up Out-of-Order Rerating

To set up out-of-order rerating, perform the tasks in the following sections:

Defining Out-of-Order Criteria

When you define out-of-order criteria, you specify parameters for events, services, discount names, or product names that qualify for out-of-order detection. The parameters you specify are the criteria BRM uses to ensure that events are rated in chronological order when you want them to be. For more information, see "About Out-of-Order Rerating Criteria".

Important:

You should know how your price plans are structured to track resources, such as resources for a specific service or resources for a specific type of usage. Tracking resources can involve using service-level balance groups and a criterion is set up for events that use the same balance group.

For more information, see "Tracking Resources by Service" and "About Tracking Resources in Account Sub-Balances".

You typically list parameters that use the same balance group under the same criterion name. Services that use different balance groups are listed under separate criterion names. The /profile/event_ordering object stores the latest event processed time for each appropriate criteria and balance group combination for each active billing cycle. For more information, see "Defining Criteria under Separate Criteria Names".

You define out-of-order criteria in the pin_config_ood_criteria.xml file in BRM_Home/sys/data/config. For a sample of this file, see "Sample Out-of-Order Criteria File".

You can define criteria by using one or more parameters.

  • The simplest criteria uses a single parameter.

    For example:

    - <OodCriteriaElement>
    <CriteriaName>GSM_TEL_SERVICE</CriteriaName> 
    - <ParameterList>
    <Parameter Type="Service">/service/gsm/telephony</Parameter> 
    </ParameterList>
    </OodCriteriaElement>
    
  • You can use two parameters in the following combinations:

    • Service Type, Event Type

    • Service Type, Product

    • Service Type, Discount

    • Event Type, Product

    • Event Type, Discount

    For example:

    - <OodCriteriaElement>
    <CriteriaName>GSM_TEL_SERVICE</CriteriaName> 
    - <ParameterList>
    <Parameter Type="Service">/service/gsm/telephony</Parameter> 
    <Parameter Type="Event">/event/delayed/session/gsm/telephony</Parameter>
    </ParameterList>
    </OodCriteriaElement>
    
  • You can use multiple parameters to combine service type, event type, product, and discount.

    For example:

    - <OodCriteriaElement>
    <CriteriaName>GSM</CriteriaName> 
    - <ParameterList>
    <Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
    <Parameter Type="Service">/service/telco/gsm/sms</Parameter> 
    <Parameter Type="Event">/event/delayed/session/telco/gsm/telephony</Parameter>
    <Parameter Type="Event">/event/delayed/session/telco/gsm/sms</Parameter>
    <Parameter Type="Product">GSM Voice Product</Parameter>
    <Parameter Type="Product">GSM Voice Discount</Parameter>
    </ParameterList>
    </OodCriteriaElement>
    

If you use a combination of event, service, and product or discount, the EDR parameters must match all of the following:

  • One service type (for example, service type 1 or service type 2)

  • One event type (for example, event type 1 or event type 2)

  • One product or discount (for example, product 1 or product 2 or discount 1 or discount 2)

For example, in the following detection criterion named GSM_Multi:

- <OodCriteriaElement>
<CriteriaName>GSM_Multi</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
<Parameter Type="Service">/service/telco/gsm/sms</Parameter> 
<Parameter Type="Event">/event/delayed/session/telco/gsm/telephony</Parameter>
<Parameter Type="Event">/event/delayed/session/telco/gsm/sms</Parameter>
<Parameter Type="Product">GSM Voice Product Telephony</Parameter>
<Parameter Type="Discount">GSM Voice Product SMS</Parameter>
</ParameterList>
</OodCriteriaElement>

The EDR must match the following parameters:

  • Service type /service/telco/gsm/telephony

  • Event type /event/delayed/session/telco/gsm/telephony

  • Product GSM Voice Product Telephony

Or the following parameters:

  • Service type /service/telco/gsm/sms

  • Event type /event/delayed/session/telco/gsm/sms

  • Product GSM Voice Product SMS

That means that when an EDR arrives for that particular service rated by that particular product when that particular event occurs, BRM considers it for out-of-order rerating.

Defining Criteria under Separate Criteria Names

List services that use the same balance group under the same criteria name. BRM does not differentiate between the events of these services when obtaining the latest event processed time in the account's profile object because they consume resources in the same way for rating.

The following out-of-order criteria would apply to two GSM services that share the same balance group:

- <OodCriteriaElement>
<CriteriaName>GSM</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
<Parameter Type="Service">/service/telco/gsm/sms</Parameter>
</ParameterList>
</OodCriteriaElement>

If the latest event processed time is later than an EDR event timestamp, the event needs to be rerated regardless of the service to which it belongs; for example, for the preceding GSM criteria, if the latest event processed time is 2 p.m. for an SMS event and the EDR is a telephony event with a 1 p.m. timestamp, the event is out of order and needs to be rerated.

If an account can own more than one instance of a service and each instance uses a different balance group, out-of-order rerating is applied to the balance group of the service instance to which the event belongs. Accounts can have multiple balance groups if you offer plans in which service-level balance groups are used (see "Tracking Resources by Service" for more information). When events for these services must be rated in chronological order, you must evaluate the out-of-order criteria for these services separately from each other.

You list services that use different balance groups under separate criteria names. The following out-of-order criteria would apply to two GSM services that use different balance groups:

- <OodCriteriaElement>
<CriteriaName>GSM_TEL</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
</ParameterList>
</OodCriteriaElement>
- <OodCriteriaElement>
<CriteriaName>GSM_SMS</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/sms</Parameter>
</ParameterList>
</OodCriteriaElement>

Because the latest event processed times for all services used by an account are tracked in one profile object, BRM uses the unique criteria name to differentiate between the service-specific latest event processed times. Thus, in the preceding criteria, BRM uses the criteria name GSM_TEL in the account's profile object to track the latest event processed time for the telephony events and uses the criteria name GSM_SMS to track the latest event processed time for the SMS events.

There may be times when you must define parameters under separate criterion names when they share the same balance group but you are tracking different resources. For example, if a GSM telephony service and a GSM discount share a balance group and are rated by the same event, you would define a criterion for the discount if you are tracking the last time resources were consumed with that particular discount.

Avoiding Overlapping Criteria

If you configure criteria already contained in another criteria, the "load_pin_config_ood_criteria" utility reports an error, and nothing is loaded into the database. In the following example, the GSM_TEL_1 criteria is a superset of the GSM_TEL_2 criteria, so GSM_TEL_2 is considered an overlapping criteria:

- <OodCriteriaElement>
<CriteriaName>GSM_TEL_1</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter>
</ParameterList>
</OodCriteriaElement>
- <OodCriteriaElement>
<CriteriaName>GSM_TEL_2</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter>
<Parameter Type="Event">/event/delayed/session/telco/gsm/telephony</Parameter> 
</ParameterList>
</OodCriteriaElement>

In the following example, the GSM_Dual_A criteria is a superset of the GSM_Multi_B criteria, so GSM_Multi_B is an overlapping criteria:

- <OodCriteriaElement>
<CriteriaName>GSM_Dual_A</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
<Parameter Type="Service">/service/telco/gsm/sms</Parameter> 
<Parameter Type="Product">GSM Voice Product Telephony</Parameter>
<Parameter Type="Discount">GSM Voice Discount SMS</Parameter>
</ParameterList>
</OodCriteriaElement>
- <OodCriteriaElement>
<CriteriaName>GSM_Multi_B</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
<Parameter Type="Service">/service/telco/gsm/sms</Parameter> 
<Parameter Type="Event">/event/delayed/session/telco/gsm/telephony</Parameter>
<Parameter Type="Event">/event/delayed/session/telco/gsm/sms</Parameter>
<Parameter Type="Product">GSM Voice Product Telephony</Parameter>
<Parameter Type="Discount">GSM Voice Discount SMS</Parameter>
</ParameterList>
</OodCriteriaElement>

You would choose one of the preceding criterion based on your goals. You would never use both of them. For example:

  • You would configure the GSM_Dual_A criterion if you wanted BRM to consider EDRs for out-of-order rerating when they matched the following:

    • Any event type for the GSM telephony service that is also rated by the GSM Voice Product Telephony product.

    or

    • Any event type for the GSM SMS service that is also rated by the GSM Voice Discount SMS discount.

  • You would configure the GSM_Multi_B criterion if you wanted BRM to consider EDRs for out-of-order rerating when they matched the following:

    • The specific event type /event/delayed/session/telco/gsm/telephony for the GSM telephony service that is also rated by the GSM Voice Product Telephony product.

    or

    • The specific event type /event/delayed/session/telco/gsm/sms for the GSM SMS service that is also rated by the GSM Voice Discount SMS discount.

Because GSM_Dual_A is configured to consider all event types including the specific event types configured in GSM_Multi_B, the out-of-order detection configured in GSM_Multi_B is already handled by the GSM_Dual_A criterion. If you only want those specific event types to be checked for out-of-order detection, you would use GSM_Multi_B rather than GSM_Dual_A.

Sample Out-of-Order Criteria File

The following is a sample configuration of the pin_config_ood_criteria.xml file.

<?xml version="1.0" encoding="UTF-8" ?> 
- <OodCriteriaConfiguration xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig pin_config_ood_criteria.xsd">

- <!--  This file is a sample file. --> 
- <!--  This file needs to be modified based on the out-of-order configuration required --> 
- <!--  for an installation. THIS FILE SHOULD NOT BE LOADED WITH THE DATA SUPPLIED HERE. --> 

- <OodCriteriaElement>
<CriteriaName>TEL_SERVICE</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/telephony</Parameter> 
<Parameter Type="Event">/event/delayed/session/telco/gsm/telephony</Parameter> 
</ParameterList>
</OodCriteriaElement>

- <OodCriteriaElement>
<CriteriaName>GSM_SERVICE</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm/sms</Parameter> 
<Parameter Type="Event">/event/delayed/session/telco/gsm/sms</Parameter> 
</ParameterList>
</OodCriteriaElement>

- <OodCriteriaElement>
<CriteriaName>A_MULTI_TEL_SERVICE</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm</Parameter> 
<Parameter Type="Product">Standard GSM Telephony</Parameter> 
</ParameterList>
</OodCriteriaElement>

- <OodCriteriaElement>
<CriteriaName>A_MULTI_TEL_SERVICE1</CriteriaName> 
- <ParameterList>
<Parameter Type="Service">/service/telco/gsm</Parameter> 
<Parameter Type="Discount">Standard GSM Discount</Parameter> 
</ParameterList>
</OodCriteriaElement>

- <OodCriteriaElement>
<CriteriaName>TEL_SERVICE_EVENT</CriteriaName>
- <ParameterList>
<Parameter Type="Event">/event/delayed/session/telco/gsm</Parameter> 
</ParameterList>
</OodCriteriaElement>

</OodCriteriaConfiguration>

Loading Out-of-Order Criteria

To configure out-of-order criteria, you edit the pin_config_ood_criteria.xml file and load the contents of the file into the BRM database by using the load_pin_config_ood_criteria utility. The data is stored in the /config/event_order_criteria object.

Important:

To connect to the BRM database, the load_pin_config_ood_criteria utility needs a configuration (pin.conf) file in the directory from which you run the utility.

Caution:

The load_pin_config_ood_criteria utility overwrites existing out-of-order criteria. If you are updating out-of-order criteria, you cannot load new out-of-order criteria only. You must load complete sets of out-of-order criteria each time you run the load_pin_config_ood_criteria utility.

Note:

You can run this utility to configure out-of-order criteria for different brands.
  1. Edit the pin_config_ood_criteria.xml file in BRM_Home/sys/data/config. For a sample of this file, see "Sample Out-of-Order Criteria File".

  2. Save and close the file.

  3. Use the following command to run the load_pin_config_ood_criteria utility:

    load_pin_config_ood_criteria pin_config_ood_criteria.xml
    

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

    load_pin_config_ood_criteria BRM_Home/sys/data/config/pin_config_ood_criteria.xml 
    

    Tip:

    If you copy the pin_config_ood_criteria.xml file to the directory from which you run the load_pin_config_ood_criteriautility, you do not have to specify the path or file name. By default, the file is named pin_config_ood_criteria.xml. You can change this name.

    For more information, see "load_pin_config_ood_criteria".

  4. If Pipeline Manager is running, send a CBPReload semaphore to reload data. The Reload semaphore is used by the DAT_PortalConfig data module. If Pipeline Manager is not running, it will load the data the next time it is started.

To verify that the out-of-order criteria were loaded, you can display the /config/event_order_criteria object by using Object Browser, or use the robj command with the testnap utility.

Configuring Out-of-Order Detection in a Pipeline

To configure out-of-order detection in a pipeline, you do the following:

  1. Configure the DAT_PortalConfig module.

  2. Configure the FCT_EventOrder module.

    Important:

    FCT_EventOrder should be located in the pipeline after the rating (FCT_MainRating) and discounting (FCT_Discount) modules and before the rejection (FCT_Reject) module.

    When configuring FCT_EventOrder, specify the following:

Batching Out-of-Order Rerate Jobs

You can configure the FCT_EventOrder module to batch the out-of-order EDR data in its transactional memory and write it to separate rerate-request files after the transaction commits. Batching rerate jobs in this way improves performance during rerating. To control how many records FCT_EventOrder batches into separate rerate request files, you specify an amount of time in minutes using the RerateDelayTolerance registry entry.

When the transaction commits, FCT_EventOrder sorts the rerate-request data in its transactional memory based on the EDR start time. The rerate start time of the first record in the rerate-request file is the rerate start time for the rerate job. As FCT_EventOrder writes the events into the rerate-request file, it compares the start time of the first record with the start time of each event being added. If the time difference exceeds the value of the RerateDelayTolerance entry, that event becomes the last record in the rerate-request file, and a new rerate-request file is created.

Example 1

If the RerateDelayTolerance entry is set to 180 minutes, and the start time of the first event in the rerate-request file is 3:15 p.m, events are added until the start time of an event is greater than 6:15 p.m.

Example 2

If the RerateDelayTolerance entry is set to 30 minutes, and the start time of the first event in the rerate-request file is 11:00 a.m. and four subsequent events have start times of 11:10 a.m., 12:05 p.m., 12:15 p.m., and 12:33 p.m, FCT_EventOrder creates two rerate-request files, resulting in two rerate jobs (/job_batch/rerate objects) as follows:

  • Rerate job 1 contains accounts associated with EDRs that have these start times:

    11:00 a.m.

    11:10 a.m.

  • Rerate job 2 contains accounts associated with EDRs that have these start times:

    12:05 p.m.

    12:15 p.m.

    12:33 p.m.

In the preceding example, if for one account the first EDR arrives at 11:10 a.m. and the last EDR arrives at 11:45 a.m., the account is included in Rerate job 1.

Configuring the Number of Accounts in an Out-of-Order Rerate Job

To improve batch rerating throughput, you can specify the number of accounts FCT_EventOrder assigns to each rerate job by using the NumberOfAccountLimit registry entry. FCT_EventOrder writes out the number of accounts specified by this entry to the rerate-request file, which, in turn, becomes the rerate job after detection of duplicate rerate requests is complete.

The default for the NumberOfAccountLimit registry entry is 1000.

Important:

The NumberOfAccountLimit registry entry of FCT_EventOrder is similar to the per_job configuration entry of the pin_rerate utility. When you configure these entries, BRM recommends you use the same value.

For more information, see "Configuring the Number of Accounts Per Job and Number of Jobs per Transaction".

Configuring Event Notification for Out-of-Order Rerating

To create rerate jobs automatically when certain events are not in chronological order, you must configure event notification for out-of-order rerating. BRM uses the /event/notification/activity/out_of_order event to trigger automatic rerating when an out-of-order event occurs.

To configure event notification for out-of-order rerating, do the following:

  1. If your system has multiple configuration files for event notification, merge them.

    All of the event notification configuration files available in your system are in the BRM_Home/sys/data/config directory.

    Depending on which BRM features you use, your system may contain one or more configuration files for event notification; for example, a wireless system may use pin_notify_ifw_sync (supports Account Synchronization and standard recycling) or pin_notify_telco (supports GSM Manager). If your system contains more than one of these files, you must merge their contents into a single file.

  2. Add the following entry to the merged file:

    # Event notification for out-of-order rerating
    177    0    /event/notification/activity/out_of_order
    

    This configures the /event/notification/activity/out_of_order event to trigger rerating and to call the PCM_OP_ACT_HANDLE_OOD_EVENT opcode (opcode ID number 177) to select which events to rerate.

    PCM_OP_ACT_HANDLE_OOD_EVENT calls the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode to insert a rerate job for the out-of-order events.

    Note:

    You can configure this notification event to call a custom opcode. The custom opcode can analyze the event, determine if rerating is required, and then call PCM_OP_RERATE_INSERT_RERATE_REQUEST to create the rerate job with a rerate reason. For more information, see "Setting Up Trigger-Dependent Rerating".
  3. (Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list.

  4. (Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger.

  5. Load your final event notification list into the BRM database by running the load_pin_notify utility to load the contents of the file into the /config/notify object.

    For instructions on using this utility, see "Using Event Notification" in BRM Developer's Guide.

Specifying a Reason Code for Rerating Out-of-Order Events

Rerate jobs can be assigned a rerate reason code. When you run the pin_rerate utility, you can rerate all accounts for a rerate job with a specific reason code. By default, rerate jobs for out-of-order events have the reason code 1. You can change this to any number you want in the CM pin.conf file by using the following entry:

fm_act ood_rerate_job_reason_code rerate_reason_code

Important:

Rerate reason codes can also be assigned by other BRM automatic rerating features and when you run pin_rerate. To rerate accounts according to type of rerate reason code, ensure that your rerate reason codes are unique.

For more information about processing rerate jobs according to a rerate reason code, see "About Processing Rerate Jobs Created by Automatic Rerating".

Configuring Batch Controller for Rerating Out-of-Order Events

The OODHandler batch handler is run automatically by Batch Controller. You must configure Batch Controller and the OODHandler batch handler.

To configure Batch Controller to rerate out-of-order events:

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

  2. Add the following entries listed in Table 29-3 for the OODHandler batch handler:

    Table 29-3 Entries for OODHandler Batch Handler

    Entry Description

    batch.random.events

    Specify your event identifier in the event identifier list. For example:

    batch.random.events    TEL, SMS, FAX, OODHANDLER
    

    where OODHANDLER is your event identifier.

    event_identifier.name

    Specify a description for the event identifier. For example:

    OODHANDLER.name    OODHANDLER usage
    

    event_identifier.file.location

    Specify the path to the directory where Pipeline Manager puts the rerate request files. The location of this directory is configured in the OutputDirectory entry in the FCT_EventOrder module wireless registry file (Pipeline_home/conf/wireless.reg).

    Important: You must create the directory. It is not created by BRM installation scripts.

    For example:

    OODHANDLER.file.location    Pipeline_home/data/out/ood
    

    event_identifier.file.pattern

    Specify the rerate job output file name. When Batch Controller detects a file with this name, it starts the batch handler.

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

    For example:

    OODHANDLER.file.pattern      *.xml
    

    event_identifier.handlers

    Specify the batch handler identifier. For example:

    OODHANDLER.handlers      OodHandler
    

    handler_identifier.name

    Specify a description for the batch handler identifier. For example:

    OodHandler.name      OODHandler
    

    handler_identifier.max.at.lowload.time

    handler_identifier.max.at.highload.time

    Specify 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:

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

    handler_identifier.start.string

    Specify the command that starts the OODHandler batch handler. For example, the default is:

    OodHandler.start.string      BRM_Home/apps/pin_ood_handler/OODHandler.pl. 
    

    Important: Copy the BRM_Home/bin/OODHandler to BRM_Home/apps/pin_ood_handler/OODHandler.pl.


  3. Save and close the file.

Configuring the OODHandler Batch Handler for Rerating Out-of-Order Events

The OODHandler batch handler retrieves the rerate-request file from the Pipeline Manager output and runs the pin_load_rerate_jobs utility to create rerate jobs. After the rerate jobs are created, the batch handler moves the rerate-request file to a different directory.

Important:

If you use the ConfigurableValidityHandler batch handler for loading first-usage validity data, do not use the OODHandler_config.values file as instructed below. Instead, you must configure the OODHandler batch handler in the ConfigurableValidityHandler configuration file (BRM_Home/apps/pin_rel/ConfigurableValidityHandler_config.values). ConfigurableValidityHandler runs both the pin_load_rerate_jobs utility and the utility for loading validity data.

To configure the OODHandler batch handler:

  1. Open the OodHandler_config.values configuration file in BRM_Home/apps/pin_ood_handler.

  2. Edit the following entries shown in Table 29-4. For information about other entries, see the OodHandler_config.values file.

    Table 29-4 Entries to Configure OodHandler Batch Handler

    Entry Description

    $FILETYPE

    Specify the file name pattern of the rerate-request file. For example:

    $FILETYPE    = "*.xml.bc";
    

    Note: The asterisk (*) represents zero or more characters in the file name. No other wildcards are supported.

    Batch Controller runs the OODHandler batch handler for each file with a name that matches this pattern.

    Important: The file name pattern must end with the .bc extension. Batch Controller automatically appends .bc to each file name before it runs a batch handler.

    $HANDLER_DIR

    Specify the path to the directory containing the OODHandler batch handler configuration files, log files, and other processing files and directories.

    The default is BRM_Home/apps/pin_ood_handler.

    $pinLoadRerateJobsDir

    Specify the path to the directory where the pin_load_rerate_jobs utility processes the files (this contains the pin_rerate_job_info.xsd file).

    The default is BRM_Home/apps/pin_ood_handler/process.

    $pinLOADRERATEJOBS

    Specify the application run by the OODHandler batch handler to process the files. For example:

    $pinLOADRERATEJOBS    = "pin_load_rerate_jobs";
    

    $STAGING

    Specify the full path to the OODHandler batch handler rerate-request file location.

    For example:

    $STAGING    = "$Pipeline_home/data/out/ood";
    

    This is the same directory where Pipeline Manager puts the rerate-request files. When Batch Controller detects the rerate-request files in this location, it calls the OODHandler batch handler.

    Note: The location of this directory is also configured in the OutputDirectory entry in the FCT_EventOrder module wireless registry file (Pipeline_home/conf/wireless.reg). You must create the directory. It is not created by BRM installation scripts.

    $PROCESSING

    Specify the full path to the directory from which the rerate job files are processed by the OODHandler batch handler.

    The default is $pinLoadRerateJobsDir.

    The OODHandler batch handler takes the files from the $STAGING directory and places them here.

    $LOGFILE

    Specify the full path to the OODHandler batch handler log file.

    For example:

    $LOGFILE = "$HANDLER_DIR/OOD_Handler.log";
    

  3. Save and close the file.

Purging Event Ordering Profile Data for Closed Billing Cycles

If out-of-order detection is configured in the system, one instance of the /profile/event_ordering object is created for each account during customer creation. The profile exists for the lifetime of the account, and entries are updated and added to it by RE Loader every time events are processed for services belonging to the account that qualifies for out-of-order detection.

You can use the purge_profile_event_ordering script to clean up entries for closed billing cycles from the /profile/event_ordering object as follows:

Log on to the machine where dm_oracle is installed and run the Shell script:

BRM_Home/apps/pin_rel/purge_profile_event_ordering

The purge_profile_event_ordering script is located in BRM_Home/apps/pin_rel.

Note:

Cleaning up data for closed billing cycles is not automatically synchronized with Pipeline Manager. You must restart Pipeline Manager for the in-memory entries to be cleaned up.

About Trigger-Dependent Rerating

Trigger-dependent rerating enables you to specify when events are automatically rerated. For example, if you rerate usage following a product cancellation, you can set up a product cancellation event to automatically trigger rerating.

To configure trigger-dependent rerating, you set up event notification to call a custom opcode that analyzes events to determine if rerating is required. For example, the criteria for rerating might be:

  • If the event is a cancel event.

  • If the cancel event for a product requires proration on cancellation.

  • If rerating needs to occur to calculate proration for this product.

If the notification event triggers rerating, the custom opcode specifies which events for an account must be rerated and sends the rerating requirements to the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode to create a rerate job.

Trigger-dependent rerating works as follows:

  1. An event that you have configured in event notification occurs to call the custom opcode. For example, this might be a purchase event, product cancellation, or change in account status. All the fields in the event are passed as input to the custom opcode.

  2. The custom opcode analyzes the event using your custom selection criteria to determine if it should trigger rerating. For example, the opcode might be called when all purchase events occur, but not all purchase events will trigger rerating.

  3. If the event triggers rerating because it matches your selection criteria, the custom opcode assigns an optional rerate reason code for rerating those events, specifies any price overrides, and calls PCM_OP_RERATE_INSERT_RERATE_REQUEST to create the rerate job.

  4. PCM_OP_RERATE_INSERT_RERATE_REQUEST creates a rerate job that includes:

    • The account that needs to be rerated.

    • The events that must be rerated for that account.

    • The start time from which to rate the events.

    • The rerate reason.

    • Price overrides, if any.

      Note:

      If more than one account is included in the rerate job, the same selection criteria, price overrides, and start time apply to all the accounts.

    For more information on how PCM_OP_RERATE_INSERT_RERATE_REQUEST creates rerate jobs, see "How BRM Creates Rerate Jobs".

  5. You run the "pin_rerate" utility to execute the rerate job and rerate the events.

Figure 29-2 shows the trigger-dependent rerating process when a purchase event occurs:

Figure 29-2 Trigger-Dependent Rerating Process

Description of Figure 29-2 follows
Description of ''Figure 29-2 Trigger-Dependent Rerating Process''

To set up trigger-dependent rerating, see "Setting Up Trigger-Dependent Rerating".

Setting Up Trigger-Dependent Rerating

To set up trigger-dependent rerating, you do the following:

  1. Create a custom opcode for trigger-dependent rerating. See "Creating a Custom Opcode for Trigger-Dependent Rerating".

  2. Configure event notification for trigger-dependent rerating. See "Configuring Event Notification for Trigger-Dependent Rerating".

Creating a Custom Opcode for Trigger-Dependent Rerating

To use trigger-dependent rerating, you must write custom code to specify when to create rerate jobs automatically when certain events occur. You can write your code by doing one of the following:

  • Create one or more custom opcodes.

    You can create multiple custom opcodes to handle rerating events for different scenarios or create one opcode to handle all scenarios.

  • Use the PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST policy opcode.

    This policy opcode handles rerating events for BRM automatic rerating scenarios. You can modify and recompile this policy opcode to handle your own automatic rerating scenarios.

    For more information about this opcode, see "About Automatic Rerating".

The opcode you use to define your custom code for trigger-dependent rerating must call the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode.

Your custom code is required to pass in the following to PCM_OP_RERATE_INSERT_RERATE_REQUEST:

  • The POIDs of the accounts to be rerated.

    You can also pass in an optional array of additional accounts that are related to these accounts (for example, an account that used the account's service before a line transfer) and the start time for each account.

    Note:

    If an array of accounts is passed in, the same selection criteria and price overrides apply to all the accounts.
  • The time from which events must be rerated for the accounts.

Your custom code can optionally pass in the following to PCM_OP_RERATE_INSERT_RERATE_REQUEST:

Your custom selection criteria and price override information for creating rerate jobs can include anything that can be passed as input to the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode. For detailed information about the array and field names that can be passed, refer to the PCM_OP_RERATE_INSERT_RERATE_REQUEST input and output flist specifications and the class specifications of the /job/rerate and /job_batch/rerate storable classes.

When an event triggers your custom opcode, your opcode may need to obtain data from other events in the database to obtain all of the information required for rerating.

Specifying a Rerate Reason Code

PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST or your custom opcode can pass an optional rerate reason code to PCM_OP_RERATE_INSERT_RERATE_REQUEST. The rerate reason code is stored in the rerate job and can be used to select jobs from the rerate queue for rerating using pin_rerate.

Your rerate reason codes can be any integer, except 1 (1 is a reserved default value for pipeline-generated rerating requests).

Important:

Because you can use multiple rerate reason codes to group rerate jobs for different rerating scenarios, ensure that your rerate reason codes are unique.

The default reason code is 0.

For information about assigning a rerate reason code by using PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST, see "About Automatic Rerating".

For information about processing rerate jobs according to the rerate reason code, see "About Processing Rerate Jobs Created by Automatic Rerating".

Specifying Selection Criteria

When an account needs to be rerated, not every event for that account may need to be rerated from the specified rerate start time. Your custom opcode can optionally send selection criteria to the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode so that all events for the account can be filtered to select only the subset of events that needs to be rerated.

For example, you may need to rerate events only when they are generated by a specific service or only when they are rated by a specific product or discount. You can specify selection criteria to rerate all accounts' events that have an event type of /event/delayed/session/telco/gsm/telephony but only when they are for the service type /service/telco/gsm/telephony and only when they are rated by the product GSM Voice Telephony.

Your selection criteria can be any of the following:

  • Event types (array PIN_FLD_EVENTS)

  • Service types (array PIN_FLD_SERVICES)

  • Product POIDs (array PIN_FLD_PRODUCTS)

  • Discount POIDs (array PIN_FLD_DISCOUNTS)

  • Deal POIDs (array PIN_FLD_DEALS)

    Note:

    Products and discounts are mutually exclusive with deals. Deals include products and discounts, so you can pass in a deal array instead of the product array and discount array.

Specifying Price Overrides

You can specify products, discounts, or deals to use for a specific rerate job to override an account's subscribed product, discount, or deals during rerating. The price override applies only to that rerate job; subsequent rerate jobs use the subscribed pricing or their own override pricing.

Your custom opcode can send the following price override data to the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode to set a price override for a rerate job:

  • An optional array of override product POIDs along with the product it is overriding (PIN_FLD_OVERRIDE_PRODUCTS).

  • An optional array of override discount POIDs along with the discount it is overriding (PIN_FLD_OVERRIDE_DISCOUNTS).

  • An optional array of override deal POIDs along with the deal it is overriding (PIN_FLD_OVERRIDE_DEALS).

    Note:

    Products and discounts are mutually exclusive with deals because deals include products and discounts. The deal is translated to a list of products and discounts when it is passed to the rerating opcodes.

The override products and discounts or deals must already be defined in your BRM database. They must also be functionally equivalent to the subscribed products and discounts or deals; for example, the priority or event map would be the same. In addition, override products and discounts cannot be configured as first usage products. See "About Effective Periods That Start on First Usage" for information about first usage.

Important:

You must rerate accounts when an override pricing product is canceled in a given billing cycle so that refunds can be applied correctly. See "Configuring Event Notification for Override Pricing".

BRM creates a record when rerating is run with price overrides by using the /rerate_session/override_info object. When override pricing is passed to the PCM_OP_SUBSCRIPTION_RERATE_REBILL opcode, this opcodes creates a /rerate_session/override_info object to capture the override pricing information used during rerating.

Price overrides are automatic when you use the Best Pricing feature. For that feature, BRM calculates the best price from alternate products and discounts and rerates events to use the best pricing. When rerating events, the product or discount that provides the best pricing is the override product or discount.

Configuring Event Notification for Trigger-Dependent Rerating

When you configure event notification for trigger-dependent rerating, you specify the following in the pin_notify file in BRM_Home/sys/data/config (or your own merged event notification configuration file):

  • The events that trigger rerating.

  • The custom opcodes you want BRM to use to analyze the events, to identify whether rerating is required.

To configure event notification for trigger-dependent rerating, do the following:

  1. If your system has multiple configuration files for event notification, merge them.

  2. Ensure that the merged file includes the events you want to trigger rerating and the opcode number of the custom opcode you want to analyze those events.

    For example, these entries call the custom opcode with opcode number 10000:

    # Event notification for trigger-dependent rerating
    10000    0    /event/customer/status
    10000    0    /event/billing/product/action/purchase
    
  3. (Optional) Add, modify, or delete entries in your final event notification list.

  4. (Optional) Create custom code for event notification to trigger.

  5. Load your final event notification list into the BRM database.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Configuring Event Notification for Override Pricing

If you use override pricing, you must set up trigger-dependent rerating to rerate accounts for cases where a refund could not be applied because an override pricing product was canceled in a given billing cycle.

For a given billing cycle, if you rerate an account with an override product and the product is canceled, BRM cannot calculate a refund for that account because the product is not available to apply the necessary cycle fees. When the refund cannot be applied, BRM creates the notification event /event/notification/product/cancel/no_refund.

To calculate the correct refund amount, you must set up trigger-dependent rerating as follows:

  1. Write custom code to specify:

    • The account to rerate from the /event/notification/product/cancel/no_refund event.

    • The product to use to apply the cycle fees for the refund to use the override product that was canceled.

      BRM uses the base pricing product associated with the account if you do not specify the override product that was canceled. To specify the override product that was canceled, obtain its information from the latest /rerate_session/override_info object created for the given account.

  2. Include your code in a custom opcode or in the PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST policy opcode that handles automatic rerating (opcode number 3787).

    If you create a custom opcode, it must call the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode to create the rerate job.

  3. Set up event notification for the event /event/notification/product/cancel/no_refund to call your custom opcode or the policy opcode. For example, to call the PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST policy opcode, you would enter:

    # Event notification for trigger-dependent rerating
    3787    0    /event/notification/product/cancel/no_refund
    

    For detailed instructions on setting up event notification, see "Configuring Event Notification for Trigger-Dependent Rerating".