22 Billing Utilities

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

Topics in this document:

• load_config_item_tags

• load_config_item_types

• load_pin_bill_suppression

• load_pin_billing_segment

• load_pin_calendar

• load_pin_payment_term

• load_pin_remittance_flds

• load_pin_remittance_spec

• pin_bill_accts

• pin_cust_convert_wholesale_hierarchy

• pin_cycle_fees

• pin_make_corrective_bills

• pin_remittance

• pin_rollover

• pin_trial_bill_accts

• pin_trial_bill_purge

• pin_update_journals

load_config_item_tags

Use this utility to load item tags into the BRM database when you create custom bill items. See "Creating Custom Bill Items".

Location

BRM_home/bin

Syntax

load_config_item_tags [-v] [-d] [-h] config_item_tags_file 

Parameters

-v

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

load_config_item_tags 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.

config_item_tags_file

The name and location of the file that contains your item tag definitions. The sample config_item_tags.xml file is in the BRM_home/sys/data/pricing/example directory.

Results

The load_config_item_tags utility notifies you when it successfully creates the /config/item_tags object.

If the load_config_item_tags utility does not notify you that it was successful, 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.

load_config_item_types

Use this utility to load bill item tag-to-bill item type mappings into the BRM database when creating custom bill items. See "Creating Custom Bill Items".

Location

BRM_home/bin

Syntax

load_config_item_types [-v] [-d] [-h] config_item_types_file 

Parameters

-v

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

load_config_item_types 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.

config_item_types_file

The name and location of the file that contains your custom item definitions. You can use the sample file, BRM_home/sys/data/pricing/example/config_item_types.xml.

Results

The load_config_item_types utility notifies you when it successfully creates the /config/item_types object.

If the load_config_item_types utility does not notify you that it was successful, 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.

load_pin_bill_suppression

Use this utility to load bill suppression information for customer segments into the BRM database. See the following topics:

• Associating Bill Suppression Information with Customer Segments

• Editing the Bill Suppression Configuration File

Location

BRM_home/bin

Syntax

load_pin_bill_suppression [-t] [-v] [-d] [-h] filename

Parameters

-t

Runs the utility in test mode to validate the XML file against its schema definition (see "Validating Your Bill Suppression Configuration File Edits"). This option does not load data into the /config/suppression object or overwrite any existing data in the object.

Note:

To avoid load errors based on XML content problems, run the utility with this option before loading data into the object.

-v

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

load_pin_bill_suppression any_other_parameter –v > filename.log

-d

Creates a log file for debugging purposes. If no log file name is specified in the utility's pin.conf file, names the file default.pinlog. Use this parameter for debugging when the utility seems 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.

filename

The name and location of the bill suppression configuration file. The default file is BRM_home/sys/data/config/pin_bill_suppression.xml, but the utility can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition. See "Validating Your Bill Suppression Configuration File Edits".

If you run the command in a different directory from where filename is located, you must include the entire path for the file. In addition, filename must be in the same directory as the default BRM_home/sys/data/config/business_configuration.xsd file.

Results

This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.

To verify that the bill suppression information was loaded, display the /config/suppression object by using one of the following features:

• Object Browser

• robj command with the testnap utility

For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Note:

You must stop and restart the Connection Manager (CM) to make new bill suppression data available.

load_pin_billing_segment

Use this utility to load billing segment definitions into the BRM database. See "Setting Up Billing Segments".

Location

BRM_home/bin

Syntax

load_pin_billing_segment [-t] [-v] [-d] [-h] filename

Parameters

-t

Runs the utility in test mode to validate the XML file against its schema definition (see "Validating Your Billing Segment Configuration File Edits"). This option does not load data into the /config/billing_segment object or overwrite any existing data in the object.

Note:

To avoid load errors based on XML content problems, run the utility with this option before loading data into the object.

-v

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

load_pin_billing_segment any_other_parameter –v > filename.log

-d

Creates a log file for debugging purposes. If no log file name is specified in the utility's pin.conf file, names the file default.pinlog. Use this parameter for debugging when the utility seems 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.

filename

The name and location of the billing segment configuration file. The default file is BRM_home/sys/data/config/pin_billing_segment.xml, but the utility can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition. See "Validating Your Billing Segment Configuration File Edits".

If you run the command in a different directory from where filename is located, you must include the entire path for the file. In addition, filename must be in the same directory as the default BRM_home/sys/data/config/business_configuration.xsd file.

Results

This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.

To verify that the billing segment definitions were loaded, display the /config/billing_segment object by using one of the following features:

• Object Browser

• robj command with the testnap utility

For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

load_pin_calendar

Use this utility to load billing calendars into the BRM database. See "Editing the Billing Calendar Configuration File".

Location

BRM_home/bin

Syntax

load_pin_calendar [-t] [-d] [-v] [-h] filename

