30 Using the pin_rerate Utility

This chapter provides an overview of how you use the Oracle Communications Billing and Revenue Management (BRM) pin_rerate utility and the functions the utility performs.

For general information about rerating, see "About Rerating Events".

For information about what you can do with pin_rerate, see "About Comprehensive Rerating Using pin_rerate".

About Using the pin_rerate Utility

You use the pin_rerate command-line utility to perform the following tasks:

If rerating fails, pin_rerate creates a report that includes the account numbers and start times for failed rerate jobs. The report file name is pin_rerate.status_report and is in the directory from which you ran the utility.

When rerate jobs have been processed, you can run pin_rerate to purge them from the database. See "Parameter for Purging Rerate Jobs".

Selecting Accounts and Events for Rerating

The first step in the rerating process is running pin_rerate to select the accounts and associated events to rerate from the BRM database. The pin_rerate utility creates rerate jobs (/job/rerate and /job_batch/rerate objects) to store the information about the selected accounts. See "About Rerate Jobs".

Note:

If you use automatic rerating, accounts are selected and rerate jobs are created automatically for certain scenarios. For more information, see "About Automatic Rerating".

Caution:

Do not move accounts to another database schema while rerating events for those accounts.

Specifying Accounts for Rerating

By default, the pin_rerate utility selects for rerating all the accounts and then all the events associated with those accounts that occurred from the start time that you specify.

For example, the following command selects all the accounts from the BRM database and, for those accounts, selects all the events that occurred after 07/23/2007.

pin_rerate -t 07/23/2007

pin_rerate provides a set of parameters that you can optionally use to select only specific accounts that meet one of the following requirements:

  • One or a set of accounts identified by the account POIDs

  • Accounts with events rated by a particular product

  • Accounts with events rated by a particular discount

  • Accounts with events rated by products and discounts associated with a particular deal

  • Accounts with events generated for a particular service type or subscription service

  • Accounts with events associated with an account's bill unit or bill unit and balance group

  • Accounts that have particular event types

For example, when you use the -p parameter:

pin_rerate -p products.txt -t 07/23/2007

pin_rerate does the following:

  • Selects only the accounts that have events related to the products in the products.txt file.

  • Selects all the events for the selected accounts that occurred after 07/23/2007.

When you use the -line parameter:

pin_rerate -line 6495832245 -t 09/21/04

pin_rerate does the following:

  • Selects only the accounts that have the subscription service with the phone number 6495832245.

  • Selects all the events for the selected accounts that occurred after 09/21/04.

For a complete list of the pin_rerate parameters, see "pin_rerate".

Specifying Events for Rerating

By default, pin_rerate rerates all the events for the selected accounts from the start time that you specify. You can specify to rerate only specific events for the selected accounts by using the -r parameter. This is called selective rerating.

Important:

Do not use selective rerating if:

  • Your rating scheme includes credit limits or resource-based tiers. These schemes require that all events related to an account are rerated to assure accurate rerating.

  • Deferred taxation is used for taxing events during rerating.

If you use selective rerating, be sure to consider how it might affect rating overall because account balances can be impacted by different types of events: a cycle event can grant free minutes and a usage event consumes free minutes from the same balance. If, for example, you change the pricing for a product that grants free minutes, you must rerate all events for the accounts that own the product. It would be incorrect to use selective rerating in this case.

The -r parameter must be used with parameters that specify the accounts to select for rerating. When the -r parameter is used, rerating applies the account selection criteria to the account's events as well and selects only those events that meet the selection criteria.

The -r parameter can be used with any of the account selection parameters.

For example, when you use -r with the -s parameter:

pin_rerate -r -s service.txt -t 07/23/2007

pin_rerate does the following:

  • Selects only the accounts that have events related to the services in the service.txt file.

  • Selects only the events related to the services in service.txt that occurred after 07/23/2007 for the selected accounts.

When you have a high volume of events to rerate, you can rerate events that are rated only in real time, such a cycle and purchase events. To do this, you use the -r parameter in combination with the -n parameter for specifying event types. You define all the event types rated by real-time rating in an input file.

