15 Billing Utilities

This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) billing utilities.

load_config_item_tags

Use this utility to load item tags into the BRM database.

You define item tags in the BRM_Home/sys/data/pricing/example/config_item_tags.xml file or another file that uses the same format. (BRM_Home is the directory where you installed BRM components.) The format of the XML file is specified in the config_item_tags.xsd schema file in the BRM_Home/xsd directory.

By default, this utility loads item tags into your system's default item tag configuration (/config/item_tags object whose PIN_FLD_NAME value is Default).

If the config_item_tags.xml file contains a value in its optional Name tag other than Default, this utility does one of the following:

  • If no other /config/item_tags object has the same name, the utility creates a new /config/item_tags object and sets the PIN_FLD_NAME field of the new object to the value specified in the Name tag.

  • If another /config/item_tags object with the same name already exists, the utility replaces that object.

For information about item tags, see "Creating Custom Bill Items."

Note:

You cannot load separate /config/item_tags objects for each brand. All brands use the same objects.

Caution:

When you run load_config_item_tags, it overwrites the existing item tags in the /config/item_tags object whose PIN_FLD_NAME value matches the Name value in the config_item_tags.xml file. If the XML file does not contain a PIN_FLD_NAME value, the Default item tag configuration is replaced.

If you are updating a set of item tags, you cannot load the new item tags only. You must load the entire set of tags in the config_item_tags.xml file.

Important:

To connect to the BRM database, the load_config_item_tags utility requires a configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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

You define these items in the BRM_Home/sys/data/pricing/example/config_item_types.xml file, or another file that uses the same format. The format of the XML file is specified in the config_item_types.xsd schema file in the BRM_Home/xsd directory.

By default, this utility loads mappings into your system's default item type configuration (/config/item_types object whose PIN_FLD_NAME value is Default).

If the config_item_types.xml file contains a value in its optional Name tag other than Default, this utility does one of the following:

  • If no other /config/item_types object has the same name, the utility creates a new /config/item_types object and sets the PIN_FLD_NAME field of the new object to the value specified in the Name tag.

  • If another /config/item_types object with the same name already exists, the utility replaces that object.

For information about item types, see "Creating Custom Bill Items."

Caution:

When you run load_config_item_types, it overwrites the existing mappings in the /config/item_types object whose PIN_FLD_NAME value matches the Name value in the config_item_types.xml file. If the XML file does not contain a PIN_FLD_NAME value, the Default item type configuration is replaced.

If you are updating a set of mappings, you cannot load the new mappings only. You must load complete sets of mappings each time you run the load_config_item_types utility.

When you run load_config_item_tags, it overwrites the existing item tags in the /config/item_tags object whose PIN_FLD_NAME value matches the Name value in the config_item_tags.xml file. If the XML file does not contain a PIN_FLD_NAME value, the Default item tag configuration is replaced.

If you are updating a set of item tags, you cannot load the new item tags only. You must load the entire set of tags in the config_item_tags.xml file.

Note:

To connect to the BRM database, the load_config_item_types utility requires a configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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. 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 mappings. 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 /config/suppression object in the BRM database.

You enter this information in the bill suppression configuration file (BRM_Home/sys/data/config/pin_bill_suppression.xml).

For more information, see the following topics:

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 copy filename to the same directory from which you run the load utility, specify only the file name. 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.

Important:

You must stop and restart the Connection Manager (CM) to make new bill suppression data available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

load_pin_billing_segment

Use this utility to load billing segment definitions into the /config/billing_segment object in the BRM database.

You define billing segments in the billing segment configuration file (BRM_Home/sys/data/config/pin_billing_segment.xml).

For more information, see the following topics:

  • About billing segments

  • Editing the Billing Segment Configuration File

  • Setting Up Billing Segments

    Note:

    You cannot load separate /config/billing_segment objects for each brand. All brands use the same object.

    Caution:

    This utility overwrites all existing data in the /config/billing_segment object. When updating the data, you cannot load new data only. You must load bill suppression data for each customer segment every time you run the utility.

    Important:

    To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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 copy filename to the same directory from which you run the load utility, specify only the file name. 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 /config/calendar objects in the BRM database.

You configure billing calendars in the billing calendar configuration file (BRM_Home/sys/data/config/pin_calendar.xml). See "Editing the Billing Calendar Configuration File".

Note:

You cannot load separate /config/calendar objects for each brand. All brands use the same object.

Caution:

This utility overwrites all existing data in the /config/calendar objects. When updating billing calendars, you cannot load new calendars only. You must load data for each calendar every time you run the utility.