Parameters

-t

Runs the utility in test mode to validate the XML file against its schema definition (see "Validating Your Billing Calendar Configuration File Edits"). This option does not load data into /config/calendar objects or overwrite any existing data in the objects.

Note:

To avoid load errors based on XML content problems, run the utility with this option before loading data into the object.

-d

Creates a log file for debugging purposes. Use this parameter for debugging when the utility seems to have run with no errors but the data has not been loaded into the database.

-v

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

load_pin_calendar any_other_parameter –v > filename.log

-h

Displays the syntax and parameters for this utility.

filename

The name and location of the billing calendar configuration file. The default file is BRM_home/sys/data/config/pin_calendar.xml, but the utility can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition. See "Validating Your Billing Calendar Configuration File Edits".

If you run the command in a different directory from where filename is located, you must include the entire path for the file. In addition, filename must be in the same directory as the default BRM_home/sys/data/config/business_configuration.xsd file.

Results

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

load_pin_payment_term

Use this utility to load payment terms into the BRM database. See "Editing the Payment Terms Configuration File".

Location

BRM_home/bin

Syntax

load_pin_payment_term [-t] [-h] [-v] [-d] filename

Parameters

-t

Runs the utility in test mode to validate the XML file against its schema definition. This option does not load data into the /config/payment_term object or overwrite any existing data in the object.

Note:

To avoid load errors based on XML content problems, run the utility with this option before loading data into the object.

-h

Displays the syntax and parameters for this utility.

-d

Creates a log file for debugging purposes. Use this parameter for debugging when the utility seems to have run with no errors but the data has not been loaded into the database.

-v

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

load_pin_payment_term any_other_parameter –v > filename.log

filename

The name and location of the payment terms configuration file. The default file is BRM_home/sys/data/config/pin_payment_term.xml, but the utility can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition.

If you run the command in a different directory from where filename is located, you must include the entire path for the file. In addition, filename must be in the same directory as the default BRM_home/sys/data/config/business_configuration.xsd file.

Results

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

load_pin_remittance_flds

Use this utility to load remittance field definitions into the BRM database. A remittance field corresponds to an attribute of a storable class and is used to define criteria in remittance profiles. Loading these field definitions is a prerequisite to using the BRM remittance feature.

You define remittance fields in the BRM_home/sys/data/pricing/example/pin_remittance_flds file. Even if you do not modify the default version of this file, you must load this file before you can define a remittance specification file.

To connect to the BRM database, the load_pin_remittance_flds utility needs a configuration file in the directory from which you run the utility. See "Connecting BRM Utilities".

Caution:

When you run load_pin_remittance_flds, it overwrites remittance fields currently in the BRM database. If you are updating remittance fields, you cannot load only new fields. Ensure that you load a complete remittance fields file, including fields that have not changed.

Location

BRM_home/bin

Syntax

load_pin_remittance_flds [-t] [-v] [-d] [-h] remittance_flds

Parameters

-t

Runs the utility in test mode. This option does not save the field definitions to the BRM database. You can use this parameter to verify if the file will load correctly.

-v

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

load_pin_remittance_flds any_other_parameter –v > filename.log

-d

Creates a log file for debugging purposes. If no log file name is specified in the utility's pin.conf file, the file is named default.pinlog. Use this parameter for debugging when the utility seems 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.

remittance_flds

The name and location of the remittance fields file. The default is BRM_home/sys/data/pricing/example/pin_remittance_flds.

Results

This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.

load_pin_remittance_spec

Use this utility to load remittance specifications into the BRM database. In a remittance specification, you define the criteria that determine which third party receives remittance and which product BRM uses to calculate remittance. You must load this file to use the BRM remittance feature.

load_pin_remittance_spec checks the validity of products in the remittance specification.

You define remittance specifications in the BRM_Home/sys/data/pricing/example/pin_remittance_spec file, or another file that uses the same format.

Caution:

When you run load_pin_remittance_spec, it overwrites remittance specifications currently in the BRM database. If you are updating remittance information, you cannot load only new remittance specifications. Ensure that you load your complete specification file, including specifications that have not changed.

Location

BRM_home/bin

Syntax

load_pin_remittance_spec [-t] [-v] [-d] [-h] filename

Parameters

-t

Runs the utility in test mode. This option does not save the specification file to the BRM database. You can use this parameter to verify if the file will load correctly.

-v

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

load_pin_remittance_spec any_other_parameter –v > filename.log

-d

Creates a log file for debugging purposes. If no log file name is specified in the utility's pin.conf file, names the file default.pinlog. Use this parameter for debugging when the utility seems 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.

filename

The name and location of the remittance specification file. The default is BRM_Home/sys/data/pricing/example/pin_remittance_spec.

Results

This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.

Note:

You must stop and restart the Connection Manager (CM) to make the new specification available.

pin_bill_accts

Use this utility as part of your daily billing to calculate the balance due for each account and to create a bill for the balance due. See "Billing Accounts By Using the pin_bill_accts Utility".

Location

BRM_home/bin

Syntax

pin_bill_accts  [-active|-inactive|-close]
                [-pay_type ID] 
                [-end mm/dd/yy|numberOfDays] 
                [-remit include|exclude|only] 
                [-sponsorship|-discount]
                [-retry]
                [-cycle_charge_only] [-finalize_bill]
                [-check_for_subords]
                [-file billing_run_config_file_name]
                [-split]
                [-test]
                [-verbose]
                [-help]

Parameters

-active|-inactive|-close

Specifies the status of the accounts to be billed.

-pay_type ID

Calculates the balance due for accounts with the specified payment method. You specify the payment method by using the payment method ID, such as 10007 for nonpaying (subordinate) accounts, as shown in Table 22-1.

Note:

If you use -pay_type 10007 Subordinate, you must run the pin_bill_accts utility twice. The first time you run the utility with this parameter to calculate the child account's balance, and the second time you run the utility without the parameter to roll up the balance due to the parent account and then bill the parent account.

This example creates bills by using -pay_type 10007 for nonpaying (subordinate) accounts:

pin_bill_accts     -active      -pay_type 10007
pin_bill_accts     -active     

Table 22-1 Payment Method ID

Payment Method	ID
credit card	10003
debit card	10002
direct debit	10005
guest	10010
invoice	10001
prepaid	10000
SEPA	10018
subordinate	10007
undefined	0

-end mm/dd/yy|numberOfDays

Specifies the due date for accounts to be billed. You can specify a specific due date (for example, -end 01/31/01 includes accounts with a due date on or before January 31, 2001) or you can specify the due date as number of days from the current date (for example, -end 5 includes accounts with a due date on or before 5 days from the current date).

Note:

The end time parameter cannot be greater than the system time. For example, if the current system date is 1/15/2005 and the end time specified is 1/31/2005, pin_bill_accts fails with “bad config:time" error message.

-sponsorship

Specifies how charge sharing groups are billed. When you specify this option, the pin_bill_accts behavior is determined by the value of the BillingFlowSponsorship parameter, which can be one of the following:

• 0: Bills owner and member accounts in any order.

• 1: Bills owner accounts before member accounts.

• 2: Bills member accounts before owner accounts.

Before using this option, ensure that BillingFlowSponsorship is set to the correct value. See "Configuring Billing for Groups and Hierarchies".

Note:

You cannot use this parameter with the -discount parameter.

-remit include|exclude|only

Specifies whether remittance accounts should be billed. Use one of these options with this parameter:

• -remit include: Include remittance accounts in billing.

• -remit exclude: Exclude remittance accounts from billing.

• -remit only: Bill only remittance accounts.

If you do not specify this parameter, remittance accounts are excluded from billing. For information on remittance, see "Remitting Funds to Third Parties".

-discount

Specifies how discount sharing groups are billed. When you specify this option, pin_bill_accts behavior is determined by the value of the BillingFlowDiscount parameter, which can be one of the following:

• 0: Bills owner and member accounts in any order.

• 1: Bills owner accounts before member accounts.

• 2: Bills member accounts before owner accounts.

Before using this option, ensure that BillingFlowDiscount is set to the correct value. See "Configuring Billing for Groups and Hierarchies".

Note:

You cannot use this parameter with the -sponsorship parameter.

-cycle_charge_only

Runs billing on accounts with /billinfo bill states 0 and 1. All cycle fees and billing-time discounts are applied, but totals are not calculated, and the bill is not finalized. At the end of the billing run, the /billinfo bill state is set to 2. See "About Bill Unit States and the pin_bill_accts Utility".

Note:

After running pin_bill_accts with this parameter, use the -finalize_bill parameter to finalize the bill.

-finalize_bill

Runs billing on accounts with /billinfo bill state 2. Totals are calculated, and items, bills, and so on are updated. At the end of the billing run, the /billinfo bill state is set to 0. See "About Bill Unit States and the pin_bill_accts Utility".

Note:

• Use this parameter to finalize a bill after running the pin_bill_accts utility with the -cycle_charge_only parameter.

-retry

Runs billing for accounts that were previously not billed by pin_bill_accts due to some error. After the errors have been resolved, use this option to bill the failed accounts.

Use pay_type 10007 with the -retry option to bill failed accounts that own nonpaying bill units first, and then run it without the pay_type option to bill all other failed accounts as follows:

pin_bill_accts –active –retry –pay_type 10007
pin_bill_accts –active –retry

-file billing_run_config_file_name

Specifies the name and location of a billing run configuration file. The default file is pin_bill_run_control.xml in the BRM_home/apps/pin_billd directory.