For example, you could specify the following event types in a file named event.txt:

  • /event/billing/product/fee/cycle/cycle_forward_monthly

  • /event/billing/product/fee/purchase

  • /event/billing/product/fee/cycle/cycle_forward_arrear

When you run the following command:

pin_rerate -t 01/01/2007 -n event.txt -r

pin_rerate does the following:

  • Selects all accounts that have events with event types in the event.txt file.

  • Selects only the events with event types in the event.txt file and which occurred after 01/01/2007 for the selected accounts.

When rerating cycle fee events, to get the correct rerating results, include the cycle events that occur during billing that are configured in the product, such as cycle discount, rollover, and fold events in the event file.

For example, if a cycle discount is configured to be some percentage of the charge during billing and if the cycle forward arrear fee is modified during the billing cycle, then to rerate the cycle forward arrear event, you need to include both events in the event file:

  • /event/billing/product/fee/cycle/cycle_forward_arrear

  • /event/billing/cycle/discount

If the event type specified in the -n parameter input file has subclasses, all subclass events are also rerated, providing they meet the selection criteria. For example, if you specify /event/delayed/session/telco in the -n parameter input file, events of type /event/delayed/session/telco/gsm that meet the selection criteria are also rerated.

For a complete list of the pin_rerate parameters, see "pin_rerate".

Customizing Event Searches for Selective Rerating

You can further refine the event selection criteria used for selective rerating by customizing the PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE policy opcode. This opcode is called when the pin_rerate utility is run with -r parameter to indicate selective rerating.

Note:

An alternative to customizing this policy opcode to filter the events selected for rerating is to create custom pin_rerate parameters instead. See "Defining Custom pin_rerate Parameters for Rerating".

PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE receives an event search template that is based on the account and event selection criteria specified in the pin_rerate command line: for example, to select events related to services specified by the -s parameter.

By default, PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE does not change the search template and returns a copy of the input flist in the output flist.

You can customize the search template in the input flist to rerate specific types of events. Most customizations include changes only to the fields listed in Table 30-1:

Table 30-1 Fields to Customize

Field Description

PIN_FLD_TEMPLATE

The modified search template.

PIN_FLD_ARGS

The list of search arguments.

Note:

  • This list must match the list of arguments in PIN_FLD_TEMPLATE.

  • It is preferable to have arguments of one type only. For example, an event search based on product objects.

The PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE policy opcode receives the following fields in the RESULTS array from the PCM_OP_SUBSCRIPTION_RERATE_REBILL standard opcode:

  • PIN_FLD_POID

  • PIN_FLD_CREATED_T

  • PIN_FLD_EFFECTIVE_T

  • PIN_FLD_END_T

  • PIN_FLD_SERVICE_OBJ

  • PIN_FLD_ACCOUNT_OBJ

  • PIN_FLD_UNRATED_QUANTITY

  • PIN_FLD_RERATE_OBJ

  • PIN_FLD_BAL_IMPACTS [*]

  • PIN_FLD_SUB_BAL_IMPACTS [*]

    Important:

    • To assure that the existing mandatory fields in the array are passed back, avoid customizing the RESULTS array. Extra fields added to the array are retrieved but ignored by the standard opcode.

    • Test your customized template to ensure that it works properly before using it with a working database. Use the -e and -c parameters with the pin_rerate utility to test your modifications. See "pin_rerate".

The PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE policy opcode returns the search template that the PCM_OP_SUBSCRIPTION_RERATE_REBILL opcode uses to find events in selected accounts that need rerating.

Specifying the Event Sequence for Rerating

Events are rerated in sequence based on the event time. You can specify one of two times:

  • Event end time defines the time that the usage actually occurred. This is the default.

  • Event creation time is the time that the event was loaded into the BRM database.

The event time you specify might depend on how the original events were rated:

  • Events rated or loaded in batches

    Events that are rated or loaded into the BRM database in batches have a significant delay between the event end time and creation time. Using the event end time reflects the actual real-time sequence of the original events. However, because batch events are recorded in order of creation time, this makes predicting the actual impact of a price configuration change harder. To compare the original and rerated balance impacts of batch events, use the event creation time.

  • Events rated and loaded in real time

    Events that are rated and loaded in real-time have very little delay between the event end time and creation time. Both the event end time and creation time reflect the real-time sequence in which the original events occurred and were recorded.