Important:

To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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 copy filename to the same directory from which you run the load utility, specify only the file name. 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.

To verify that the billing calendars were loaded, display the /config/calendar objects 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.

Important:

You must stop and restart the Connection Manager (CM) to make new billing calendar data available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

load_pin_payment_term

Use this utility to load payment terms into the /config/payment_term object in the BRM database.

You configure payment terms in the payment terms configuration file (BRM_Home/sys/data/config/pin_payment_term.xml). See "Editing the Payment Terms Configuration File".

Note:

You cannot load separate /config/payment_term objects for each brand. All brands use the same object.

Caution:

This utility overwrites all existing data in the /config/payment_term object. When updating the data, you cannot load new data only. You must load data for each payment term every time you run the utility.

Important:

To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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 (see "Validating Your Payment Terms Configuration File Edits"). 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. See "Validating Your Payment Terms Configuration File Edits".

If you copy filename to the same directory from which you run the load utility, specify only the file name. 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.

To verify that the payment terms were loaded, display the /config/payment_term 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.

Important:

You must stop and restart the Connection Manager (CM) to make new payment term data available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

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.

For information about remittance, see "Remitting Funds to Third Parties" and "About Customizing Remittance".

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.

Note:

To connect to the BRM database, the load_pin_remittance_flds utility requires a configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

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

Parameters

remittance_flds

The name and location of the remittance fields file. By default, this file is BRM_Home/sys/data/pricing/example/pin_remittance_flds.

-d

Writes additional information for debugging purposes to the utility log file default.pinlog. This file is located either in the directory from which the utility was started, or in a directory specified in the configuration file.

-t

Runs in test mode. In this mode, load_pin_remittance_flds 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

-help

Displays the syntax and parameters for this utility.

Results

The load_pin_remittance_flds utility notifies you only if it encounters errors. Use the -v option to display additional status information.

If this utility encounters errors, look in the log file (default.pinlog) for error messages. 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_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 define remittance specifications in the BRM_Home/sys/data/pricing/example/pin_remittance_spec file, or another file that uses the same format. You must load this file to use the BRM remittance feature.

load_pin_remittance_spec checks the validity of products in the remittance specification.

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.

Note:

For information about remittance, see "Remitting Funds to Third Parties".

Location

BRM_Home/bin

Syntax

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

Parameters

remittance_spec

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

-d

Writes error information for debugging purposes to the utility log file default.pinlog. This file is located either in the directory from which the utility was started, or in a directory specified in the configuration file.

-t

Runs in test mode. In this mode, load_pin_remittance_spec 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

-help

Displays the syntax and parameters for this utility.

Results

The load_pin_remittance_spec utility notifies you only if it encounters errors. Use the -v option to display additional status information.

If this utility encounters errors, look in the log file default.pinlog for error messages. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.

Important:

You must stop and restart the Connection Manager (CM) to make the new specification available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

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. This utility should be used for regular billing only. For corrective bills, use "pin_make_corrective_bills".

For information about billing, see:

  • Billing accounts with the pin_bill_accts utility

  • About billing

    Note:

    To connect to the BRM database, the pin_bill_accts utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

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

Parameters

-active|-close|-inactive

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 15-1.

Table 15-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


Important:

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     
-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/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.
-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".

-sponsorship

Specifies how charge sponsor groups will be billed. When you specify this option, pin_bill_accts will do the following depending on the billing_flow_sponsorship parameter in /config/business_params:

If the value of billing_flow_sponsorship is:

  • 0, it bills sponsor and sponsoree accounts in any order.

  • 1, it bills sponsor accounts before sponsorees.

  • 2, it bills sponsoree accounts before sponsors.

Before using this option, ensure that sponsorship billing is enabled. See "Setting up billing for sponsorship".

Note:

You cannot use this parameter with the -discount parameter.
-discount

Specifies how discount sponsor groups will be billed. When you specify this option, pin_bill_accts will do the following depending on the billing_flow_discount parameter in /config/business_params:

If the value billing_flow_discount is:

  • 0, it bills discount group owner and discount group member accounts in any order.

  • 1, it bills discount group owner accounts before discount group member accounts.

  • 2, it bills discount group member accounts before discount group owner accounts.

Before using this option, ensure that sponsorship billing is enabled. See "Setting up billing for sponsorship".

Note:

You cannot use this parameter with the -sponsorship parameter.
-cycle_charge_only