The billing run configuration file can contain either a list of account and bill unit POIDs or a list of billing segments and accounting days of months (DOMs).

Note:

• When you run pin_bill_accts with a billing run configuration file, do not run it as a cron job. If you do, depending on the restrictions in the configuration file, some bill units might never be billed.

• When running pin_bill_accts with -file option, ensure that the accounts specified in the billing run configuration file reside on the same database schema where pin_bill_accts is run. If the file contains accounts from different database schemas, pin_bill_accts reports an error. See "Setting Up Billing in a Multischema Environment".

-split

Generates detail revenue assurance data if you have enabled its collection in the billing utilities configuration file. (See "Enabling Billing Utilities to Generate Revenue Assurance Data" in BRM Collecting Revenue Assurance Data.) You can view the detailed data by generating Revenue Assurance Billing Detail report. The details are based on item types.

Note:

If you specify both the -split and -file parameters and the input file for the -file parameter includes a list of accounts and bill units, the Revenue Assurance Billing Detail report does not segregate the data based on the billing segment and billing day of month (DOM).

For more information, see "About Collecting Revenue Assurance Data from Billing" in BRM Collecting Revenue Assurance Data.

-test

Tests the utility, but does not affect accounts. Use this parameter to see which accounts will be billed, without actually creating bills for the balances due.

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

pin_bill_accts any_other_parameter –verbose > filename.log

-help

Displays the syntax and parameters for this utility.

Results

If the pin_bill_accts utility does not notify you that it was successful, 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.

When it is called internally by the pin_bill_day script, the pin_bill_accts utility logs error information in the pin_mta.pinlog file.

Error Handling

When the pin_bill_accts utility detects that the cycle fee processing was not completed for the /billinfo object, pin_bill_accts stops with an error and sets the PIN_FLD_BILLING_STATUS field of the /billinfo object to PIN_BILL_ERROR. In addition, it sets the PIN_FLD_BILLING_STATUS_FLAGS field of the /billinfo object to PIN_BILL_FLAGS_CF_NOT_APPLIED (bit value 0x1000).

Note:

If any nonpaying child bill unit caused the failure, pin_bill_accts updates the billing statuses set in the PIN_FLD_BILLING_STATUS and PIN_FLD_BILLING_STATUS_FLAGS fields of the /billinfo object for both child and parent bill units.

pin_cust_convert_wholesale_hierarchy

Use this utility to convert one or more hierarchies to wholesale billing. See "Converting Existing Bill Unit Hierarchies to Wholesale Billing" for information about the composition of the input file. See "Configuring Wholesale Billing" for more information about wholesale billing.

Location

BRM_home/bin

Syntax

pin_cust_convert_wholesale_hierarchy -file convert_wholesale_input.xml

Parameters

-file convert_wholesale_input.xml

Specifies the name and location of an input file containing information about the hierarchies to be converted.

The input file can contain either a list of /billinfo POIDs or a list of /BusinessProfile POIDs for the hierarchies to be converted.

Results

Each thread of this application will call the PCM_OP_CUST_CONVERT_WHOLESALE_HIERARCHY opcode to convert the hierarchy for a parent account bill unit.

Error Handling

This application checks for multiple bill units on a single parent account, and if found, does not proceed for that account. Accounts with multiple parent bill units are not allowed in wholesale billing.

pin_cycle_fees

Use this utility to perform the following tasks:

• Charge cycle forward fees.

• Identify cycle forward fees that have reached the end of free billing periods. For example, if a customer signs up for one month of free service, the pin_cycle_fees utility finds when the free period is over and applies the cycle forward fee balance impact to the customer's account.

• Cancel charge offers that have an expired pending cancellation date. For example, if a charge offer is set to cancel at a future date, the pin_cycle_fees utility cancels the charge offer.

• Bill charge offers with a delayed purchase start time.

See "Prorating Cycle-Forward Fees and Canceling Charge Offers By Using the pin_cycle_fees Utility".

Location

BRM_home/bin

Syntax

pin_cycle_fees   -regular_cycle_fees|-defer_cycle_fees|-defer_cancel|-defer_purchase 
                 [-start mm/dd/yy|number_of_days] 
                 [-end mm/dd/yy|number_of_days] 
                 [-verbose] [-test] [-help]

Parameters

-regular_cycle_fees

Charges cycle forward fees.

Note:

The -regular_cycle_fees parameter replaces the functionality of the pin_cycle_forward utility.

-defer_cycle_fees

Identifies and applies cycle forward fees that have reached the end of free billing periods.

-defer_cancel

Cancels expired charge offers.

-defer_purchase

Bills charge offers with a delayed purchase start time.

-start [mm/dd/yy or yyyy|number_of_days]

-end [mm/dd/yy or yyyy|number_of_days]

