1. Rerating Events
  2. Manually Creating Rerate Jobs

4 Manually Creating Rerate Jobs

Learn how to create rerate jobs manually by running the pin_rerate utility in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

About Manually Selecting Events for Rerate Jobs

You manually specify the events to include in a rerate job using the pin_rerate utility. The utility selects events for the rerate job based on criteria you specify, which consists of a timestamp and one of the following:

  • One or more event types, such as purchase events and cancellations events

  • One or more account numbers

  • One or more charge offers, discount offers, or bundles

  • One or more service types

  • A sharing group owner

  • One or more balance groups

  • A customer's subscriber ID

  • Custom criteria

BRM finds events created after the specified timestamp generated by the accounts that meet your criteria. It then groups the events into a rerate job.

For example, assume you specify to rerate events generated after 15 June for the GSM data service type (/service/telco/gsm/data). In this case, BRM does the following:

  1. Finds all accounts associated with the GSM data service type.

    For example, it finds that accounts A, B, and C meet this criteria.

  2. For the accounts that meet the criteria, finds all events that they generated after 15 June. This includes any event type generated by the account, not just purchase events.

    For example, it finds all purchase events, cycle forward events, product cancellation events, and so on that accounts A, B, and C generated after 15 June.

  3. Adds the events from step 2 to a rerate job.

Selecting Events for Rerate Jobs

You select the events to rerate by running the pin_rerate utility with the job creation options. You can select events for rerate jobs based on the following:

Selecting Events for a Single Account

To select all events created by a single account after a specified date, you use the following syntax:

pin_rerate -a accountID -t timestamp

where:

  • accountID is the account POID object ID. For example, if the account POID is 0.0.0.1 /account 8606 0, the POID object ID is 8606.

  • timestamp is the timestamp in [ss/mm/hh/]MM/DD/YYYY format.

For example, this command finds all events generated by 0.0.0.1 /account 8606 0 after 23 July 2023 and adds them to a rerate job: 

pin_rerate -a 8606 -t 07/23/2023

Alternatively, you can run this command in calculate-only mode by adding the -c parameter. It performs rerating but does not update anything in the BRM database. For example, to run the previous command in calculate-only mode, you would enter: 

pin_rerate -a 8606 -c -t 07/23/2007

Note:

You can use the calculate-only mode (-c parameter) with only the -a parameter.

Selecting Events for a List of Accounts

To select all events created by a list of accounts after a specified date, you use the following syntax:

pin_rerate -m inputFile -t timestamp

where inputFile is the name of the XML file that lists the accounts.

For example, this command finds all events generated by the accounts listed in accounts_to_rerate.xml after 15 July 2023 and adds the events to a rerate job: 

pin_rerate -m accounts_to_rerate.txt -t 07/15/2023

In the input file, specify each account in a results array that lists account POIDs. For example:

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

Selecting Events for a Sharing Group

To select all events created after a specified date for all accounts in a specified sharing group, you use the following syntax:

pin_rerate -G groupOwnerId -t timestamp

where groupOwnerId is the account ID of the sharing group owner.

The utility includes events for the owner account and all member accounts of the specified charge sharing group, discount sharing group, profile sharing group, or product sharing group in the rerate job.

Note:

This job option does not support multilevel sharing group hierarchies. Only the owner and their immediate children are included in the 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.

For example, this command finds all events generated after 23 July 2023 by the sharing group owned by 0.0.0.1 /account 423591 and adds them to a rerate job: 

pin_rerate -G 423591 -t 07/23/2023

Selecting Events Associated with Offers

You can select all events for accounts associated with one of the following:

  • A list of charge offers. To do so, use the -p inputFile parameter to include all events for accounts associated with one or more specified charge offers. For example: 

    pin_rerate -p charge_offer_rerate.txt -t 01/23/2023

  • A list of discount offers. To do so, use the -i inputFile parameter to include all events for accounts associated with one or more specified discount offers. For example: 

    pin_rerate -i discount_offer_rerate.txt -t 01/23/2023

  • A list of bundles. To do so, use the -d inputFile parameter to include all events for accounts associated with charge offers or discount offers that belong to one or more specified bundles. For example: 

    pin_rerate -d bundle_rerate.txt -t 01/23/2023

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

Note:

The -p, -i, and -d parameters are mutually exclusive.

In the input file, list the charge offer, discount offer, or bundle names with one name on each line. For example:

ChargeOffer_1
ChargeOffer_2
ChargeOffer_3

All names are case-sensitive and must match the names as defined in your Pricing Design Center (PDC) product offerings.

Selecting Events Based On Event Type

To select events created after a specified date for accounts associated with a specific event type, you use the following syntax:

pin_rerate -n inputFile -t timestamp

