Rerating Utilities

7 Rerating Utilities

Learn about the syntax and parameters for the Oracle Communications Billing and Revenue Management (BRM) rerating utilities.

Topics in this document:

load_pin_rerate_flds

Use this utility to load the following information into the BRM database:

Custom event selection parameters. The data is loaded into the /config/rerate_flds object. See "Selecting Events Based on a Custom Event Field".
Balance-impact comparison fields that determine if an adjustment event must be created. The data is loaded into the /config/rerate_flds/compare_bi object. See "Configuring Rerating Adjustment Events".

Location

BRM_home/sys/data/config

Run load_pin_rerate_flds from this directory.

Syntax

load_pin_rerate_flds -f xml_file_name [-v] [-h]

Parameters

-f xml_file_name: Specifies the name of the XML file that contains the data.

Note:

The file you load cannot include both event selection data and balance-impact comparison data. You must load the files for these configurations separately.
-verbose: Displays information about successful or failed processing as the utility runs.

Note:

This parameter is always used with other parameters and commands. It is not position dependent. For example, you can enter -verbose at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file:

load_pin_rerate_flds any_other_parameter –v > filename.log
-help: Displays the syntax and parameters for this utility.

Results

This utility notifies you when it successfully creates the /config/rerate_flds object.

If it cannot create the /config/rerate_flds, it logs an error in the log file (default.pinlog). It creates the log file either in the directory from which the utility was started or in the directory specified in the configuration file.

pin_rate_change

Use this utility to create rerate jobs for cycle forward and cycle forward arrears events when the pricing changes. Use this BRM utility after you change pricing in PDC and before running the pin_rerate utility.

See "Creating Rerate Jobs for Cycle Forward and Cycle Forward Arrears Charges".

The pin.conf file for this utility is in BRM_home/apps/pin_rate_change.

Location

BRM_home/bin

Syntax

pin_rate_change [-v] [-d] [-h]

Parameters

-v: Displays information about successful or failed processing as the utility runs.

Note:

This parameter is not position dependent. For example, you can enter -v at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file:

pin_rate_change any_other_parameter –v > filename.log
-d: Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors, but the data has not been loaded into the database.
-h: Displays the syntax and parameters for this utility.

Results

The pin_rate_change utility notifies you when it successfully creates the rerate jobs

If the pin_rate_change utility does not notify you that it was successful, run the command again with the -d parameter, and look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.

pin_rerate

Use this BRM utility to rerate events. See "About Rerating Events".

To rerate events, you run the pin_rerate utility multiple times: once to create rerating jobs and several additional times to process the rerate jobs.

Note:

pin_rerate is a multithreaded application (MTA).
In a multischema environment, you must run pin_rerate separately on each database schema.

Location

BRM_home/bin

The pin.conf file for this utility is located in BRM_home/apps/pin_rerate. Run pin_rerate from this directory.

Syntax Overview

You can run the pin_rerate utility in the following modes:

Select mode: Select events for rerating and bundles them into a rerate job. See "Rerate Job Creation Options".
Process mode: Processes the rerate jobs. See "Rerate Job Processing Parameters".
Configuration mode: Provides additional options when rerating jobs. See "Rerate Job Configuration Options".

Results