By default, the pin_rerate utility rerates batch events in sequence based on event end time for both real-time and batch events.

To specify the event time for rerating, use the -b parameter when selecting accounts for rerating. The -b parameter takes either the c option (for event creation time) or the e option (for event end time).

For example:

pin_rerate -b c -t 07/23/2007

The preceding example selects all accounts, then selects both real-time and batch events that occurred after 07/23/2007 for the selected accounts, and finally rerates the events in order of creation time.

For a list of the pin_rerate parameters, see "pin_rerate".

Assigning Rerate Reasons to Rerate Jobs

Some rerating jobs must be processed before others. For example, if a rerate job includes events that have an impact on future rating, such as volume-based discounting, those events must be rerated first. You can achieve this by assigning rerate reason codes to rerate jobs when you create those jobs. You can then select only those jobs associated with the specified rerate reason code during scheduled rerating executions.

Rerate reason codes can be any integer except 1 (1 is reserved for pipeline-generated events that were rated out of order).

Important:

Ensure that your reason codes are unique to process rerate jobs associated with them during separate rerating executions.

You assign rerate reason codes when you manually create rerate jobs by using the pin_rerate utility.

Note:

Rerate jobs created automatically by BRM automatic rerating features are not assigned a reason code by default. You can assign rerate reason codes for trigger-dependent and automatic rerating by customizing the PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST policy opcode. For more information, see the following sections:

You can assign a unique reason code for out-of-order rerating by using a configuration file. See "Specifying a Reason Code for Rerating Out-of-Order Events".

To assign a rerate reason code by using pin_rerate, you specify the rerate reason code on the command line along with other account selection parameters, such as the start time and other parameters:

pin_rerate -reason reason_code -t start_time other_parameters

You can specify only one reason code when creating rerate jobs. Rerate jobs are created for the selected accounts and all rerate jobs are assigned the specified rerate reason code.

For example, to assign a rerate reason code of 99 to rerate jobs that rerate all account's events that occurred after January 1, 2007 and that are associated with the products specified in the product.txt file, you enter the following command:

pin_rerate -reason 99 -t 01/01/2007 -p product.txt

For more information, see "pin_rerate".

To process rerate jobs according to the rerate reason code, see the following sections:

Defining Custom pin_rerate Parameters for Rerating

You can define custom pin_rerate parameters based on any event criteria. This enables you to customize which event attributes are used to select accounts and events for rerating.

To define custom parameters, you map extraction keys to fields in the event object. You then run the load_pin_rerate_flds utility to load the extraction-key-to-event-field mappings into the /config/rerate_flds object in the BRM database. See "Configuring Custom pin_rerate Parameters".

When you run pin_rerate, it uses the extraction key to find the corresponding event field name in the /config/rerate_flds object. It uses the event field name to find and retrieve accounts and events for rerating.

For example, if you map the extraction key resource_id to the PIN_FLD_RESOURCE_ID field in the /event object, you can run pin_rerate with the following command, specifying the input file containing the resource IDs:

pin_rerate -resource_id input_file -t start_time

In this example, pin_rerate selects accounts to be rerated that have events associated with the resources specified in the input file.

By default, BRM searches only the base /event class for fields associated with custom pin_rerate parameters. If the event field associated with a custom parameter is present only in a subclass, you must specify the subclass event type in the command line by including the -n parameter.

Important:

When used with custom pin_rerate parameters, the input file for the -n parameter can contain only one event type. If you specify more than one event type, an error is returned.

Configuring Custom pin_rerate Parameters

To configure custom pin_rerate parameters, you perform the following tasks:

Defining Custom Parameters

To define custom pin_rerate parameters, create an XML file that maps the parameters to event fields. You can map to fields specified in the EVENT_T and EVENT_BAL_IMPACTS_T tables in the base /event class or to fields in an event subclass.

Note:

  • If you map parameters to fields in an /event subclass, you must specify the subclass by using the -n parameter when you run pin_rerate with the custom parameter.

  • To create the XML file, you must be familiar with XML and the XML schema.