If best pricing is configured, runs billing on accounts with billinfo states 0 and 1. At the end of billing, the billinfo state advances to the next state. See "About Bill States" in BRM Managing Accounts Receivable.

For information on best pricing, see "Offering the Best Price to Your Customers".

-finalize_bill

If best pricing is configured, runs billing on accounts with billinfo state 2. At the end of billing, the billinfo state is set back to 0. See "About Bill States" in BRM Managing Accounts Receivable.

For information on best pricing, see "Offering the Best Price to Your Customers".

-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 the pay_type 10007 with the -retry option to bill the failed subordinate accounts 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
-from_file file_name

Specifies that the accounts to bill will be read from a file, and the associated file name. This parameter is used when you set up pipeline-triggered billing. The input file is passed to the pin_bill_accts utility by the BillHandler billing batch handler to trigger billing for the accounts specified in the file. See "Setting up pipeline-triggered billing".

-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). For more information, see the following topics:

  • Splitting a billing run into multiple runs

  • Specifying due date adjustments in a billing run

  • Billing Only Specified Accounts and Bill Units

    Note:

    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 to Run in a Multischema Environment".

    Caution:

    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.
-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 has not been completed for the /billinfo object, pin_bill_accts aborts with an error and sets the PIN_FLD_BILLING_STATUS field of the /billinfo object to PIN_BILL_ERROR. In addition, it also sets the PIN_FLD_BILLING_STATUS_FLAGS field of the /billinfo object to PIN_BILL_FLAGS_CF_NOT_APPLIED (bit value 0x1000).

Important:

If any subordinate 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 subordinate and parent bill units.

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 products that have an expired pending cancellation date. For example, if a product is set to cancel at a future date, the pin_cycle_fees utility cancels the product.

  • Bill products with a delayed purchase start time.

For more information about fees, see "Prorating Cycle-Forward Fees and Canceling Products with the pin_cycle_fees Utility".

Note:

To connect to the BRM database, the pin_cycle_fees utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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

-defer_purchase

Bills products 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. For information on using start and end parameters, see "Specifying Start and End Times".

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

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

Important:

If any subordinate 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 subordinate 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 aborts with an error because the cycle fee processing has 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_cycle_forward

Use this utility to charge cycle forward fees.

Note:

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

Note:

To connect to the BRM database, the pin_cycle_forward utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

pin_cycle_forward [-verbose][-test][-help]

Parameters

-verbose

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

Note:

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_forward –verbose > filename.log

-test

Runs in test mode to find the accounts that meet the criteria for cycle forward fee, but does not apply any cycle forward fees. The test does not affect the resource balances (currency and non-currency) of the accounts.

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

pin_deferred_act

Use this utility as part of your daily billing to execute deferred actions. For example, if a CSR has scheduled an account to become inactive, the pin_deferred_act utility performs the status change on the scheduled date. By default, this utility is included in the pin_bill_day script.

For more information, see "Executing Deferred Actions with the pin_deferred_act Utility".

For information about scheduling status changes, see "Managing Deferred Actions" in BRM Managing Customers.

Note:

To connect to the BRM database, the pin_deferred_act utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

pin_deferred_act [-report|-purge|-retry] [-opcode opcode_name]
                 [-status pending|done|error][-start mm/dd/yy]
                 [-end mm/dd/yy] [-verbose] [-test] [-help]

Parameters

-report

Displays the progress and current state of /schedule objects.

This parameter can take one or more of these options as search criteria to filter the results of your report:

  • -opcode [opcode_name]

  • -status pending|done|error

  • -start mm/dd/yy or yyyy

  • -end mm/dd/yy or yyyy

For example:

pin_deferred_act -report -start 01/10/03 -end 01/24/03 -verbose
-purge

Purges from the BRM database all /schedule objects whose actions have been executed successfully. This helps reduce the size of your database.

This parameter can take one or more of these options as search criteria for purging:

  • -opcode [opcode_name]

  • -status pending|done|error

  • -start mm/dd/yy or yyyy

  • -end mm/dd/yy or yyyy

For example:

pin_deferred_act -purge -start 01/10/03 -end 01/24/03 -verbose -opcode PCM_OP_BILL_MAKE_BILL_NOW
-retry

Retries all the /schedule objects whose schedule actions have failed to execute and whose status is marked as ERROR.

This parameter can take one or more of these options as search criteria for purging:

  • -opcode [opcode_name]

  • -status pending|done|error

  • -start mm/dd/yy or yyyy

  • -end mm/dd/yy or yyyy