If the pin_rerate utility does not notify you that it was successful, look in the utility log file (pin_rerate.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.

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

Rerate Job Creation Options

When you run the pin_rerate utility with the job creation options, it finds the events to rerate and bundles them into a rerate job. See "About Manually Selecting Events for Rerate Jobs".

Syntax for Creating Rerate Jobs

pin_rerate  -a accountPOID  [-c]
            -t timestamp
            -G groupOwnerPoid -t timestamp
            -p|-i|-s|-d|-n|-m|-g|-fieldName inputFile -t timestamp [-r] [-e]
            -line subscriptionID -t timestamp
            [-reason reason_code]

Parameters for Selecting Accounts for Rerating

All account selection parameters are optional and mutually exclusive, except for the -t parameter, which is mandatory when selecting the events to rerate. If you specify only the time (-t) parameter, BRM selects all accounts for rerating in the period defined by the -t parameter.

-a accountPOID [-c]

Includes the events associated with the specified account POID in the rerate job.

You can also include the -c option to rerate in calculate only mode. The utility rerates the events without updating the database.

-t timestamp: Selects accounts for rerating based on the event start time. All accounts with events that occurred between the start time and the current date are included in the rerate job.

-G groupOwnerPoid -t timestamp

Selects accounts for rerating based on the specified sharing group owner. The owner account and all member accounts of the specified charge sharing group, discount sharing group, profile sharing group, or product sharing group are included in the rerate job.

All accounts with events that occurred between the start time and the current date are included in the rerate job.

By default, the owner and all members of the sharing group must reside in the same database schema. To rerate sharing groups with accounts in multiple schemas, you must set the CrossSchemaSharingGroup business parameter. See "Enabling Sharing Groups to Support Multiple Schemas" in BRM Managing Customers for more information.

Note:

This job option does not support multilevel sharing group hierarchies. Only the owner and its immediate children are included in the job.

-p inputFile -t timestamp

Selects accounts for rerating based on the charge offers listed in the input file. Accounts that have events associated with the charge offers specified in inputFile are included in the rerate job.

In the input file, include a line for each charge offer name. All names are case sensitive.

-i inputFile -t timestamp

Selects accounts for rerating based on the discount offers listed in the input file. Accounts that own at least one instance of the discount offer specified in inputFile are included in the rerate job.

In the input file, include a line for each discount offer name. All names are case sensitive.

-s inputFile -t timestamp

Selects accounts for rerating based on the service names listed in the input file. Accounts that have events associated with the services specified in inputFile are included in the rerate job.

In the input file, include a line for each service name. All names are case sensitive.

-d inputFile -t timestamp

Includes in the rerate job all events associated with the bundles listed in the input file. Accounts that have events associated with the charge offers and discount offers that belong to the bundles specified in inputFile are selected for rerating.

In the input file, include a line for each bundle name. Names are case sensitive.

Note:

If a charge offer is a part of multiple bundles, all accounts that purchase the charge offer are selected for rerating even if they did not purchase the bundle that was rerated.

-n inputFile -t timestamp

Selects accounts for rerating based on the types of events. Accounts that have events of the types specified in inputFile are selected for rerating.

In the input file, include a line for each bundle name. Names are case sensitive.

Note:

If you use this parameter with the -r parameter, all subclasses of the event specified in the input file are also rerated. See "Selecting Events for Rerate Jobs".
When a custom pin_rerate parameter is used, the -n parameter is mandatory if the custom parameter is based on an event field present only in an event subclass. In this case, the -n parameter input file can contain only one type of event.

-m inputFile -t timestamp

Selects a set of accounts for rerating based on the provided account POIDs.

inputFile format: A text file containing the accounts to rerate in flist format. Specify each account in a results array. For example:

0 PIN_FLD_RESULTS                   ARRAY [1]
    1 PIN_FLD_ACCOUNT_OBJ            POID [0] $DB_NO /account 12345 0
0 PIN_FLD_RESULTS                   ARRAY [2]
    1 PIN_FLD_ACCOUNT_OBJ            POID [0] $DB_NO /account 12333 0
...

where PIN_FLD_ACCOUNT_OBJ is the POID of the account object.

You cannot use this parameter with the -a, -d, -g, -i, -n, -p, or -s -e, -line, or field_name parameters.

-g inputFile -t timestamp

Selects accounts for rerating based on balance groups.

inputFile format: A text file containing information for one or more accounts in flist format. Specify an account POID, bill unit POID, and balance group POID in a results array for each account. For example:

0 PIN_FLD_RESULTS                  ARRAY [1]
    1  PIN_FLD_ACCOUNT_OBJ          POID [0] $DB_NO /account 12345 0
    1  PIN_FLD_BILLINFO_OBJ         POID [0] $DB_NO /billinfo 34567 0
    1  PIN_FLD_BAL_GRP_OBJ          POID [0] $DB_NO /balance_group 66765 0
0 PIN_FLD_RESULTS                  ARRAY [1]
    1  PIN_FLD_ACCOUNT_OBJ          POID [0] $DB_NO /account 12344 0
    1  PIN_FLD_BILLINFO_OBJ         POID [0] $DB_NO /billinfo 45654 0
    1  PIN_FLD_BAL_GRP_OBJ          POID [0] $DB_NO /balance_group NULL 0
...

To rerate all events for all balance groups for a given account's bill unit, specify a value of NULL as the POID ID for the balance group object, as shown in the second results array in the above example.

-fieldName inputFile -t timestamp

field_name is a custom pin_rerate parameter you have defined that maps to a specific event field.

inputFile is a file that contains the values of the event field used to select accounts for rerating.

Selects accounts based on the custom parameter. Accounts are selected for rerating that have events with the field identified by field_name whose field value is one of those specified in inputFile.

For information about defining custom pin_rerate parameters, see "Selecting Events Based on a Custom Event Field".

Note:

If the custom parameter maps to a field in an /event subclass, you must specify the subclass event by including the -n parameter, and the -n parameter input file can include only one event. If you specify more than one type of event, an error is returned.

-line subscriptionID: Selects accounts for rerating based on a subscription service. The subscription service is identified by the PIN_FLD_ALIAS_LIST.PIN_FLD_NAME field, which can specify, for example, the caller ID such as a phone number or the MAC address.

-reason reasonCode

Use with other selection parameters to assign a rerate reason code to the jobs created for the selected accounts.

For more information about assigning rerate reason codes, see "Specifying the Order to Process Rerate Jobs".

-r

Specifies to rerate all subclasses of the event specified in the input file.

You can use the -e parameter with the -p, -i, -s, -d, -n, -m, -g, and -fieldName parameters.

-e

Displays an estimated number of events that will be rerated to the screen without loading any data into the database. It also writes the estimate to the pin_rerate.pinlog file.

You can use the -e parameter with the -p, -i, -s, -d, -n, and -fieldName parameters.

Rerate Job Processing Parameters

When you run the pin_rerate utility with the job processing parameters, it processes the rerate jobs in the queue. For more information, see "Steps for Processing Rerate Jobs".

Syntax for Processing Rerate Jobs

pin_rerate    -process jobs [-reason reasonCode]
              -process queue
              -process recycle [-db databaseID]
              -rerate [-l [d | s | sd | n]]
              -purge [-time timestamp]

Parameters for Processing Rerate Jobs

All parameters are optional and mutually exclusive.

-process jobs [-reason reasonCode]

Searches for all jobs with a NEW status, sends the list of accounts associated with the job to ECE to lock the accounts, and then sets the job's status to WAITING_ACCOUNT_LOCK.

Include the optional -reason reasonCode option to process only jobs associated with the specified reason codes. Replace reasonCode with a comma-separated list of reason codes. See "Specifying the Order to Process Rerate Jobs" for more information.

-process queue

Processes acknowledgment events from ECE and then updates the job's status to ACCOUNT_LOCKED.

When processing rerate jobs, you run pin_rerate -process queue twice: once before running utility with the -rerate parameter and again after running the utility with the -rerate parameter.

-process recycle [-db databaseID]

Recycles event records that were suspended during the rerating process and then changes the job's status to COMPLETED. By default, it recycles event records from the current database schema.

To recycle suspended event records residing in a different schema, include the -db databaseID option with the database number (for example, 0.0.0.2).

-rerate -l [d | s | sd | n]

Rerates the events in the job, releases the lock on all accounts associated with the job, and then changes the job's status to RERATED.

If you include the -l parameter, it also generates a detailed rerating report and summary rerating report. To change which reports are generated, use the following:

-ld: Generates a detailed rerating report (pin_rerate.detail) only.
-ls: Generates a summary rerating report (pin_rerate.summary) only.
-lsd: Generates both the detailed and summary rerating reports. This is the default.
-ln: Generates no report.

-purge [-t timestamp]: Purges all rerate jobs with a status of COMPLETED or UNSUCCESSFUL. Also include the -t timestamp option to purge completed and unsuccessful jobs created before the specified time in [ss/mm/hh/]MM/DD/YYYY format.

Rerate Job Configuration Options

When you run the pin_rerate utility with the job processing parameters, it processes rerate jobs. For more information, see "Steps for Processing Rerate Jobs".

Syntax for Processing Rerate Jobs

pin_rerate    [-b [c | e]] [-e  -a | -s | -p | -n | -d] [-backout] [-help]

Parameters Affecting Rerating Behavior

The following are additional, optional parameters that affect rerating behavior and the utility's output.

-b [ c | e ]

Specifies the order in which batch events are rerated based on the event time. You can specify one of two times:

-bc: Rerates events in the order that they were loaded into the BRM database.
-be: Rerates events based on the time the event occurred. This is the default.

See "Specifying the Event Sequence in a Rerate Job" for more information.

-e -a | -s | -p | -n | -d

Returns an estimate of how many events might be affected by rerating based on which accounts are being rerated:

-e -a: Provides an estimate for a single account.
-e -s: Provides an estimate for accounts associated with a specific service.
-e -p: Provides an estimate for accounts that own with specific charge offers.
-e -n: Provides an estimate for accounts with specific types of events.
-e -d: Provides an estimate for accounts that own specific bundles.

If you do not specify one of these options when using the -e parameter, the utility returns 0.

Note:

You cannot use this parameter with the -m or -g parameters.

-backout

Specifies backout-only rerating, which backs out the balance impacts of rating without rerating events. For more information about back-out-only rerating, see "Processing Events in Rerate Jobs".

This parameter is optional and can be used with any other parameter.

Note:

When choosing the events to back out, do not select events that could imbalance your general ledger, such as events for which fees have already been paid and usage events that should be rerated. Typically, backout-only rerating is performed only on usage events where rating should not have occurred.

-h | -help

Displays the syntax and parameters for this utility.