Create an XML file containing the parameter-to-event field mappings according to the BRM rerating XML schema file (BRM_home/xsd/pin_rerate_flds.xsd).

Important:

Validate your XML file against the XML schema. The load_pin_rerate_flds utility cannot successfully load an invalid XML file.

Sample XML parameter file

The following example shows how you specify event fields in <Name> tags and the parameters they map to in <value> tags:

<PinRerateList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/InfranetXMLSchema pin_rerate_flds.xsd">
     <PinRerate> 
          <Name>EVENT.PIN_FLD_START_T </Name>
          <value>startTime</value>
     </PinRerate>
     <PinRerate> 
          <Name>EVENT.PIN_FLD_END_T</Name>
          <value>endTime</value>
     </PinRerate>
     <PinRerate>
          <Name>EVENT.PIN_FLD_ACCOUNT_OBJ</Name>
          <value>account</value>
     </PinRerate>
     <PinRerate> 
          <Name>EVENT.PIN_FLD_RATE_PLAN </Name>
          <value>ratePlan</value>
     </PinRerate>
     <PinRerate> 
          <Name>EVENT.PIN_FLD_DEAL </Name>
          <value>deal</value>
     </PinRerate>
     <PinRerate> 
          <Name>EVENT.PIN_FLD_SERVICE_OBJ </Name>
          <value>service</value>
     </PinRerate>
     <PinRerate> 
          <Name>EVENT.PIN_FLD_BAL_IMPACTS.PIN_FLD_PRODUCT_OBJ</Name>
          <value>product</value>
     </PinRerate>
</PinRerateList>

If you map a custom parameter to a field in an /event subclass, specify the array or substruct (if any) that contains the parameter field.

For example, to specify PIN_FLD_ORIGIN_NETWORK, which is located in the PIN_FLD_TELCO_INFO substruct in the /event/delayed/session/telco subclass:

<PinRerate>
<Name>EVENT.PIN_FLD_TELCO_INFO.PIN_FLD_ORIGIN_NETWORK</Name>
<value>origin_network</value>. 
</PinRerate>

Loading Custom Parameters

Use the following command to load the custom pin_rerate parameters defined in the XML file into the /config/rerate_fld object:

BRM_home/sys/data/config/load_pin_rerate_flds xml_file_name

Important:

The load_pin_rerate_flds utility uses a configuration file (pin.conf) located in the same directory to connect to the BRM database. Edit the configuration file to connect to your BRM database.

For more information, see "load_pin_rerate_flds".

About Processing Rerate Jobs Created by Automatic Rerating

Rerate jobs are created automatically by the following features:

These rerate jobs are automatically processed when you run the pin_rerate with one of the following parameters:

  • The -process jobs parameter when rerating real-time-rated and pipeline-rated events concurrently.

  • The -rerate parameter when rerating only real-time-rated if you do not use Pipeline Manager for batch rating.

By default, rerate jobs that are automatically created are not assigned a rerate reason code. If you customize automatic rerating to assign a specific rerate reason code to rerate jobs, you process those jobs by using the -reason parameter with the -process jobs or -rerate parameter.

For more information, see the following sections:

Rerating Real-Time-Rated and Pipeline-Rated Events Concurrently

When rerating real-time-rated and pipeline-rated events concurrently, you process rerate jobs in the following ways:

Processing Rerate Jobs for Concurrent Rerating

When rerating real-time-rated and pipeline-batch-rated events concurrently, rerate jobs are created and processed in separate commands. Rerate jobs can be created in the following ways:

  • Automatically by BRM automatic rerating features.

  • When you run pin_rerate to select accounts for rerating, as described in "Selecting Accounts and Events for Rerating". For example:

    pin_rerate -t start_time -s input_file

To process all existing rerate jobs in the rerate queue, run the following commands:

  1. pin_rerate -process jobs. See "Notifying the Batch Pipeline That Rerating Is Starting".

  2. pin_rerate -process queue. See "Processing Acknowledgment Events from the Batch Pipeline".

  3. pin_rerate -rerate. See "Rerating the Events Associated with the Accounts in Rerate Jobs".

  4. pin_rerate -process queue. See "Processing Acknowledgment Events from the Batch Pipeline".

  5. pin_rerate -process recycle. See "Recycling EDRs Suspended during Rerating".