For example

pin_deferred_act -retry -start 01/10/03 -end 01/24/03 -verbose
-opcode [opcode_name]

Used as search criteria by the –report, –purge, and –retry parameters for retrieving /schedule objects containing the specified opcode responsible for the deferred action.

For example:

pin_deferred_act -report -start 01/10/03 -end 01/24/03 -verbose -opcode PCM_OP_BILL_MAKE_BILL_NOW
-status pending|done|error

Used as search criteria by the –report, –purge, and –retry parameters for retrieving /schedule objects having the specified status.

For example:

pin_deferred_act -retry -start 01/10/03 -end 01/24/03 -verbose -status ERROR
-start mm/dd/yy or yyyy
-end mm/dd/yy or yyyy

Used as search criteria by the –report, -purge, and –retry parameters for retrieving /schedule objects with an execution date matching the start and end dates specified. The value you supply for the start date is inclusive, but the value for the end date is non–inclusive and also defaults to the current date. If a start date is not specified, this utility retrieves all valid /schedule objects up to the specified end date. If an end date is not specified, this utility uses the current date as the end date and retrieves all valid /schedule objects until the current date.

For information on using this parameter, see "Specifying Start and End Times".

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

pin_deferred_act any_other_parameter –v > filename.log

-test

Runs a test to find out how many accounts meet the criteria without performing the action. The test has no effect on the accounts. This is most useful when run with the -verbose option.

-help | -h

Displays the syntax and parameters for this utility.

Results

If the 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_deferred_act utility logs error information in the pin_mta.pinlog file.

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. This utility is a multithreaded application which runs the PCM_OP_BILL_MAKE_CORRECTIVE_BILL opcode in each working thread.

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