Start and end dates.

If a start date is specified, the entire day is included. The end date is automatically the current date if you do not specify a value for the -end parameter.

If an end date is specified, that entire day is included, ending at, but not including, the 0th (first) second of the next day (00:00:00 a.m.). The end date cannot be a future date.

-test

Tests the utility, but does not affect accounts. Use this parameter to see which accounts have reached the end of free billing without actually applying cycle forward fees or canceling the expired charge offers.

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

pin_cycle_fees any_other_parameter –verbose > filename.log

-help

Displays the syntax and parameters for this utility.

Results

If the pin_cycle_fees utility does not notify you that it was successful, 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.

When it is called internally by the pin_bill_day script, the pin_cycle_fees utility logs error information in the pin_mta.pinlog file.

Error Handling

When the pin_cycle_fees utility encounters an error in applying regular, deferred, deferred purchase, or deferred cancellation cycle fees, it sets the PIN_FLD_BILLING_STATUS billing status field of the /billinfo object to PIN_BILL_ERROR. In addition, it sets the appropriate bit of the PIN_FLD_BILLING_STATUS_FLAGS field of the /billinfo object as follows:

• For regular cycle fees: PIN_BILL_FLAGS_CF_ERROR (bit value 0x100)

• For deferred cycle fees: PIN_BILL_FLAGS_DEF_CF_ERROR (bit value 0x200)

• For deferred purchase cycle fees: PIN_BILL_FLAGS_DEF_PURCHASE_ERROR (bit value 0x400)

• For deferred cancel cycle fees: PIN_BILL_FLAGS_DEF_CANCEL_ERROR (bit value 0x800)

Note:

If any nonpaying child bill unit caused the failure, pin_cycle_fees updates the billing statuses set in the PIN_FLD_BILLING_STATUS and PIN_FLD_BILLING_STATUS_FLAGS fields of the /billinfo object for both child and parent bill units.

When the status of the /billinfo object is set to PIN_BILL_ERROR, the pin_bill_accts utility, which runs after pin_cycle_fees, does not select this /billinfo object for billing. If you rerun pin_bill_accts with the -retry option, the billing opcode stops with an error because the cycle fee processing failed for this /billinfo object.

Rerun pin_cycle_fees (directly or through the pin_bill_day script) before you can run billing on this /billinfo object.

pin_make_corrective_bills

Use the pin_make_corrective_bills utility to generate corrective bills for prior bills that have corrections or to process corrections on prior corrective bills. See "Creating Corrective Bills".

This utility should be used for corrective billing only. For regular bills, use "pin_bill_accts".

Location

BRM_home/bin

Syntax

pin_make_corrective_bills  [-bill_no bill1, bill2,...] 
                           [-account_no acct1, acct2, acct3,...] 
                           [-start mm/dd/yy|number_of_days] 
                           [-end mm/dd/yy|number_of_days] 
                           [-file file_name]
                           [-item_type /item/A/R_item] 
                           [-adj_reason D_id R_id] 
                           [-threshold_amount min_amt] 
                           [-correction_reason D_id R_id] 
                           [-corrective_inv_type  R|L  D|S] 
                           [-no_adj_create [Y | N]]
                           [-validate_only]
                           [-help]

Parameters

-bill_no bill1, bill2...

Specifies the bill numbers for which corrective bills are required.

-account_no acct1, acct2, acct3...

Specifies the account numbers for which corrective bills are required.

-start mm/dd/yy|number_of_days

Specifies the start time to use in selecting the bills for corrective billing. When you specify the start date as a specific date, for example -start 01/31/01, the utility attempts to create corrective bills for all bills finalized on or before January 31, 2001. When you specify the start date as a number of days, for example -end 5, the utility attempts to create corrective bills for all bills finalized on or in the 5 days before the current date).

If you omit this parameter, pin_make_corrective_bills sets the start date to 1 month before the current date.

-end mm/dd/yy|number_of_days

Specifies the due date for accounts to be billed. You can specify a specific due date (for example, -end 01/31/12 includes accounts with a due date on or before January 31, 2012) or you can specify the due date as number of days from the current date (for example, -end 5 includes accounts with a due date on or 5 days before the current date).

If you omit this parameter, pin_make_corrective_bill sets the end date for the corrective billing for each selected bill to the end date on that bill.

Note:

The end time parameter cannot be greater than the system time. For example, if the current system date is 1/15/2012 and the end time specified is 1/31/2012, pin_make_corrective_bills fails with “bad config:time" error message.

-file file_name

Specifies that the list of accounts or the list of bill numbers will be read from a file, and provides the associated file name. The input file should be in XML format.

-item_type/item/A/R_item