For example:

pin_rerate -process jobs
pin_rerate -process queue
pin_rerate -rerate
pin_rerate -process queue
pin_rerate -process recycle

Note:

You run pin_rerate during non-peak hours with these commands as part of a cron job. See your operating system documentation for details on creating a cron job.

Notifying the Batch Pipeline That Rerating Is Starting

After rerate jobs are created, you run pin_rerate with the -process jobs parameter to notify the batch pipeline that rerating is about to begin.

When you specify the -process jobs parameter, the following actions are performed:

  1. The pin_rerate utility finds all the rerate jobs with a status of NEW and sends business events containing the rerate job ID and the list of accounts associated with the rerate job to the batch pipeline.

  2. The pin_rerate utility then changes the status of the jobs from NEW to WAITING_ACCOUNT_LOCKED to indicate that it is waiting for an acknowledgment from the pipeline.

  3. The batch pipeline dequeues the business events and suspends rating EDRs for those accounts. See "About Suspending and Recycling EDRs during the Rerating Process".

  4. The batch pipeline sends an acknowledgment event back to the Account Synchronization database queue.

    Note:

Processing Acknowledgment Events from the Batch Pipeline

You run pin_rerate with the -process queue parameter to process acknowledgment events sent by the batch pipeline.

You run pin_rerate with the -process queue parameter at two times:

  • After you run pin_rerate with the -process jobs parameter. The acknowledgment event at this time indicates that the batch pipeline has suspended rating EDRs for the accounts in the rerate jobs. The pin_rerate utility dequeues the event and changes the status of the rerate jobs from WAITING_ACCOUNT_LOCKED to ACCOUNT_LOCKED.

  • After you run pin_rerate with the -rerate parameter. The acknowledgment event at this time indicates that the batch pipeline has resumed rating EDRs for the accounts in the rerate job. pin_rerate dequeues the event and changes the status of the rerate jobs from RERATED to READY_FOR_RECYCLE.

Rerating the Events Associated with the Accounts in Rerate Jobs

When the rerate jobs has the ACCOUNT_LOCKED status, you run pin_rerate with the -rerate parameter to rerate the accounts.

pin_rerate finds all the rerate jobs with a status of ACCOUNT_LOCKED and calls rerating opcodes to rerate the accounts.

After an account is successfully rerated, pin_rerate sends a business event through the Account Synchronization Data Manager (DM) to the batch pipeline to update the account data. The DAT_BalanceBatch module processes the event and reloads the updated account balances from the BRM database.

When all the accounts in a rerate job have been successfully rerated and updated, pin_rerate updates the rerate job status from ACCOUNT_LOCKED to RERATED and then notifies the batch pipeline that rerating is complete. The batch pipeline resets the rerate flags for all the accounts in the rerate job and returns an acknowledgment event to inform pin_rerate that it has resumed rating EDRs for those accounts.

Recycling EDRs Suspended during Rerating

EDRs that are temporarily suspended by the batch pipeline are loaded into the BRM database by Suspended Event (SE) Loader. The suspended EDRs are stored in the database until they are recycled.

Important:

Before you can recycle suspended EDRs, they must be loaded into the BRM database by SE Loader. You typically schedule SE Loader to run automatically when you set up standard recycling.

To recycle the EDRs that were suspended during the rerating process, you run pin_rerate with the -process recycle parameter.

Note:

Suspended EDRs are typically recycled by running the pin_recycle utility. However, pin_rerate calls the standard recycling opcode directly so you do not use pin_recycle when using pin_rerate.

pin_rerate finds all the rerate jobs with a status of READY_FOR_RECYCLE and calls the standard recycling opcodes to recycle the associated EDRs. Standard recycling uses the recycle key value in the EDR to identify and retrieve the EDRs that were suspended during the rerating process.

After the EDRs are recycled, pin_rerate changes the status of the jobs from READY_FOR_RECYCLE to COMPLETE.

Note:

  • In a multischema environment, you must run pin_rerate separately on each database schema.

  • If no EDRs were suspended for the accounts being rerated, the job status is still changed to COMPLETE.

  • If an error occurs while recycling EDRs, the job status is not changed; it retains the status of READY_FOR_RECYCLE.