To connect to the BRM database, the pin_make_corrective_bills utility uses the configuration file you use to run the pin_ bill_accts utility. The default file is pin_bill_run_control.xml in the BRM_Home/apps/pin_billd directory. For more information, see the description on creating configuration files for BRM utilities in BRM System Administrator's Guide.

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/xxx] 
                [-adj_reason D R] 
                [-threshold_amount amount] 
                [-correction_reason D R] 
                [-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_bills 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

This BRM command-line utility calculates 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.

For information on billing, see "About Running the Billing Scripts".

For information about remittance, see "Remitting Funds to Third Parties".

Note:

To connect to the BRM database, the pin_remittance 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_remit. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

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

Tip:

You can use just the first character of each parameter when you run pin_remittance. For example, you can enter either pin_remittance -help or pin_remittance -h.

Parameters

-acct account_number

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

For the default account number format, see the Glossary entry for account number.

-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/2001, pin_remittance includes all remittance events that took place through midnight of 02/12/2001.

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 remittance without writing the results to the BRM database. Use this parameter for testing and verification.

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

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

Displays the syntax and parameters for this utility.

pin_rollover

The pin_bill_day script runs this BRM utility to roll over all expired resource sub-balances that have not been rolled over.

For more information, see "When Rollover Events Occur" in BRM Setting Up Pricing and Rating.

Note:

To connect to the BRM database, the pin_rollover utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

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 resource balances (currency and non-currency) 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.

Important:

Trial billing stops and reports a warning message when it encounters an account or bill unit (/billinfo) 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 "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Important:

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.

The end date is used as the search criteria for retrieving accounts for trial billing. The search selects all accounts with a billing date less than the end date. You can specify either an absolute date, a number of days before or after the current date, or the current date (by specifying 0).

Note:

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

The start date determines the billing cycles for which trial invoices are generated. You can specify either an absolute date, a number of days before or after the current date, or the current date (by specifying 0).

If you specify a start date, trial billing is run only when a billing cycle is completed between the start date and the end date. Trial billing is not run on partial cycles.

Note:

If you do not specify a start date or if you specify 0 for the current date, pin_trial_bill_accts generates trial invoices for all billing cycles that were completed between the current date and the end date and that have not already been billed. More than one trial invoice might be generated for accounts that have not been billed for one or more billing cycles.

Examples:

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

    pin_trial_bill_accts -end 04/01/2002
    pin_trial_bill_accts -end +17
      
    
  • Create trial invoices for accounts whose billing date is on or before 3/1/2002 (current date is 3/15/2002)

    pin_trial_bill_accts -end 03/01/2002
    pin_trial_bill_accts -end -14
      
    
  • Create trial invoices for accounts whose billing date is on or before the current date:

    pin_trial_bill_accts -end 0
    pin_trial_bill_accts
      
    
  • Create trial invoices for accounts with complete billing cycles between 4/1/2002 and 5/15/2002 (current date is 5/15/2002):

    pin_trial_bill_accts -start 04/01/2002 -end 5/15/2002
    pin_trial_bill_accts -start -44 -end 0
      
    
-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 the month (DOMs), or both.

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

Note:

You should not specify bill segments or DOMs along with bill units (/billinfo object POIDs) in the input file. If bill segments or DOMs are specified along with bill units, the pin_trial_bill_accts utility considers only the bill units for trial billing.
-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.

The ID can be any payment method ID from Table 15-2.

Table 15-2 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


For example, to generate trial invoices for all bills paid by the credit card payment method, use the following syntax:

pin_trial_bill_accts -pay_type 10003
   

For hierarchical accounts, you must run the subordinate accounts before running the parent account. For example, to generate trial invoices for hierarchical accounts whose payment method is by check, use the following syntax:

pin_trial_bill_accts -pay_type 10007
pin_trial_bill_accts -pay_type 10012
   

Hierarchical Account Limitations:

  • The -active, -closed, or -inactive parameters are not supported for subordinate accounts when combined with the -pay_type parameter. These parameters limit the amount of subordinates that are invoiced, which leads to errors when the parent account is trial billed.

  • Do not set a threshold value. Setting a threshold value limits the amount of subordinates that are invoiced, which leads to errors when the parent account is trial billed.

    Note:

    The threshold entry is located in the BRM_Home/apps/pin_trial_bill/pin.conf file.
  • The -f, -f_control and -bill_only parameters are not supported for all accounts when used with the -pay_type parameter.

For more information on payment methods, see "About Payment Methods" in BRM Configuring and Collecting Payments.

For more information on creating hierarchical account trial invoices, see the discussion on creating hierarchical account trial invoices in BRM Designing and Generating Invoices.

-retry

Runs trial billing for hierarchical accounts that were previously not billed during a trial invoicing run due to some error. After the errors have been resolved, use this parameter to rebill the hierarchical accounts that were previously not billed.

You must run the subordinate accounts before running the parent account. You must also regenerate trial invoices on the parent accounts that did not contain an error. For example, to run trial billing on accounts 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
  

For more information, see the discussion on working with hierarchical account trial billing errors in BRM Designing and Generating Invoices.

-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 a 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 (type /invoice/trial) created with the "pin_trial_bill_accts" utility.

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

The pin.conf file for this utility is in BRM_Home/apps/pin_trial_bill.

Location

BRM_Home/bin

Syntax

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

Parameters

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

The start and end dates determine the billing cycles for which trial invoices are purged. Billing cycles must fall entirely within the start and end date range. 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 purges trial invoices for all billing cycles before the specified end date.
-end mm/dd/yy or yyyy |+/- numberOfDays|0

The utility selects all accounts whose billing date is before 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.

Examples:

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

pin_trial_bill_purge -end 4/1/2002
pin_trial_bill_purge -end +16
  

Purge trial invoices for accounts whose billing date is before 3/1/2002 (current date is 3/15/2002):

pin_trial_bill_purge -end 3/1/2002
pin_trial_bill_purge -end -14
  

Purge trial invoices for accounts whose billing date is 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/2002 and 3/15/2002 (current date is 3/15/2002):

pin_trial_bill_purge -start 2/1/2002 -end 3/15/2002
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 included in the search.

Note:

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

Specifies the text file that contains the list of account POIDs for the accounts to process.

Example:

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

pin_trial_bill_purge -end 4/1/2002 -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 redirect the output to a log file, use the following syntax, where filename.log is 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 a 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_items_journals

Use the pin_update_items_journals utility to process the temporary item and journal data and update the main item and journal tables. This utility is run when the value of the StagedBillingFeeProcessing business parameter specifies that the service charges should be aggregated to a single account-level item. See "About Applying Cycle Forward Fees in Parallel" for more information.

To connect to the BRM database, the pin_update_items_journals utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_Home/bin

Syntax

pin_update_items_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_items_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_items_journals utility encounters an error while processing items and journal data in the temporary tables, 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:

  • Updating journal objects: PIN_BILL_FLAGS_UPDATE_JOURNALS_ERROR (bit value 0x2000)

  • Updating item objects: PIN_BILL_FLAGS_UPDATE_ITEMS_ERROR (bit value 0x4000)

Important:

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

After you have resolved the processing errors, you can reprocess the items and journals data by running the pin_update_items_journals utility again.