Specifies the A/R item allocated to a bill as the criteria for selecting bills to include in the corrective billing. Enter the A/R item for example, /item/adjustment, /item/disputed, /item/writeoff, /item/recvd. Use -item_type item/any to select all A/R items. If you omit this parameter, pin_make_corrective_bills uses the default value, /item/adjustment, to select only those bills with adjustments allocated to them.

-adj_reason D_id R_id

Specifies the event-adjustment reasons associated with a bill as the criteria for selecting bills to include in the corrective billing. If you enter this parameter, you must specify both D_id which is the event adjustment domain number and R_id the reason number.

For example, -adj_reason D_id R_id

-threshold_amount min_amt

Specifies the minimum amount for A/R actions that should be reached in a bill to generate a corrective bill. pin_make_corrective_bills uses the value you input with the -threshold_amount parameter. If you omit this parameter, pin_make_corrective_bills uses the value currently in the CorrectiveBillThreshold business parameter.

-correction_reasonD_id R_id

Specifies the correction reason to associated with the corrective bills. You must specify both D_id which is the event adjustment domain number and R_id the reason number.

For example, -correction_reason D_id R_id.

-corrective_inv_type R|L D|S

Specify the type of corrective invoice to associate with each corrective bill. R indicates Replacement Invoice and L indicates Invoice Correction Letter. S indicates Summary and D indicates Detail.

Enter the two values separated by a blank. For example, to generate a detail replacement invoice, you specify -corrective_inv_type R D when you run the pin_make_corrective_bills utility.

If you omit one of the entries (as in -corrective_inv_type R) or omit the blank between the two entries (as in -corrective_inv_type RD), the pin_make_corrective_bills application will fail to generate the corrective bill.

-create_if_no_corrections Y|N

Specifies whether to generate the corrective bill when there are no A/R charges for a bill. The default value is N which results in pin_make_corrective_bills not generating the corrective bill for any bill with no A/R charges.

If you enter Y as the value for -create_if_no_corrections, set the -corrective_inv_type parameter to R (to indicate Replacement Invoice). pin_make_corrective_bills will not create the corrective bill if you specify -corrective_inv_type as L when you enter Y as the value for -create_if_no_corrections.

If you enter Y as the value for -create_if_no_corrections and you omit the -corrective_inv_type parameter, pin_make_corrective_bills creates the corrective bill if the /payinfo object for the account indicates a replacement invoice as the type of corrective invoice. Otherwise, it fails to create the corrective bill.

-validate_only

Specifies that pin_make_corrective_bills should only validate the eligibility of the bills for corrective billing. When you run pin_make_corrective_bills with the -validate_only parameter, the utility only verifies that the selected accounts or bills are eligible for corrective billing. It does not generate corrective bills.

When you use the -validate_only parameter, pin_make_corrective_bills lists the information for each bill in the default.pinlog log file.

-help

Displays the syntax and parameters for this utility.

Results

The pin_make_corrective_bills utility creates an entry in the default.pinlog utility log file for any errors it encounters in its process. The default.pinlog log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.

Error Handling

If billing fails due to errors in bill units, the pin_make_corrective_bills utility automatically updates the billing status field in their /billinfo objects to error. If any nonpaying child bill units caused the failure, the utility updates the billing status for both child and parent bill units.

pin_remittance

Use this utility to calculate the remittance you owe to third parties, such as service providers and resellers. Typically, you run pin_remittance as part of the monthly remittance script, pin_remit_month, but you can also run it apart from the script. You should run billing on non-remittance accounts before calculating remittance.

Note:

To connect to the BRM database, the pin_remittance utility needs a configuration file in the directory from which you run the utility. See "Connecting BRM Utilities".

Location

BRM_home/bin

Syntax

pin_remittance [-acct account_number] [-end date] [-output file_name]
               [-calconly] [-verbose] [-billing_cycle_alignment]
               [-help]

Parameters

-acct account_number

Calculates the remittance owed to an account. You can specify only one account number. Ensure that the account owns a remittance product.

If you do not use this parameter, pin_remittance runs on all remittance accounts.

-end date

Specifies the end date for which events are part of the calculation. pin_remittance calculates remittance for events that occurred before midnight of the day before the end date. For example, if the end date is 02/13/2020, pin_remittance includes all remittance events that took place through midnight of 02/12/2020.

If you do not specify this parameter, the end date is the current date. The start date is always the date of the previous remittance calculation.

The date format is mm/dd/yyyy.

-output [file_name]

Creates a remittance report. If you do not specify a file name, the report's default name is rem_date.rep, where date is the end date. To use a different name, specify that name with this parameter. If a file already exists with the report name you specify, pin_remittance overwrites the existing file.

-calconly

Calculates the remittance without writing the results to the BRM database. Use this parameter for testing and verification.

-billing_cycle_alignment

When the utility is run with the -billing_cycle_alignment parameter, the opcode's input PIN_FLD_FLAGS field is set to 1. This sets the opcode's current time and date to whichever of the following is earliest:

• BRM's current time and date

• Value of the utility's optional -end date parameter

• One second before the account's next billing cycle begins

This ensures that billing is not triggered before remittance is calculated when the utility is run after a remittance account's billing date.

Note:

By default, the pin_remit_month script runs the pin_remittance utility with the -billing_cycle_alignment parameter.

-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 -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_remittance any_other_parameter –v > filename.log

-help

Displays the syntax and parameters for this utility.

Results

If the pin_remittance utility does not notify you that it was successful, 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_rollover

The pin_bill_day script runs this Oracle Communications Billing and Revenue Management (BRM) utility to roll over all expired sub-balances that have not been rolled over.

For more information, see "When Rollover Events Occur" in PDC Creating Product Offerings.

Location

BRM_home/bin

Syntax

pin_rollover [-verbose] [-test]

Parameters

-verbose

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

-test

Runs in test mode to find the accounts that meet the criteria for roll over, but does not perform any roll over. The test does not affect the balances (currency and noncurrency) of the accounts.

Results

If the pin_rollover utility does not notify you that it was successful, 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_trial_bill_accts

Use this utility to calculate the balance due and create a trial invoice for each account.

Note:

Trial billing stops and reports a warning message when it encounters an account or bill unit with inactive status.

For information about trial billing, see "About Trial Billing".

Note:

• To connect to the BRM database, the pin_trial_bill_accts utility needs a configuration file in the directory from which you run the utility. The pin.conf file for this utility is in BRM_home/apps/pin_trial_bill. See "Connecting BRM Utilities" in BRM System Administrator's Guide.

• Trial billing may stop responding if the Data Manager has too few back ends configured. You should change the default configuration settings for Data Manager and increase the number of back ends. For more information about setting the number of back ends, see "Improving Data Manager and Queue Manager Performance" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

pin_trial_bill_accts [-start mm/dd/yy|+/- numberOfDays|0]
                     [-end mm/dd/yy|+/- numberOfDays|0]
                     [-f inputFile|-f_control inputFile]
                     [-active|-inactive|-closed]
                     [-bill_only]
                     [-pay_type ID]
                     [-retry]
                     [-split]
                     [-verbose]
                     [-help]

Parameters

-start mm/dd/yy or yyyy|+/- numberOfDays|0

-end mm/dd/yy or yyyy|+/- numberOfDays|0

The start and end dates determine which accounts are selected for trial billing and which billing cycles for those accounts are trial billed. See "Running Trial Billing With Date Ranges".

-f inputFile

Specifies the text file that contains the list of account POIDs for trial billing.

Example:

Create trial invoices for accounts in inputFile and whose billing date is less than 4/1/2002 (current date is 3/15/2002):

pin_trial_bill_accts -end 04/01/2002 -f myListOfAccounts

-f_control inputFile

Specifies the name and location of a text file that contains additional criteria for selecting accounts and bill units for trial billing. The default file is pin_bill_run_control.xml in the BRM_home/apps/pin_billd directory.

This file can contain a list of account and bill unit POIDs or a list of billing segments, accounting days of month (DOMs), or both.

For more information, see "Specifying Bill Units, Billing Segments, and DOMs for Trial Billing".

Note:

You should not specify billing segments or accounting DOMs with bill unit POIDs in the input file. If you do, the utility considers only the bill units for trial billing

The billing run configuration file can contain either a list of account and bill unit POIDs or a list of billing segments and accounting days of months (DOMs)

-active|-inactive|-closed

Searches for accounts whose status is active, inactive, or closed. By default, all accounts are searched.

Note:

The active, inactive, or closed parameter does not apply when you use the -f parameter.

-bill_only

Performs trial billing without generating trial invoices and collects revenue assurance data if you have enabled its collection in the trial billing utility configuration file. For more information, see "About Collecting Revenue Assurance Data from Trial Billing".

-pay_type ID

Generates trial invoices for accounts with the specified payment method ID. If you do not specify the payment method ID, the pin_trial_bill_accts utility generates trial invoices for all payment methods. See "Running Trial Billing According to Payment Type".

-retry

Runs trial billing for hierarchical bill units that were previously not billed during a trial invoicing run because of one or more errors. After the errors are resolved, use this parameter to rebill the unbilled hierarchical bill units.

You must run nonpaying child bill units before running paying parent bill units. You must also regenerate trial invoices on the parent bill units that did not contain an error. For example, to run trial billing on bill units that contained an error and whose payment method is by check, use the following syntax:

pin_trial_bill_accts -pay_type 10007 -retry
pin_trial_bill_accts -pay_type 10012 -retry
pin_trial_bill_accts -pay_type 10012

-split

Generates detail revenue assurance data if you have enabled its collection in the trial billing utility configuration file. This parameter is valid only if Revenue Assurance Manager is installed.