Processing Rerate Jobs According to a Rerate Reason Code for Concurrent Rerating

To process rerate jobs according to a rerate reason code when rerating real-time-rated and pipeline-batch-rated events concurrently, you use the -process jobs parameter with the -reason parameter:

pin_rerate -process jobs -reason [reason_code_1,reason_code_2,reason_code_3,...]

where reason_code_x is the rerate reason code assigned to existing rerate jobs in one of the following ways:

You can list multiple reason codes separated by commas (do not use spaces between reason codes). For example, to process jobs with reason codes 100, 200, and 300, enter the following commands:

pin_rerate -process jobs –reason 100,200,300
pin_rerate -process queue
pin_rerate -rerate
pin_rerate -process queue
pin_rerate -process recycle

Important:

When you list multiple rerate reasons, the rerate jobs associated with them are processed randomly. They are not processed in the order you list them in the command line, nor are they processed in increasing or decreasing numeric order. To process rerate jobs according to a rerate reason in a particular order, you must schedule separate rerating executions for them.

Processing Rerate Jobs When You Do Not Use Pipeline Batch Rating

If you do not use Pipeline Manager for batch rating, you process rerate jobs in the following ways:

Processing Rerate Jobs When Selecting Accounts for Rerating

When rerating real-time events only, rerate jobs are processed when you run pin_rerate and specify the start time and any additional search criteria as described in "Selecting Accounts and Events for Rerating".

For example:

pin_rerate -t start_time -p input_file

The pin_rerate utility selects the accounts for rerating by using the search criteria, creates rerate jobs, and then immediately rerates the selected accounts.

Processing Existing Rerate Jobs

Some rerate jobs are automatically created by BRM automatic rerating features. Other rerate jobs can be precreated by assigning a rerate reason code when selecting the accounts for rerating.

To process all existing rerate jobs in the rerate queue, you use only the -rerate parameter:

pin_rerate -rerate

Processing Rerate Jobs per a Rerate Reason When Rerating Only Real-Time-Rated Events

To process rerate jobs according to a rerate reason when rerating only real-time-rated events, you use the -rerate parameter with the -reason parameter:

pin_rerate -rerate -reason reason_code_1,reason_code_2,reason_code_3,...

where reason_code_x is the rerate reason code assigned to existing rerate jobs in one of the following ways:

You can list multiple reason codes separated by commas (do not use spaces between reason codes). For example, to process jobs with reason codes 100, 200, and 300, you enter the following commands:

pin_rerate -rerate –reason 100,200,300

Important:

When you list multiple rerate reasons, the rerate jobs associated with them are processed randomly. They are not processed in the order you list them in the command line, nor are they processed in increasing or decreasing numeric order. To process rerate jobs according to a rerate reason in a particular order, you must schedule separate rerating executions for them.

Processing Failed Rerate Jobs

To process failed rerate jobs, you run pin_rerate only with the commands for processing rerate jobs, without specifying selection criteria or rerate reason codes.

Note:

This also processes all rerate jobs that are in the rerate queue: not only failed rerate jobs.

For example:

For more information, see "How Failed Rerate Jobs Are Processed".

Using pin_rerate for Back-Out-Only Rerating

Back-out-only rerating backs out the balance impacts of rating without rerating events.

BRM backs out balance impacts for back-out-only rerating by creating an adjustment event that fully negates the original balance impacts. See "How BRM Applies the Balance Impacts of Rerating".

To back out the balance impacts of rating, run pin_rerate with the -backout parameter. Use the -backout parameter with other parameters that select the accounts and their events for rerating. This creates rerate jobs that are set for back-out-only rerating for the selected accounts.

For example, the following command selects accounts whose events were rated by the products specified in the products.txt file and backs out those events rated by the products that occurred after 06/01/2007:

pin_rerate -backout -r -p products.txt -t 06/01/2007

The -r parameter is used to select only the events that used the specified products. Without the -r parameter, pin_rerate would select accounts whose events used the specified products and then back out all events for those accounts.

Note:

Use caution when choosing the events to back out because it can impact your general ledger. For example, it is incorrect to use back-out-only rerating for a cycle event when the customer has already paid the cycle fee or to use back-out-only rerating when product pricing is changed. Typically, back-out-only rerating is performed only on usage events where rating should not have occurred.

Using Custom pin_rerate Parameters with Back-Out-Only Rerating

You can perform back-out-only rerating using custom pin_rerate parameters. This enables you to select events for back-out-only rerating based on any event criteria.

For information about defining custom pin_rerate parameters, see "Defining Custom pin_rerate Parameters for Rerating".

By default, rerating searches only the base /event storable class for fields associated with custom pin_rerate parameters. If the event field associated with a custom parameter is present only in a subclass, you must also specify the subclass event type in the command line by using the -n input_file parameter.

If the event type specified in the -n parameter input file has subclasses, all subclass events are also backed out, providing they meet the selection criteria. For example, if you specify /event/delayed/session/telco in the -n parameter input file, events of type /event/delayed/session/telco/gsm that meet the selection criteria are also backed out.

Example of Using a Custom Parameter with Back-Out-Only Rerating

Suppose you define the custom parameter origin_network to select events based on the PIN_FLD_ORIGIN_NETWORK field. You specify an origin network ID in a file named origin_network.txt.

The PIN_FLD_ORIGIN_NETWORK field is located in the /event/delayed/session/telco subclass so you specify this subclass, in a file named event_subclass.txt.

To select accounts whose events were generated by the specified origin network and back out the balance impacts of only those events when they occurred after 06/01/2007, run the following command:

pin_rerate -backout -r -n event_subclass.txt -origin_network origin_network.txt -t 06/01/2007

Reports Generated by the pin_rerate Utility

By default, the rerating process generates summary and detailed reports. To print a report, use the pin_rerate -l parameter. You have the option of printing either a summary of the report, a detailed report, or both summary and detailed reports. If you do not specify which report to print, both summary and detailed reports are printed by default.

You set the reporting parameter as follows:

  • When rerating both real-time-rated and pipeline-batch-rated events concurrently, you specify the -l parameter with the -rerate parameter. In the following example, the report option is set to print a summary report:

    pin_rerate -t 01/01/2007 -s service.txt 
pin_rerate -process jobs
pin_rerate -process queue
pin_rerate -rerate -l s
pin_rerate -process queue
pin_rerate -process recycle

    Important:

    When the batch pipeline is enabled, you cannot specify the report option at rerate job creation time.

  • If you do not use Pipeline Manager for batch rating, you specify the -l parameter at one of the following times:

    • When specifying the accounts to rerate. Enter the -l parameter after the parameters used to select the accounts. In the following example, the report option is set to print a detailed report:

      pin_rerate -t 01/01/2007 -p product.txt -l d

    • When processing rerate jobs that already exist, such as those created with a rerate reason code and those created by automatic rerating. Specify the -l parameter with the -rerate parameter. In the following example, the report option is set to print a summary report:

      pin_rerate -rerate -l s

      Important:

      Report generation is resource intensive and can degrade system performance, depending on system load and the number of events rerated. You can override report generation by using the -l n option with -rerate to skip printing reports. For example: pin_rerate -rerate -l n

Report Generated When Rerating Is Performed before Billing

Summary reports are created for each account. The following example of a summary report shows that rerating occurred as a result of changing the monthly cycle forward fee from $200 to $20. Rerating took place before billing was run, so the difference is shown in the current bill.

                PIN_RERATE SUMMARY REPORT
       ==========================================

Date Range: 3/1/2007 10:0:0 to 3/2/2007 20:4:49
-------------------------------

Account: 0.0.0.1 /account 13640 0
Resource Name   Original Amount      New Amount      Difference
US Dollar       200.000000           20.000000       -180.000000
Total Resources 200.000000           20.000000       -180.000000
-------------------------------

+++++++++++++++++++++++++++++++++++++
The Total Rerate Impact:
+++++++++++++++++++++++++++++++++++++
Resource Name   Original Amount      New Amount      Difference
US Dollar       200.000000           20.000000       -180.000000
Total Resources 200.000000           20.000000       -180.000000
-----------------------------------------------
END OF REPORT
==================================================================