For example, this command finds all events created after 10 January 2023 for accounts that are associated with the event types listed in event_rerate.xml: 

pin_rerate -n event_rerate.txt -t 01/10/2023

In the input file, you list the event types with one on each line. For example, this specifies to select only GSM and GPRS events:

/event/session/telco/gsm
/event/session/telco/gprs

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 arrears fee is modified during the billing cycle, then to rerate the cycle forward arrears event, you need to include both events in the event file:

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

  • /event/billing/cycle/discount

You can specify to also include the subclasses of all event types listed in the input file. To do so, include the -r parameter at the command line. For example: 

pin_rerate -n event_rerate.txt -r -t 01/10/2023

In this example, the utility would also include the /event/session/telco/gsm/data, /event/session/telco/gsm/voice, and /event/session/telco/gprs/session events in the rerate job.

Selecting Events Based On Service Type

To select all events for accounts associated with one or more service types, you use the following syntax:

pin_rerate -s inputFile -t timestamp

For example, this command finds all events for accounts associated with the service types listed in service_rerate.xml created after 20 May 2023, and adds the events to a rerate job: 

pin_rerate -s service_rerate.txt -t 05/20/2023

In the input file, you list the service types with one on each line. For example:

/service/telco/gsm/data
/service/telco/gsm/telephony
/service/telco/gsm/sms

Selecting Events Based On Subscriber Service ID

To select all events for accounts associated with a service identifier, you use the following syntax:

pin_rerate -line subscriptionID -t timestamp

where subscriptionID is the service identifier the customer created for the account. The service identifier is a unique ID that connects the customer to the service instance that the customer owns. For example, it could be an phone number, email address, or a personal ID number. Customers use the service identifier as their login name for the service.

For example, this command finds all events for accounts with the phone number 6495832245 created after 20 June 2023, and adds the events to a rerate job:

pin_rerate -line 6495832245 -t 06/20/2023

You can further restrict the selected accounts to those associated with:

  • Charge offers (-p)

  • Discount offers (-i)

  • Bundles (-d)

  • Events (-n)

  • Services (-s)

  • Accounts (-m)

  • Custom fields (-field_name)

Selecting Events Associated with Balance Groups

To select all events created for one or more balance groups, you use the following syntax:

pin_rerate -g inputFile -t timestamp

For example, this command finds all events generated by the balance groups listed in balance_groups.xml after 1 January 2023, and adds the events to a rerate job: 

pin_rerate -g balance_groups.txt -t 01/23/2023

In the input file, provide a results array that lists the POIDS for accounts, bill units, and balance groups. To rerate events for all balance groups in an account's bill unit, specify a value of NULL as the POID ID for the balance group, as shown in the following 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
...

Selecting Events Based on a Custom Event Field

To select events for accounts associated with a custom event field, you use the following syntax:

pin_rerate -fieldName inputFile -t timestamp

where fieldName is the name of a field you define. For example, if tax was calculated incorrectly, you might define the custom parameter -tax_supplier for selecting events based on the PIN_FLD_TAX_SUPPLIER field. In this case, you would specify a list of tax supplier IDs in the input file.

When you use a custom event field, the utility searches the base /event storable class for the field.

If the custom event field is present only in a subclass, use the -n parameter instead. For example, the PIN_FLD_ORIGIN_NETWORK field is not in the base /event class, so you must use the -n parameter to select events based on that field. In this case, you create an input file specifying the /event/activity/telco event in a file named event_rerate.txt.

Note:

When using the -n parameter with a custom field, the input file can contain only one type of event.

To select accounts whose telco events were generated a the specified origin network, run the following command: 

pin_rerate -n event_rerate.txt -origin origin.txt -t 06/01/2024

If the event specified in the input file contains subclasses, all subclass events are also selected. For example, if you specify /event/activity/telco, BRM also selects events from the /event/activity/telco/gsm event.

To define custom event fields:

  1. Create an XML file that maps the event field name to the utility's parameter name according to the BRM rerating XML schema file (BRM_home/xsd/pin_rerate_flds.xsd). You can map parameter names to fields in the base /event storable class or to fields in an /event subclass. For example: 

    <PinRerate> 
   <Name>EVENT.PIN_FLD_TAX_SUPPLIER</Name>
   <value>tax_supplier</value>
</PinRerate>

    where the <Name> tag specifies the event field name, and the <value> tag specifies the parameter name used at the command line.

    Note:

    Ensure that you validate your XML file against the XML schema. The load_pin_rerate_flds utility cannot load an invalid XML file.

  2. Load the XML file into the /config/rerate_flds object by running the load_pin_rerate_flds utility: 

    load_pin_rerate_flds -f xml_file_name

    See "load_pin_rerate_flds" for more information.

  3. Run the pin_rerate utility with the -fieldName parameter: 

    pin_rerate -fieldName inputFile -t timestamp

    For example, to search for the tax supplier in events:

    pin_rerate -tax_supplier tax_supplier.txt -t 01/23/2023

    The pin_rerate utility uses the /config/rerate_flds object to identify the event field to search for.