Note:

If you use this parameter, trial invoices are generated unless you also specify the -bill_only parameter.

You can view the detailed data by generating Revenue Assurance Billing Detail report. The details are based on item types.

Note:

If you specify both the -split and -f_control parameters and the input file for the -f_control parameter includes a list of accounts and bill units, the Revenue Assurance Billing Detail report does not segregate the data based on the billing segment and billing day of month (DOM).

For more information, see "About Collecting Revenue Assurance Data from Trial Billing".

-verbose

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

-help

Displays the syntax and parameters for this utility.

Results

If the pin_trial_bill_accts utility does not notify you that it was successful, 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_trial_bill_purge

Use this utility to purge trial invoices created with the "pin_trial_bill_accts" utility. For information about trial billing, see "Running Trial Billing".

Note:

To connect to the BRM database, the utility needs a configuration file in the directory from which you run the utility. The pin.conf file for this utility is in BRM_home/apps/pin_trial_bill. See "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

pin_trial_bill_purge [-start mm/dd/yy|+/- number_of_days|0]
                     [-end mm/dd/yy|+/- number_of_days|0]
                     [-active|-inactive|-closed]
                     [-f inputFile|-all]
                     [-verbose][-help]

Parameters

-start mm/dd/yy or yyyy|+/- number_of_days|0

The start and end dates determine the billing cycles for which trial invoices are purged. Billing cycles must fall entirely within the range created by the start and end dates, except fall between the start and end dates. You can specify an absolute date or number of days before or after the current date.

Note:

If you do not specify a start date, pin_trial_bill_purge will purge trial invoices for all billing cycles before the end date for the account. If end date is not specified, it uses the current date.

-end mm/dd/yy or yyyy|+/- number_of_days|0

The end date is used as the search criteria for retrieving accounts for purging trial invoices. It selects all accounts whose billing date is less than the end date. You can specify an absolute date or number of days before or after the current date.

Note:

If you do not specify an end date, pin_trial_bill_purge uses the current date for the end date.

Examples:

Purge trial invoices for accounts whose billing date is on or before 4/1/2032 (current date is 3/15/2032):

pin_trial_bill_purge -end 4/1/2032

pin_trial_bill_purge -end +16

Purge trial invoices for accounts whose billing date is on or before 3/1/2032 (current date is 3/15/2032)

pin_trial_bill_purge -end 3/1/2032

pin_trial_bill_purge -end -14

Purge trial invoices for accounts whose billing date is on or before the current date:

pin_trial_bill_purge -end 0

pin_trial_bill_purge

Purge trial invoices for accounts with complete billing cycles between 2/1/2032 and 3/15/2032 (current date is 3/15/2032):

pin_trial_bill_purge -start 2/1/2032 -end 3/15/2032

pin_trial_bill_purge -start -45 -end 0

-active|-inactive|-closed

Searches for accounts whose status is active, inactive, or closed. By default, all accounts are searched.

Note:

These parameters do not apply when you use the -f parameter.

-f inputFile

Specifies the text file that contains the list of account POIDs.

For example, to purge trial invoices for accounts in inputFile and whose billing date is less than 4/1/2032 (current date is 4/15/2032):

pin_trial_bill_purge -end 4/1/2032 -f myListOfAccounts

-all

Purges all trial invoices in the database.

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

pin_trial_bill_purge any_other_parameter –v > filename.log

-help

Displays the syntax and parameters for this utility.

Note:

If you do not specify a start or end date or a file with list of accounts, pin_trial_bill_purge selects all accounts whose billing date is on or before the current date.

Results

If the pin_trial_bill_purge utility does not notify you that it was successful, 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_update_journals

Use the pin_update_journals utility to process the temporary journals of nonpaying child bill units and then roll them up to the paying parent bill unit. You must run this utility before billing the paying parent bill unit. See "Rolling Journals Up to the Wholesale Parent".

Note:

To connect to the BRM database, the pin_update_journals utility needs a configuration file in the directory from which you run the utility. See "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

pin_update_journals [-verbose] [-help]

Parameters

-verbose

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

-help

Displays the syntax and parameters for this utility.

Results

If the pin_update_journals utility does not notify you that it was successful, 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.

Error Handling

When the pin_update_journals utility encounters an error while processing A/R items in the temporary tables, it sets the PIN_FLD_BILLING_STATUS billing status field of the paying parent bill unit (/billinfo object) to PIN_BILL_ERROR. In addition, it sets the appropriate bit of the PIN_FLD_BILLING_STATUS_FLAGS field of the /billinfo object as PIN_BILL_FLAGS_UPDATE_JOURNALS_ERROR (bit value 0x2000).

After you have resolved the processing errors, you can reprocess the A/R items by running the pin_update_journals utility again.