The following is the detailed report for the example above.

                PIN_RERATE DETAILED REPORT
        ==========================================

Date Range: 3/1/2007 10:0:0 to 3/2/2007 20:4:49

Event: 0.0.0.1 /event/billing/product/fee/cycle/cycle_forward_monthly 219550481834327128 0
Service Type:   /service/ip
Event Time:     3/1/2007 20:4:14
----------
O/N       Resource    Amount       Disct     GL_ID       Tax
Original  US Dollar   -200.000000  0.000      102        0.000000
New       US Dollar    20.000000   0.000      102        0.000000
-----------------------------------------
Account: 0.0.0.1 /account 13640 0
Resource Name    Original Amount      New Amount      Difference
US Dollar        200.000000           20.000000       -180.000000
Total Resources  200.000000           20.000000       -180.000000
-------------------------------

+++++++++++++++++++++++++++++++++++++
The Total Rerate Impact:
+++++++++++++++++++++++++++++++++++++
Resource Name     Original Amount      New Amount      Difference
US Dollar         200.000000           20.000000       -180.000000
Total Resources   200.000000           20.000000       -180.000000
-----------------------------------------------
END OF REPORT

Report Generated When Rerating Is Performed after Billing

The following example of a summary report shows rerating as a result of changing the monthly cycle forward fee from $200 to $20. Rerating took place after billing was run, so the difference is posted in the next bill.

Adjustments are posted only for cycle forward fees. Since cycle forward fees are charged in advance and since the difference between the old and the new amount in this case is $180, the new amount is calculated as -360. In this case, the reports show only the adjusted amount.

                PIN_RERATE SUMMARY REPORT
        ==========================================

Date Range: 8/7/2007 10:0:0 to 9/7/2007 20:6:52

-------------------------------
Account: 0.0.0.1 /account 14854 0
Resource Name     Original Amount      New Amount      Difference
US Dollar         0.000000             -360.000000     -360.000000
Total Resources   0.000000             -360.000000     -360.000000
-------------------------------

+++++++++++++++++++++++++++++++++++++
The Total Rerate Impact:
+++++++++++++++++++++++++++++++++++++
Resource Name      Original Amount      New Amount     Difference
US Dollar          0.000000             -360.000000    -360.000000
Total Resources    0.000000             -360.000000    -360.000000
-----------------------------------------------
END OF REPORT

The following is a detailed report of the example above:

                 PIN_RERATE DETAILED REPORT
        ==========================================

Date Range: 8/7/2007 10:0:0 to 9/7/2007 20:6:52


Event:0.0.0.1 /event/billing/adjustment/event 222875404996720238 0
Adjusted From:0.0.0.1 /event/billing/product/fee/cycle/cycle_forward_monthly 222330047229342470 0
Service Type:   /service/ip
Event Time:     9/7/2007 20:6:54
----------
Resource      Amount         Disct     GL_ID
US Dollar     -180.000000    0.000     102
----------

Event:0.0.0.1 /event/billing/adjustment/event 222875404996721006 0
Adjusted From:  0.0.0.1 /event/billing/product/fee/cycle/cycle_forward_monthly 222875404996719270 0
Service Type:   /service/ip
Event Time:     9/7/2007 20:6:54
----------
Resource          Amount         Disct     GL_ID
US Dollar         -180.000000    0.000     102
-----------------------------------------
Account: 0.0.0.1 /account 14854 0
Resource Name     Original Amount      New Amount      Difference
US Dollar         0.000000             -360.000000     -360.000000
Total Resources   0.000000             -360.000000     -360.000000
-------------------------------

+++++++++++++++++++++++++++++++++++++
The Total Rerate Impact:
+++++++++++++++++++++++++++++++++++++
Resource Name     Original Amount      New Amount      Difference
US Dollar         0.000000             -360.000000     -360.000000
Total Resources   0.000000             -360.000000     -360.000000
-----------------------------------------------
END OF REPORT

Improving pin_rerate Performance

The following parameters can be used with pin_rerate to improve performance:

- pin_rerate  rerate_children  5 
- pin_rerate  rerate_per_step  1000 
- pin_rerate  rerate_fetch_size  5000