Backing Out Rating for Select Events

Backout-only rerating backs out the balance impacts of rating without rerating events. BRM backs out balance impacts for backout-only rerating by creating an adjustment event that entirely negates the original balance impacts.

Note:

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

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 to include in the job.

For example, the following command selects accounts whose events were rated by the charge offers specified in the charge_offer_backout.txt file and backs out those events that occurred after 12/1/2024: 

pin_rerate -backout -p charge_offer_backout.txt -t 12/1/2024 -r

Creating Rerate Jobs for Cycle Forward and Cycle Forward Arrears Events

Note:

You can create rerate jobs for cycle forward and cycle forward arrears events after their pricing has changed.

For example, suppose a $10 cycle fee is charged to an account for the cycle from April 15 to May 15. You change the fee from $10 to $20 on April 30, which is the middle of the cycle. When you rerate events, BRM recalculates the cycle fees as follows:

  • Refunds the $10 for the old cycle fee.

  • Recalculates the cycle fees based on the $10 fee for the first 14 days in the cycle and the $20 fee for the next 16 days in the cycle:

    ($10 x 14/30) + ($20 x 16/30) = $15.33

After you change the pricing for a cycle forward or cycle forward arrears event, run the pin_rate_change utility to analyze charge offers and create rerate jobs for cycle forward and cycle forward arrears events: 

pin_rate_change

See "pin_rate_change" for more information.

Assigning Reason Codes to Rerate Jobs

You may sometimes need rerating jobs to be processed in a specific order, such as charge offers first, discount offers second, and bundles third. You can enforce the order in which jobs are processed by assigning a reason code to your rerate jobs. Later, you specify the order in which to process your rerate jobs with an assigned reason code when you run rerating. See "Specifying the Order to Process Rerate Jobs" for more information.

To assign a reason code to a rerate job, you include the -reason parameter when specifying the events to rerate. For example: 

pin_rerate -reason reasonCode -p charge_offer_rerate.txt -t 01/30/2030

where reasonCode is a unique integer, except for the number 1. The number 1 is reserved for internal use.

For example, to assign reason code 100 to a rerate job containing events associated with a single account, you could enter: 

pin_rerate -reason 100 -a 86060 -t 01/30/2030

Getting an Estimated Number of Rerated Events

You can get an estimate of the number of events in a rerate job by including the pin_rerate -e parameter at the command line. You can use the -e parameter with any of the selection parameters, as shown below: 

pin_rerate -e [-p|-i|-s|-d|-n|-fieldName] inputFile -t timestamp

You cannot use the -e parameter when selecting events associated with the following:

  • A list of accounts (-m)

  • Balance groups (-g)

When you run the utility with the -e parameter, it displays an estimated number of events that will be rerated on the screen without loading any data into the database. It also writes the estimate to the pin_rerate.pinlog file.

For example, to get an estimate of the number of events that will be rerated for a list of services, use this command:

pin_rerate -e -s service_rerate.txt -t 12/01/2024

Specifying the Event Sequence in a Rerate Job

Events in a job are rerated in sequence based on the event time, which is based on either:

  • The event occurrence time: Events are rerated in the order the events ended. This is the default.

  • The time the event was created in the database: Events are rerated in the order they were loaded into the BRM database.

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

  • Events that are rated or loaded into the BRM database as a result of offline charging can have a significant delay between the event end time and the time they are loaded into the database. Using the event end time reflects the real-time sequence of the original events. However, because batch events are recorded in the order they were created in the database, this makes it harder to predict the impact of a price configuration change. To compare the original and rerated balance impacts of batch events, use the event creation time.

  • Events rated by online charging, and cycle events and purchase events, have no or very little delay between the event end time and the time they are loaded into the database. Both times reflect the real-time sequence in which the original events occurred and were recorded.

To specify the sequence in which to process events in a job, use the following syntax:

pin_rerate -b [c|e] eventCriteria

where:

  • -bc specifies to rerate events in the order they were loaded into the BRM database, and -be specifies to rerate events in the order that the usage events occurred.

  • -be specifies to rerate events in the order that the usage events occurred.

  • eventCriteria is any event selection criteria, such as the -a, -d, -g, -i, -m, -p, -s , -line, or custom parameters.

For example, this command selects events for all accounts that occurred after 06/15/2024, and specifies to rerate in the order in which the events occurred.

pin_rerate -be -t 06/15/2024