Billing Opcode Workflows

6 Billing Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) billing opcode workflows.

Topics in this document:

Opcodes Described in This Chapter

Table 6-1 lists the opcodes described in this chapter.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 6-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_POL_CONFIG_BILLING_CYCLE	Customizing How to Bill Events That Occur between Billing Cycles
PCM_OP_ACT_USAGE	Customizing How to Bill Events That Occur between Billing Cycles
PCM_OP_BILL_CONVERT_AMOUNTS	About Currency Conversion
PCM_OP_BILL_CREATE_SPONSORED_ITEMS	Creating /item/sponsor Objects Running Bill Now Running Bill Now for a Service
PCM_OP_BILL_CURRENCY_CONVERT_AMOUNTS	About Currency Conversion
PCM_OP_BILL_CURRENCY_QUERY_CONVERSION_RATES	About Currency Conversion
PCM_OP_BILL_CYCLE_TAX	Running Bill Now
PCM_OP_BILL_MAKE_BILL	Creating Bills Modifying a Bill Object Calculating When a Bill is Due Customizing Accounting Cycles Suspending and Resuming Billing of Closed Accounts Determining Whether Bills Should Be Suppressed Manually Suppressing Bills Making Trial Bills
PCM_OP_BILL_MAKE_BILL_NOW	Modifying a Bill Object Calculating When a Bill is Due Running Bill Now Running Bill Now for a Service Applying Discounts and Folds with Bill Now Creating /item/sponsor Objects Using Revenue Assurance Manager
PCM_OP_BILL_MAKE_BILL_ON_DEMAND	Using Revenue Assurance Manager
PCM_OP_BILL_MAKE_CORRECTIVE_BILL	Calculating When a Bill is Due Customizing Bill Due Date Calculations for Payment Terms Making a Corrective Bill Validating Bills for the Corrective Billing Process
PCM_OP_BILL_MAKE_TRIAL_BILL	Making Trial Bills Creating Bills Collecting Split Revenue Assurance Data
PCM_OP_BILL_POL_BILL_PRE_COMMIT	Modifying a Bill Object
PCM_OP_BILL_POL_CALC_PYMT_DUE_T	Creating Bills Calculating When a Bill is Due Customizing Bill Due Date Calculations for Payment Terms Changing the Bill Now Due Date Payment Due Dates for Corrective Bills
PCM_OP_BILL_POL_CHECK_SUPPRESSION	Determining Whether Bills Should Be Suppressed Adding Bill Suppression Exceptions Deleting Bill Suppression Exceptions Creating Bills
PCM_OP_BILL_POL_GET_PENDING_ITEMS	Creating /item/sponsor Objects Customizing Bill Now Running Bill Now for a Service
PCM_OP_BILL_POL_POST_BILLING	Suspending and Resuming Billing of Closed Accounts
PCM_OP_BILL_POL_SPEC_BILLNO	Customizing the Format of Bill and Invoice Numbers
PCM_OP_BILL_POL_SPEC_FUTURE_CYCLE	Customizing Accounting Cycles
PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL	Validating Bills for the Corrective Billing Process
PCM_OP_BILL_REMOVE_ACCOUNT_SUPPRESSION	Ending Manual Account Suppression
PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION	Suppressing Accounts
PCM_OP_BILL_SET_BILL_SUPPRESSION	Manually Suppressing Bills
PCM_OP_BILL_SET_LIMIT_AND_CR	Customizing Credit Limit and Consumption Rules Customizing Client Applications to Modify Fixed Thresholds
PCM_OP_CUST_CREATE_BILLINFO	Creating Bill Units Updating Bill Units
PCM_OP_CUST_DELETE_BILLINFO	Deleting Bill Units
PCM_OP_CUST_POL_PREP_BILLINFO	Preparing Bill Unit Data Setting the Billing DOM According to the Payment Method Updating Bill Units Validating Bill Unit Data
PCM_OP_CUST_POL_VALID_BILLINFO	Validating Bill Unit Data Updating Bill Units Preparing Bill Unit Data
PCM_OP_CUST_SET_BILLINFO	Customizing Accounting Cycles Updating Bill Units Preparing Bill Unit Data Setting Up Hierarchical and Sharing Relationships among Bill Units Changing Hierarchical and Sharing Relationships among Bill Units
PCM_OP_CUST_SET_STATUS	Resuming Billing When Closed Accounts Are Reactivated
PCM_OP_DELIVERY_MAIL_SENDMSGS	Customizing Alert Behavior
PCM_OP_MAKE_BILL_ON_DEMAND	Modifying a Bill Object On-Purchase Billing
PCM_OP_PROCESS_AUDIT_CREATE	Using Revenue Assurance Manager
PCM_OP_PROCESS_AUDIT_CREATE_WRITEOFF_SUMMARY	Customizing the Revenue Assurance Written-Off Event Record Summaries Using Revenue Assurance Manager
PCM_OP_PROCESS_AUDIT_POL_ALERT	Customizing Alert Behavior
PCM_OP_PROCESS_AUDIT_POL_CREATE	Customizing Audit Object Validation Using Revenue Assurance Manager
PCM_OP_PROCESS_AUDIT_SEARCH	Using Revenue Assurance Manager
PCM_OP_PYMT_COLLECT	Customizing the Minimum Amount to Charge
PCM_OP_PYMT_GRANT_INCENTIVE	Creating Bills
PCM_OP_PYMT_POL_PRE_COLLECT	Customizing the Minimum Amount to Charge
PCM_OP_SUBSCRIPTION_APPLY_RATE	Customizing Accounting Cycles
PCM_OP_SUBSCRIPTION_CYCLE_ARREARS	Running Bill Now Customizing Accounting Cycles
PCM_OP_SUBSCRIPTION_CYCLE_FOLD	Running Bill Now
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD	Running Bill Now Customizing Accounting Cycles
PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL	Customizing Accounting Cycles
PCM_OP_SUBSCRIPTION_PURCHASE_FEES	Running Bill Now
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT	Preparing Bill Unit Data

Creating Bills

PCM_OP_BILL_MAKE_BILL creates a /bill object. PCM_OP_BILL_MAKE_BILL does the following:

Applies cycle fees.
Totals pending items in the /bill current total field.
Totals open items in the /bill previous total field.
If rollover correction is enabled, PCM_OP_BILL_MAKE_BILL can trigger the creation of rerating requests at the end of the delayed period if call detail records (CDRs) from the previous cycle borrow rollover from the current cycle.

To trigger the creation of rerating requests, PCM_OP_BILL_MAKE_BILL creates a notification event of type /event/notification/rollover_correction/rerate for the account being billed and possibly other accounts from which a bill unit was transferred into the account.
If rollover correction is enabled, PCM_OP_BILL_MAKE_BILL triggers rollover correction if CDRs borrow from the previous cycle borrow rollover from the current cycle.
If payment incentives are enabled, PCM_OP_BILL_MAKE_BILL calls PCM_OP_PYMT_GRANT_INCENTIVE which determines whether to grant the payment incentive and also calculates the incentive. PCM_OP_BILL_MAKE_BILL then retrieves the payment incentives and recalculates the affected bill, changing the balance impacts accordingly.
To determine the payment due date of a bill, PCM_OP_BILL_MAKE_BILL calls PCM_OP_BILL_POL_CALC_PYMT_DUE_T.
At the end of the last accounting cycle in a bill unit's billing cycle, PCM_OP_BILL_MAKE_BILL calls PCM_OP_BILL_POL_CHECK_SUPPRESSION to find out whether a bill should be suppressed.

If the PCM_OP_BILL_POL_CHECK_SUPPRESSION output flist indicates that the bill should be suppressed, PCM_OP_BILL_MAKE_BILL performs these tasks:
- Generates an /event/billing/suppression event.
- Extends the bill for another billing cycle instead of finalizing it.
If the PCM_OP_BILL_POL_CHECK_SUPPRESSION output flist indicates that the bill should not be suppressed, performs these tasks:
- If the output flist includes an exception to bill suppression, generates an /event/billing/suppression/exception object and then finalizes the bill. )
- If the result does not include an exception, finalizes the bill.
Whether or not the output flist indicates that the bill should be suppressed, PCM_OP_BILL_MAKE_BILL always subtracts 1 from the /billinfo counter that tracks the remaining cycles for which a bill has been manually suppressed (PIN_FLD_SUPPRESSION_CYCLES_LEFT) if the value in the counter is greater than 0.
When you use delayed billing, PCM_OP_BILL_MAKE_BILL performs some functions on the billing DOM and performs the rest of the functions at the end of the delay interval.

If the /billinfo object being billed is a parent, PCM_OP_BILL_MAKE_BILL creates a single /bill object for that parent, which includes all pending and open items from its nonpaying /billinfo objects.

When called by PCM_OP_BILL_MAKE_TRIAL_BILL during trial invoicing, PCM_OP_BILL_MAKE_BILL checks the value of the PIN_FLD_FLAGS field. If the value is PIN_INV_TYPE_PARENT, PCM_OP_BILL_MAKE_BILL calculates the adjusted, disputed, due, received, and writeoff values from each nonpaying child bill unit's /invoice/trial objects. The resulting billing totals are passed to the parent of the nonpaying child bill units.

Modifying a Bill Object

Use PCM_OP_BILL_POL_BILL_PRE_COMMIT to modify a bill object before committing it to the database. PCM_OP_BILL_POL_BILL_PRE_COMMIT is called by PCM_OP_BILL_MAKE_BILL, PCM_OP_BILL_MAKE_BILL_NOW, and PCM_OP_MAKE_BILL_ON_DEMAND.

Calculating When a Bill is Due

PCM_OP_BILL_POL_CALC_PYMT_DUE_T calculates the due date and the payment collection date of a bill (/bill object).

PCM_OP_BILL_POL_CALC_PYMT_DUE_T is called by PCM_OP_BILL_MAKE_BILL, PCM_OP_BILL_MAKE_CORRECTIVE_BILL, and PCM_OP_BILL_MAKE_BILL_NOW.

Note:

By default, the due date calculation is based on the time that billing is actually run, not on the time that a bill unit is ready to be billed.

Although configurable payment collection dates are used only for BRM-initiated payment, such as payments made by credit card and direct debit, they are calculated and stored for bills associated with all payment methods.

When called by PCM_OP_BILL_MAKE_BILL or PCM_OP_BILL_MAKE_CORRECTIVE_BILL, PCM_OP_BILL_POL_CALC_PYMT_DUE_T checks the PIN_FLD_PAYMENT_TERM value in the /payinfo object associated with the bill's /billinfo object and then performs the following operations:

If the field has no payment term ID or if the ID is 0, PCM_OP_BILL_POL_CALC_PYMT_DUE_T uses the default process of calculating the due date rather than using the bill run management process. The default process involves the fm_bill_pol_default_calc_due_t function and either the PIN_FLD_DUE_DOM value or the PIN_FLD_RELATIVE_DUE_T value in the /payinfo object.
If the payment term ID is greater than 0, PCM_OP_BILL_POL_CALC_PYMT_DUE_T uses one of the following bill run management functions to calculate the payment due date:
- fm_utils_add_n_days
- fm_bill_pol_add_n_bus_days
- fm_bill_pol_get_nthweekdayofmonth
For more information, see "Customizing Bill Due Date Calculations for Payment Terms".

After calculating the due date, PCM_OP_BILL_POL_CALC_PYMT_DUE_T checks the due date adjustment value in the PIN_FLD_DUE_DATE_ADJUSTMENT field of its input flist. If the value is greater than 0, it adds the value to the due date.

PCM_OP_BILL_POL_CALC_PYMT_DUE_T then returns the payment due date to PCM_OP_BILL_MAKE_BILL, which puts it in the PIN_FLD_DUE_T field of the /bill object.

PCM_OP_BILL_POL_CALC_PAYMT_DUE_T does not return any values. Its output flist, however, contains the PIN_FLD_DUE_T value, which PCM_OP_BILL_MAKE_BILL and PCM_OP_BILL_MAKE_CORRECTIVE_BILL use as the due date of the bill. By default, PCM_OP_BILL_POL_CALC_PAYMT_DUE_T uses this PIN_FLD_NAME input to calculate the due date based on the current time.

Customizing Bill Due Date Calculations for Payment Terms

You use payment terms to set due dates a specified number of days after the billing cycle end date or on a specified day of the month. You can customize how PCM_OP_BILL_POL_CALC_PAYMT_DUE_T calculates due dates for regular bills as well as for corrective bills.

When PCM_OP_BILL_MAKE_CORRECTIVE_BILL calls PCM_OP_BILL_POL_CALC_PAYMT_DUE_T to calculate the due date for a corrective bill, it identifies the bill from the PIN_FLD_NAME parameter. The possible values in PIN_FLD_NAME are PIN_OBJ_NAME_CORRECTIVE_BILL, PIN_OBJ_NAME_CORRECTIVE_BILL_NOW, PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND.

The value in PIN_FLD_NAME can be used to validate that PCM_OP_BILL_POL_CALC_PAYMT_DUE_T is calculating the due date for a corrective bill and, if necessary, provide custom logic to calculate due dates for the corrective bill.

For each payment term in your system, you must customize PCM_OP_BILL_POL_CALC_PYMT_DUE_T to specify which function and parameters to use to calculate the due dates of the bills associated with the payment term. To customize the function:

In the function's switch statement, add a case for each payment term defined in your /config/payment_term object.

The ID (constant expression) of each case should correspond to the ID of a payment term element in the PIN_FLD_PAYMENT_TERMS array of /config/payment_term. For example, if the array contains payment term element 1001, add case 1001 to the statement.

Note:

Case numbers 1 through 1000 are for BRM use only.
In each case, call the appropriate function with the appropriate parameters.

To calculate payment due dates for bills associated with a payment term, call one of these functions in the corresponding case in PCM_OP_BILL_POL_CALC_PYMT_DUE_T:

For payment terms that add any type of day (business, weekend, holiday, and so on) to the billing cycle end date, use this function:

fm_utils_add_n_days(n, &due_t)
- n specifies the number of days to add to the billing cycle end date. The value can be any positive integer.
- &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). n is added to this date.
For an example, see case TERM1 in the PCM_OP_BILL_POL_CALC_PYMT_DUE_T code sample.
For payment terms that add only business days to the billing cycle end date, use this function:

fm_bill_pol_add_n_bus_days(ctxp, n, "default", &due_t, ebufp)

For an example, see case TERM2 in the PCM_OP_BILL_POL_CALC_PYMT_DUE_T code sample.
- ctxp points to a communication channel between the client application and the database.
- n specifies the number of business days to add to the billing cycle end date. The value can be any positive integer.
- default is the case-sensitive name of the default billing calendar.
  
  To use a different calendar, replace default with the value in the PIN_FLD_NAME field of the /config/calendar object that you want to use.
  Note:
  - This function automatically skips weekends, so you do not need to include Sundays and Saturdays in billing calendars used only by this function.
  - If the CM cache does not contain the specified /config/calendar object, the function uses the default process of calculating the payment due date rather than the bill run management process.
- &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). n is added to this date.
- ebufp is a pointer to the error buffer that contains any errors that occur when the function tries to retrieve the specified calendar from the database.
For an example, see case TERM1 in the PCM_OP_BILL_POL_CALC_PYMT_DUE_T code sample.
For payment terms that specify a particular day of month, use this function:

fm_bill_pol_get_nthweekdayofmonth(d, n, &due_t)
- d is a day of the week. The value can be 0 (Sunday), 1 (Monday), 2 (Tuesday), 3 (Wednesday), 4 (Thursday), 5 (Friday), or 6 (Saturday).
- n is the ordinal rank of d in a month. The value can be 1 (first d of the month), 2 (second d of the month), 3 (third d of the month), or 4 (fourth d of the month).
- &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object).
  
  Note:
  
  If &due_t is after d n of the month, d n of the next month is used.
  
  For example, if d = 2, n = 3, and &due_t = April 19, 2004, the payment due date is April 20, 2004 (third Tuesday of April).
  
  But, if d = 2, n = 3, and &due_t = April 21, 2004, the payment due date is May 18, 2004 (third Tuesday of the next month).
For an example, see case TERM3 in the PCM_OP_BILL_POL_CALC_PYMT_DUE_T code sample.
You can also create custom functions to calculate payment due dates:

custom_function(custom_parameter, &due_t, ebufp)
- &due_t is a pointer to the end date of the current billing cycle (PIN_FLD_ACTG_LAST_T in the /billinfo object). The function must take due_t as a parameter.
- ebufp is a pointer to the error buffer that contains any errors that occur when the function tries to retrieve an object from the database. If the function uses BRM objects, this parameter is required.

The following sample is the default implementation of the fm_bill_pol_calc_pymt_due_t function in the fm_bill_pol_calc_pymt_due_t.c file:

switch (ptt)
    {
        case TERM1: /* Add 17 days to the billing cycle end date */
            fm_utils_add_n_days(17, &due_t);
            break;
    
        case TERM2: /* Add 14 business days to the billing cycle end date */
            fm_bill_pol_add_n_bus_days(ctxp, 14, "default", &due_t, ebufp);
            if (PIN_ERR_IS_ERR(ebufp))
            {
                PIN_ERR_LOG_EBUF(PIN_ERR_LEVEL_ERROR,
                "fm_bill_pol_calc_pymt_due_t: Error while using Payment Term 2", ebufp);
                goto cleanup;
            }
            /***********************************************************
            * If due_t is not changed, it means that there
            * are no /config/calendar objects available in the CM cache.
            * In this case, use the default TERM0 implementation.
            ***********************************************************/
            if (due_t == *eff_tp)
            {
                PIN_ERR_LOG_MSG(PIN_ERR_LEVEL_WARNING, "Switching to default calculation");
                fm_bill_pol_default_calc_due_t(&due_t, eff_tp, r_due_t, due_dom, ebufp);
            }
    
            break;
    
        case TERM3: /* Make the due date the 3rd Tuesday of the month */
            fm_bill_pol_get_nthweekdayofmonth( 2, 3, &due_t);
            break;
    
        /* Add implementation for handling more payment terms here */
    
        default: /* TERM0 for backward compatibility */
            fm_bill_pol_default_calc_due_t(&due_t, eff_tp, r_due_t, due_dom, ebufp);
    }

Customizing the Format of Bill and Invoice Numbers

By default, bill numbers for regular bills are B1-1, B1-2, B1-3, and so on. For corrective bills, the default numbering is CB1-1, CB1-2, CB1-3, and so on.

The default numbering takes the format PrefixDB_num-Seq_Number, where:

Prefix represents the prefix to be used for the bill.

For regular bills, BRM assigns BDB_num as the default prefix. DB_num indicates the number of the database in which the original bill is stored. For example, when DB_num is 1, 3, or 7, the prefixes for regular bills are B1, B3, or B7.

For corrective bills, BRM assigns CBDB_num as the default prefix. For example, when DB_num is 1, 3, or 7, the prefixes for corrective bills are CB1, CB3, or CB7.
Seq_Number is the unique sequence number from the appropriate /data/sequence object. BRM supports two types of /data/sequence objects, (PIN_SEQUENCE_TYPE_BILL_NO and PIN_SEQUENCE_TYPE_CORR_BILL_NO).

Note:

Of these two /data/sequence objects, PIN_SEQUENCE_TYPE_CORR_BILL_NO is used exclusively for corrective bills.

For regular bills, BRM uses the unique sequence number from the PIN_SEQUENCE_TYPE_BILL_NO /data/sequence object.

For corrective bills, you can select to use the unique sequence number from either of the two /data/sequence objects, (PIN_SEQUENCE_TYPE_BILL_NO and PIN_SEQUENCE_TYPE_CORR_BILL_NO).

A regular bill and all its corrective bills have the same POID (the bill object identifier in the BRM database). As a result, you can use the bill POID to retrieve the complete set of bills, that is, the corrected bill and its prior bills.

You can customize the prefix and the numbering sequence for bills. Use PCM_OP_BILL_POL_SPEC_BILLNO to customize bill numbers. By default, if the bill number is in the input flist, the opcode returns it. Otherwise, the opcode generates a bill number based on the bill POID.

To use a different bill number format, use PCM_OP_WRITE_FLDS to modify the PIN_FLD_HEADER_STR field in the /data/sequence object. For example, to use a bill number format with numbers only and no letters, such as 100, 101, 102, and so on, set PIN_FLD_HEADER_STR to two colons (::).

PCM_OP_BILL_POL_SPEC_BILLNO assigns a default number to the /account object in the database. This opcode is called by the pin_fld_billno utility and uses the default implementation information to create a unique billing number. The billing number is then returned to the object in the database.

PCM_OP_BILL_POL_SPEC_BILLNO is called by PCM_OP_BILL_MAKE_BILL, PCM_OP_BILL_MAKE_BILL_NOW, and PCM_OP_MAKE_BILL_ON_DEMAND

Running Bill Now

Bill now runs PCM_OP_BILL_MAKE_BILL_NOW on a specified bill unit (/billinfo object) immediately. If a bill unit is not specified, this opcode creates one /bill for each /billinfo for the given account.

The PIN_FLD_NAME field in the /bill object contains the type of billing the /bill object is for:

Regular billing
Billing on purchase
Bill now
Bill now for the current cycle
Bill now on the next cycle

The last two options enable the creation of two bills during the delayed period if your customer management system (CMS) supports that functionality. One bill is generated for the current cycle charges; the other is generated for the next cycle charges.

PCM_OP_BILL_MAKE_BILL_NOW performs the following tasks:

Applies cycle fees, including deferred fees and folds, by calling the following opcodes:
- PCM_OP_SUBSCRIPTION_PURCHASE_FEES
- PCM_OP_SUBSCRIPTION_CYCLE_ARREARS
- PCM_OP_SUBSCRIPTION_CYCLE_FOLD
- PCM_OP_SUBSCRIPTION_CYCLE_FORWARD
If called for a service of a sponsored account, PCM_OP_BILL_MAKE_BILL_NOW calls PCM_OP_BILL_CREATE_SPONSORED_ITEMS The bill produced is for the pending items for the specified service of the sponsored account.
If called on a nonpaying bill unit, creates one bill for the parent bill unit that includes only the items from the nonpaying bill unit. In such cases, the PIN_FLD_GROUP_OBJ field in the /event/billing/cycle/tax object contains the POID of the nonpaying /billinfo object. If called on a parent bill unit, creates one bill that contains a total of the items from both the parent and any nonpaying bill units. This includes any nonpaying bill unit cycle taxes. In such cases, the PIN_FLD_GROUP_OBJ field contains the POID of the parent /billinfo object.
Finalizes the bill.
If configured, calls PCM_OP_BILL_CYCLE_TAX to calculate taxes.

Note:

Bill Now ignores the cycle_tax_interval value in the CM's configuration file (pin.conf) and always rolls activities for each nonpaying bill unit into the parent bill unit and calculates taxes for the parent only.
If configured, prorates cycle arrears and cycle forward arrears fees.

Bill Now does not generate invoices. You must separately run the pin_inv_accts utility or the pin_bill_day script.

Customizing Bill Now

By default, Bill Now generates a bill that includes all pending items. You can customize Bill Now to include only specified pending items. To change the default behavior, edit the search criteria in PCM_OP_BILL_POL_GET_PENDING_ITEMS

If the bill is produced for the parent bill unit, this bill, by default, includes pending items from the parent and all nonpaying child bill units. To include items for just one of the nonpaying bill units, add functionally to PCM_OP_BILL_POL_GET_PENDING_ITEMS to filter out the rest of the items for the bill units associated with the parent bill unit.

Running Bill Now for a Service

You can extend your customer management application to generate a Bill Now type of bill for a specific service. When the selected service belongs to a member account in a charge or discount sharing group, a bill can be generated for the owner account of the sharing group.

Use the following opcodes:

PCM_OP_BILL_MAKE_BILL_NOW
PCM_OP_BILL_CREATE_SPONSORED_ITEMS
PCM_OP_BILL_POL_GET_PENDING_ITEMS

Applying Discounts and Folds with Bill Now

To apply discounts or folds, your customer management application needs one of the values listed in Table 6-2 in the PIN_FLD_FLAGS field in the PCM_OP_BILL_MAKE_BILL_NOW input flist:

Table 6-2 Values to Apply Folds, Discounts, or Both

To Include:	Set the Value To:
Folds	16
Discounts	32
Folds and discounts	48 (Add the values to get both actions.)

Note:

A billing-time discount is not allowed when Bill Now includes only selected items or a specific service.
When the billing-time discount flag is specified, you must ensure that a fold charge is configured for the specific balance used by the billing-time discount. In addition to the billing-time discount flag, you must also specify the fold flag to fold the balance used by the discount. If a fold charge is not configured for the balance used by the discount or if the fold flag is not specified, the billing-time discount is applied again during regular billing.
When the fold flag is specified, all balances are folded, even those not used by the billing-time discount. For example, when closing an account, you can specify the fold flag to fold all the balances. In other cases, you might not want to fold all the balances. In such cases, do not specify the billing-time discount or fold flag if there are other balances that are not used by the billing-time discount.

Changing the Bill Now Due Date

The default due date for a bill created with Bill Now is calculated as the billing cycle length minus one day after Bill Now is run:

date_of_bill + billing_cycle_length - one_day

For example, if you run Bill Now on June 2, and the billing cycle is one month, the bill is due July 1.

To change the Bill Now due date to, for example, date_of_bill + billing_cycle_length - 7 days, you customize the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode. See BRM Opcode Guide.

On-Purchase Billing

PCM_OP_BILL_MAKE_BILL_ON_DEMAND creates a /bill object immediately when a bundle or package that is flagged for on-purchase billing is purchased.

To create a bill on purchase for a bundle or package, the PCM_FLD_ON_DEMAND_INFO field must be set in the /deal or /plan objects.

Use PDC to set this field by selecting Bill on Purchase in the General Information section of the bundle or package. Use Pricing Center to set this field by selecting Bill on Demand on the plan or deal Attributes tab.

Creating /item/sponsor Objects

Use PCM_OP_BILL_CREATE_SPONSORED_ITEMS to create /item/sponsor objects for sponsoring accounts. These item objects include charges from the sponsored accounts. PCM_OP_BILL_CREATE_SPONSORED_ITEMS sends that information to PCM_OP_BILL_POL_GET_PENDING_ITEMS

PCM_OP_BILL_CREATE_SPONSORED_ITEMS is called by PCM_OP_BILL_MAKE_BILL_NOW when it creates a bill for a sponsoring account. PCM_OP_BILL_CREATE_SPONSORED_ITEMS can also be run separately. In this case, the returned list of items can be passed to PCM_OP_BILL_MAKE_BILL_NOW to produce a bill for each sponsor account.

If PCM_OP_BILL_CREATE_SPONSORED_ITEMS is called, billing time discounts and folds are not applied.

Customizing Billing

See the following topics:

Customizing the Minimum Amount to Charge

You set the default minimum amount to charge a customer in the CM pin.conf file minimum entry. To check a batch of charges and refunds for any amounts below the minimum before charging and refunding customers, use PCM_OP_PYMT_POL_PRE_COLLECT. The PIN_FLD_SESSION_OBJ field in the input flist references the type of session in which the event occurred: either /event/billing/batch/refund or /event/billing/batch/payment, depending on the batch type.

Note:

Ensure that the minimum credit card charge does not conflict with the minimum amount to collect.

You can change the minimum credit card charge amount by modifying the default minimum payment amount in PCM_OP_PYMT_POL_PRE_COLLECT

Before performing the charges and refunds, PCM_OP_PYMT_COLLECT allocates the PIN_FLD_CHARGE array elements to open items and then calls PCM_OP_PYMT_POL_PRE_COLLECT.

PCM_OP_PYMT_POL_PRE_COLLECT then checks each element of the input PIN_FLD_CHARGES array to ensure:

The result of selecting open items for allocating charges is set to PIN_SELECT_RESULT_PASS.
The amount charged is greater than or equal to the minimum payment amount.
The amount refunded is greater than or equal to the minimum and the account has a negative balance.
The value of the input PIN_FLD_COMMAND field is valid.

By default, the results can be the following:

If the amount charged is less than the minimum amount, PCM_OP_PYMT_POL_PRE_COLLECT sets the PIN_FLD_DESCR field to “Below minimum" and the result to PIN_CHARGE_RES_FAIL_NO_MIN.
If the amount refunded is less than the minimum amount, PCM_OP_PYMT_POL_PRE_COLLECT sets the PIN_FLD_DESCR field to “Below minimum" and the result to PIN_CHARGE_RES_FAIL_NO_MIN.
If PIN_FLD_COMMAND is set to PIN_CHARGE_CMD_REFUND and the account balance is zero or higher, PCM_OP_PYMT_POL_PRE_COLLECT sets the PIN_FLD_DESCR field to “No credit available" and the result to PIN_CHARGE_RES_NO_CREDIT_BALANCE.

You can change the minimum credit card charge amount by modifying the default minimum payment amount in PCM_OP_PYMT_POL_PRE_COLLECT.

You can also customize PCM_OP_PYMT_POL_PRE_COLLECT to retrieve soft descriptor information that enables you to display the name under which you do business (your DBA name), charge offer name, and customer service number on your customer's checking account or credit card statement. See "Adding Soft Descriptors to Invoices".

Customizing Accounting Cycles

To customize accounting cycles, use PCM_OP_BILL_POL_SPEC_FUTURE_CYCLE. This opcode can be modified to calculate the next and future accounting cycles appropriate for your business policy.

PCM_OP_BILL_POL_SPEC_FUTURE_CYCLE is called from PCM_OP_BILL_MAKE_BILL or PCM_OP_CUST_SET_BILLINFO whenever BRM calculates PIN_FLD_ACTG_NEXT_T and PIN_FLD_ACTG_FUTURE_T.

By default, PIN_FLD_ACTG_NEXT_T is calculated if you do not specify it in the input flist, but PIN_FLD_ACTG_FUTURE_T will always be calculated based on PIN_FLD_ACTG_NEXT_T.

PCM_OP_BILL_POL_SPEC_FUTURE_CYCLE can be modified to calculate the next and future accounting cycles appropriate for your business policy.

To customize the time interval for applying cycle forward and cycle arrears fees for a specified charge offer, use PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL.

PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL is called by PCM_OP_SUBSCRIPTION_APPLY_RATE, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD, and PCM_OP_SUBSCRIPTION_CYCLE_ARREARS.

PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL is an empty hook. If you customize this policy opcode to pass a PIN_FLD_FLAGS output flist field set to 1, the charge offer will be forced into a long cycle. This adds any extra days to the next accounting cycle.

Customizing How to Bill Events That Occur between Billing Cycles

Use the PCM_OP_ACT_POL_CONFIG_BILLING_CYCLE policy to specify in which billing cycle to apply an event when an event occurs between the end of a billing cycle and when billing applications are run.

By default, this opcode selects the current month's bill, but you can customize this opcode to select the previous month's bill.

You specify how long after the billing cycle ends that new events are included in the previous month's bill by using the ConfigBillingCycle business parameter in the billing instance of the /config/business_params object. See "Billing Cycle Override for Delayed Billing" in BRM Configuring and Running Billing.

PCM_OP_ACT_POL_CONFIG_BILLING_CYCLE is called by PCM_OP_ACT_USAGE when both of the following are true:

The value of the ConfigBillingCycle business parameter is greater than 0.
The value of ConfigBillingCycle is less than or equal to the value of the ConfigBillingDelay business parameter.

If ConfigBillingCycle is greater than ConfigBillingDelay, the CM returns an error.

You can customize PCM_OP_ACT_POL_CONFIG_BILLING_CYCLE to point qualifying events to either the previous month's bill or the current month's bill.

Customizing Credit Limit and Consumption Rules

PCM_OP_BILL_SET_LIMIT_AND_CR sets the credit limit and consumption rules for both currency and noncurrency sub-balances.

By default, PCM_OP_BILL_SET_LIMIT_AND_CR sets or changes the credit limit and consumption rules in the account's default /balance_group object. To set credit limit and consumption rules for any of the other billing entities associated with the object, specify them with the optional PIN_FLD_BAL_GRP_OBJ field passed in the input flist.

PCM_OP_BILL_SET_LIMIT_AND_CR includes the following flags:

If the PCM_OPFLG_READ_RESULT flag is set, all fields in the event object are returned in addition to the POID.
If the PCM_OPFLG_CALC_ONLY flag is set, no fields in the database are changed and the event object is not actually created. The fields that would have been used to create the event object are returned to the caller.
If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/limit object is created to record the details of the operation.

Customizing Client Applications to Modify Fixed Thresholds

To modify any fixed threshold values in a customer's credit limit data, you must customize your client application to call the PCM_OP_BILL_SET_LIMIT_AND_CR opcode.

You pass the fixed threshold values in the input flist's PIN_FLD_THRESHOLDS array. Each fixed value has a separate PIN_FLD_THRESHOLD flist entry in the array.

When the opcode receives fixed threshold values in its input flist, PCM_OP_BILL_SET_LIMIT_AND_CR updates the amount, refreshes the cache of credit limit data, and generates a ModifyBalanceGroup business event for ECE.

About Currency Conversion

Currency conversion is performed by the following opcodes:

PCM_OP_BILL_CURRENCY_CONVERT_AMOUNTS converts the currency according to the conversion rate defined in the /config/currency/conversionrates object. You can set multiple time periods for conversion rates.

For example, this opcode is used to convert currencies when an account using EMU currency is set up with a primary currency and a secondary currency.

BRM supports conversion only between the euro and EMU currencies. Conversion between two EMU currencies or between any other currencies is not supported.

PCM_OP_BILL_CURRENCY_CONVERT_AMOUNTS fails if the specified time is not in the time range or if the source or destination currency is invalid. The ERROR_NOT_FOUND error code is returned.
PCM_OP_BILL_CURRENCY_QUERY_CONVERSION_RATES retrieves the conversion rates from the /config/currency/conversionrates object. This opcode is called by PCM_OP_BILL_CONVERT_AMOUNTS.

It returns the conversion rate, start and end time of the time range for this rate and currency operator information.

PCM_OP_BILL_CURRENCY_QUERY_CONVERSION_RATES fails if no conversion rate is specified between the source and destination currency types. The ERROR_NOT_FOUND error code is returned.

Managing Bill Units

See the following topics:

Creating Bill Units

Use PCM_OP_CUST_CREATE_BILLINFO to create bill units.

You can set each bill unit's billing cycle fields, such as the accounting type, the billing frequency, and the billing day of month (DOM), by passing information in the opcode's input flist fields.

If the object is successfully created, the PCM_OP_CUST_CREATE_BILLINFO output flist contains:

The POID of the /account object to which the bill unit belongs.
PIN_FLD_BILLINFO array that specifies the billing information that is created.

For information about setting up relationships among bill units participating in hierarchies and charge and discount sharing groups, see "Setting Up Hierarchical and Sharing Relationships among Bill Units" .

After creating a bill unit, you must associate it with the account balances for which the bill is created. To do this, the account must have multiple balance groups so that different balances can be linked to different bills. You create multiple balance groups when you create packages in PDC or plans in Pricing Center.

Setting the Billing Day of Month

A bill unit's billing day of month (DOM) is the day on which its accounting cycle and billing cycle begin.

Note:

The billing DOM and the accounting DOM are the same day, which is specified in the PIN_FLD_ACTG_CYCLE_DOM field of the /billinfo object.

To set a bill unit's billing DOM, BRM uses the following values in this order of priority:

The DOM assigned to the billing segment. BRM assigns the DOM set for the billing segment in the /config/billing_segment object. For more information, see the chapter about billing in BRM Opcode Guide.

Note:

To customize how BRM assigns the DOM according to the billing segment, see the chapter about billing in BRM Opcode Guide.
The DOM used by the first bill unit in the account. If a DOM is not assigned to the billing segment, BRM uses the DOM of the first bill unit in the account.
Default setting in the CM pin.conf file. If a DOM is not assigned to the billing segment and is not available from another bill unit, the DOM is set to the value assigned in the actg_dom entry in the CM configuration file (BRM_home/sys/cm/pin.conf, where BRM_home is the directory in which the BRM server software is installed).
The current date. If a DOM is not available from the billing segment, other bill units, or the CM pin.conf file, BRM sets the DOM to the current date.

For example, if an account was created with two bill units, BU1 that has an assigned DOM and BU2 that does not have a DOM assigned, BRM assigns a DOM to BU2 as follows:

If BU2 is the second bill unit in the account, BRM uses the DOM of BU1.
If BU2 is the first bill unit in the account, BRM uses the DOM specified in the CM pin.conf file. If a value is not set in the CM pin.conf file, the DOM is set to the current date.

Updating Bill Units

Use PCM_OP_CUST_SET_BILLINFO to update billing information in existing bill units. This opcode calls policy opcodes to permit customization and perform validations. Set the value of the PIN_FLD_POID field in the PIN_FLD_BILLIFO array to -1, which causes PCM_OP_CUST_SET_BILLINFO to call PCM_OP_CUST_CREATE_BILLINFO before calling the policy opcodes.

PCM_OP_CUST_SET_BILLINFO updates an existing PIN_FLD_BILLINFO array associated with a specified account by setting new values for the array fields as specified in the input flist. Any PIN_FLD_BILLINFO array fields not included in the input flist are left unchanged.

PCM_OP_CUST_SET_BILLINFO calls PCM_OP_CUST_POL_PREP_BILLINFO to prepare the updated billing information for validation and then calls PCM_OP_CUST_POL_VALID_BILLINFO to validate the information.

Use the following opcodes to customize PCM_OP_CUST_SET_BILLINFO functionality:

Use PCM_OP_CUST_POL_PREP_BILLINFO to prepare bill unit data. See "Preparing Bill Unit Data".
Use PCM_OP_CUST_POL_VALID_BILLINFO to validate bill unit data. See "Validating Bill Unit Data".

Both of these opcodes are called by PCM_OP_CUST_SET_BILLINFO.

You can set each bill unit's billing cycle fields, such as the accounting type, the billing frequency, and the billing DOM, by passing information in the opcode's input flist fields.

Preparing Bill Unit Data

PCM_OP_CUST_POL_PREP_BILLINFO processes the account billing fields in the /billinfo object during customer account creation or while updating billing information to prepare for validation. For information about the PREP opcodes, see in BRM Developer's Guide.

This opcode is called by PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT and PCM_OP_CUST_SET_BILLINFO.

The opcode's main responsibility includes:

Assigning default values for the billing cycle length, primary currency, and accounting type, if they are not passed in the input flist. See "Assigning Default Billing Information".
Determining and assigning the billing DOM. See "Assigning Billing DOMs to Bill Units".

PCM_OP_CUST_POL_PREP_BILLINFO prepares the following billing information:

Account POID
Event ending timestamp
Bill unit POID
Payment method
Bill unit name
New or changed billing DOM
Old billing DOM
Accounting type: open item accounting or balance forward accounting
Next billing date
Billing frequency (based on the number of accounting cycles)
Parent bill unit
Currency used
Secondary currency used
Billing segment ID

PCM_OP_CUST_POL_PREP_BILLINFO provides a mechanism for taking the information passed to PCM_OP_CUST_SET_BILLINFO and processing the fields before their validation by PCM_OP_CUST_POL_VALID_BILLINFO. See "Validating Bill Unit Data".

Processing includes adding any missing fields whose values are derived or generated by PCM_OP_CUST_POL_PREP_BILLINFO, and forcing fields to predefined values independent of what you specified. You specify fields on the input flist, and this opcode returns the processed version of the data on the output flist. Validity of the field values is checked by PCM_OP_CUST_POL_VALID_BILLINFO.

If PCM_OP_CUST_POL_PREP_BILLINFO cannot derive all of the necessary fields because the values you specified are incorrect, no error is returned. Instead, the derived fields are returned on the output flist with a default value, and PCM_OP_CUST_POL_VALID_BILLINFO is called to detect the incorrect customer data and return the validation error to the calling application. This enables the calling application to get the details of the validation error instead of receiving an incorrect ebuf error. If PCM_OP_CUST_POL_PREP_BILLINFO cannot generate a necessary field or encounters other internal problems, it returns an ebuf error.

How BRM Calculates Long Billing Cycles

BRM uses the following formula to calculate long billing cycles:

Use a short cycle unless one of the following is true:

Future billing day of month > current billing day of month

AND

(Future billing day of month - current billing day of month) < 15
Future billing day of month < current billing day of month

AND

(Current billing day of month - future billing day of month) > 15

Examples:

The following example is shown in Figure 6-1. If the current billing DOM is 1 and the future billing DOM is 10:

10 > 1

10 - 1 = 9

Use a long cycle.

Figure 6-1 Long Cycle Example 1

Description of "Figure 6-1 Long Cycle Example 1"

The following example is shown in Figure 6-2. If the current billing DOM is 1 and the future billing DOM is 20:

20 > 1

20 - 1 = 19

Use a short cycle.

Figure 6-2 Short Cycle Example 1

Description of "Figure 6-2 Short Cycle Example 1"

The following example is shown in Figure 6-3. If the current billing DOM is 10 and the future billing DOM is 1:

1 < 10

10 - 1 = 9

Use a short cycle.

Figure 6-3 Short Cycle Example 2

Description of "Figure 6-3 Short Cycle Example 2"

The following example is shown in Figure 6-4. If the current billing DOM is 20 and the future billing DOM is 1:

1 < 20

20 - 1 = 19

Use a long cycle.

Figure 6-4 Long Cycle Example 2

Description of "Figure 6-4 Long Cycle Example 2"

Setting the Billing DOM According to the Payment Method

You can set the billing DOM for new customers according to the payment method. For example, you can set up all accounts that pay for bills using the invoice payment method to be billed for those bills on the same day. To do this, customize the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode. Also, use event notification to implement your customization when existing customers change payment methods.

Assigning Default Billing Information

PCM_OP_CUST_POL_PREP_BILLINFO prepares the billing information for online account creation by implementing the following default values:

If not already specified in the input flist, the PIN_FLD_BILL_WHEN field is set to the value specified in the Connection Manager (CM) pin.conf file's bill_when entry. If no value is found in the pin.conf file, it is defaulted to 1.
If not already specified in the input flist, the PIN_FLD_CURRENCY field is set to the value specified in the CM pin.conf file's currency entry. If no value is specified, the field is set to the currency associated with the system account.
If not already specified in the input flist, the PIN_FLD_ACTG_TYPE field is set to the value specified in the CM pin.conf file's actg_type entry. If no value is found in the pin.conf file, the field is set to 2 (balance-forward accounting).
If the primary currency is EURO, the PIN_FLD_CURRENCY_SECONDARY field is set to the default secondary currency.

Determining the Accounting Type

BRM determines a bill unit's accounting type by reading and using the following accounting type settings in this order:

Client application or opcode flist setting. You can specify a bill unit's accounting type when you create or modify an account in Billing Care or Customer Center.

If you use a custom client application, you can specify a bill unit's accounting type by passing it in the PIN_FLD_ACTG_TYPE input flist field of the following opcodes:
- PCM_OP_CUST_COMMIT_CUSTOMER
- PCM_OP_CUST_MODIFY_CUSTOMER
- PCM_OP_CUST_UPDATE_CUSTOMER
Default setting in the Connection Manager (CM) configuration file. You can specify a default accounting type by using the actg_type entry in the CM's configuration file (BRM_home/sys/cm/pin.conf). BRM uses the default setting during account creation only if an accounting type is not passed in the input flist.
System-wide accounting type. If an accounting type is not passed in the input flist nor set in the CM pin.conf file, BRM automatically sets the bill unit's accounting type to balance forward accounting.

Assigning Billing DOMs to Bill Units

PCM_OP_CUST_POL_PREP_BILLINFO assigns a billing DOM to a bill unit based on the following order of priority:

The DOM assigned to the billing segment. The opcode assigns the DOM set for the billing segment in the /config/billing_segment object. For more information, see "Assigning Billing DOMs Based on the Billing Segment".

Note:

To customize how the opcode assigns the DOM according to the billing segment, see "Customizing the DOM Assignment Process".
The DOM used by the other bill units in the account. If a DOM is not assigned to the billing segment, the opcode assigns the DOM used by the other bill units in the account.
Default setting in the Connection Manager pin.conf file. If a DOM is neither assigned to the billing segment nor available from another bill unit, the DOM is set to the value assigned in the actg_dom entry in the CM configuration file (BRM_home/sys/cm/pin.conf, where BRM_home is the directory in which the BRM server software is installed).
The current date. If a DOM is not available from the billing segment, other bill units, or the CM pin.conf file, the opcode assigns the DOM to the current date passed in the input flist's PIN_FLD_END_T field.

For example, if an account was created with two bill units, BU1 that has an assigned DOM and BU2 that does not have an assigned DOM, the opcode assigns a DOM to BU2 as follows:

If BU2 is the second /billinfo object associated with the /account object, the opcode assigns the DOM used by BU1.
If BU2 is the first /billinfo object associated the /account object, the opcode assigns the DOM set in the CM pin.conf file. If a value is not set in the CM pin.conf file, the DOM is set to the current date passed in the input flist's PIN_FLD_END_T field.

Assigning Billing DOMs Based on the Billing Segment

When a /config/billing_segment object exists in the CM cache and contains an array of billing segments, PCM_OP_CUST_POL_PREP_BILLINFO performs the following tasks:

If the input PIN_FLD_BILLING_SEGMENT field does not contain a value or contains 0, PCM_OP_CUST_POL_PREP_BILLINFO sets the output PIN_FLD_BILLING_SEGMENT field to 0. This triggers BRM to use the default process rather than the bill cycle management process of assigning a billing DOM to the bill unit.
If the input PIN_FLD_BILLING_SEGMENT field does contain a value other than 0 but the input PIN_FLD_ACTG_FUTURE_DOM field does not contain a value, PCM_OP_CUST_POL_PREP_BILLINFO uses the bill cycle management process of assigning a billing DOM to the bill unit:
- By default, the opcode assigns the first open DOM in the specified billing segment, starting with the current DOM.
- Alternatively, the opcode can use a weighted average calculation to select a billing DOM. See "Customizing the DOM Assignment Process".
  
  Note:
  
  If the input PIN_FLD_ACTG_FUTURE_DOM field does contain a value, that value becomes the billing DOM unless it is closed. If it is closed, PCM_OP_CUST_POL_VALID_BILLINFO returns a validation error.

The default DOM assignment process rather than the bill cycle management process is also used in these situations:

The /config/billing_segment object is not in the CM cache.
In the cached /config/billing_segment object, no DOMs are associated with the billing segment ID specified in the input PIN_FLD_BILLING_SEGMENT field.

Customizing the DOM Assignment Process

To increase the probability that the assigned billing DOM has the lightest billing load of all the open days in a billing segment, PCM_OP_CUST_POL_PREP_BILLINFO can optionally use a weighted average calculation to select a DOM. The calculation should factor in the total billing-run processing time of each open DOM. This information is stored in the /config/billing_segment object.

A sample weighted average calculation is included in the opcode file (fm_cust_pol_prep_billinfo.c).

To use the calculation, PCM_OP_CUST_POL_PREP_BILLINFO must call the fm_cust_pol_prep_billinfo_get_dom_from_process_t_from_cache function to assign a DOM to a bill unit. (By default, the opcode calls fm_cust_pol_prep_billinfo_get_next_dom_from_cache.)

The sample calculation works as follows:

Billing segment X, to which bill unit Y belongs, has the following open DOMs and associated billing-run processing times as shown in Table 6-3:

Table 6-3 Sample Billing DOMs

DOM/Process	Value	Value	Value	Value	Value
Open Billing DOMs	5	11	16	20	75
PIN_FLD_TOTAL_PROCESS_T (in seconds)	20000	30000	15000	45000	25000

DOM/Process

Value

Open Billing DOMs

PIN_FLD_TOTAL_PROCESS_T

(in seconds)

20000

30000

15000

45000

25000

Using the total number of seconds in two DOMs (172,800) as a constant, PCM_OP_CUST_POL_PREP_BILLINFO divides the constant by each DOM's total billing-run processing time as shown in Table 6-4:

Table 6-4 Sample Bill-Run Processing Times

DOM/Process

Value

Open Billing DOMs

PIN_FLD_TOTAL_PROCESS_T

(in seconds)

20000

30000

15000

45000

25000

172,800/

PIN_FLD_TOTAL_PROCESS_T

(results are rounded down to nearest whole number)

PCM_OP_CUST_POL_PREP_BILLINFO then adds the results and uses their sum as a seed value to generate a random number. In this case, the sum is 33. Assume the random number is 21.

PCM_OP_CUST_POL_PREP_BILLINFO subtracts the random number from the result in the first column of the table. If the remainder is less than 0, the opcode assigns the column's DOM to the bill unit. If the remainder is greater than 0, the opcode subtracts the remainder from the result in the next column. It continues this process until it gets a remainder that is less than 0 as shown in Table 6-5:

Table 6-5 Sample Values for Billing DOMs

DOM/Process	Value	Value	Value	Value	Value
Open Billing DOMs	5	11	16	20	27
PIN_FLD_TOTAL_PROCESS_T (in seconds)	20000	30000	15000	45000	25000
172,800/ PIN_FLD_TOTAL_PROCESS_T (results are rounded down to nearest whole number)	8	5	11	3	6
First Quotient - Random Number	21 - 8 = 13	NA	NA	NA	NA
Is result less than 0? No	13 > 0	13 - 5 = 8	NA	NA	NA
Is result less than 0? No	NA	8 > 0	8 - 11 = -3	NA	NA
Is result less than 0? Yes	NA	NA	-3 < 0	NA	NA

Based on the final result of this example calculation, PCM_OP_CUST_POL_PREP_BILLINFO sets the PIN_FLD_ACTG_FUTURE_DOM in the output flist for bill unit Y to 16.

Validating Bill Unit Data

PCM_OP_CUST_POL_VALID_BILLINFO validates an account's billing information in the /billinfo object passed to it by PCM_OP_CUST_POL_PREP_BILLINFO during customer account creation or administrative update.

The billing information can include the following:

Payment method
Parent /billinfo object
Next bill time
Currency used
Billing frequency
Accounting cycle duration
Accounting type
Billing segment ID

By default, PCM_OP_CUST_POL_VALID_BILLINFO validates the PIN_FLD_ACTG_TYPE, PIN_FLD_ACCOUNT_NO, and PIN_FLD_PAY_TYPE fields according to the criteria contained in the /config/fld_validate object. Invalid pay types result in an error.

Valid payment methods are listed in the BRM_home/include/pin_cust.h file as BILL_TYPE. Include the pin_cust.h file in the applications that call PCM_OP_CUST_POL_VALID_BILLINFO.

Validating Billing Segment Information

If the PIN_FLD_BILLING_SEGMENT field in the PCM_OP_CUST_POL_VALID_BILLINFO input flist contains a value other than 0, PCM_OP_CUST_POL_VALID_BILLINFO performs the following tasks:

It verifies that the billing segment identified in the PIN_FLD_BILLING_SEGMENT field is in the /config/billing_segment object.
If the billing segment is in the /config/billing_segment object, PCM_OP_CUST_POL_VALID_BILLINFO checks the status of the billing DOM in the input flist PIN_FLD_ACTG_FUTURE_DOM field for the specified billing segment.

PCM_OP_CUST_POL_VALID_BILLINFO logs a validation error and returns a message to the user interface in these situations:

The specified billing segment is not in the /config/billing_segment object.
The status of the specified billing DOM is closed.

Suspending and Resuming Billing of Closed Accounts

To suspend and resume billing of a bill unit in a closed account, see the following:

Suspending Billing of Closed Accounts

To suspend billing of a closed account, use PCM_OP_BILL_POL_POST_BILLING.

This opcode is called by PCM_OP_BILL_MAKE_BILL. It enables you to perform custom processing on a bill unit at the time of billing.

By default, PCM_OP_BILL_POL_POST_BILLING suspends billing of a specified bill unit in a closed account that has the following characteristics:

Zero balance due for all bill units (total balance due of all open and pending items).
For account hierarchies, the balance due amount includes the open and pending item totals of every nonpaying child bill unit.
No billable activity since the previous bill was generated.

If the bill unit has nonpaying child bill units, they are suspended, too.

For accounts with a multimonth billing cycle, the default implementation of this opcode suspends billing at the end of the last accounting cycle.

If delayed billing is enabled, PCM_OP_BILL_POL_POST_BILLING suspends billing at the end of the billing delay interval.

To indicate billing is suspended, this opcode sets the PIN_FLD_BILLING_STATUS field in the /billinfo object to inactive.

PCM_OP_BILL_POL_POST_BILLING returns the POID of the /billinfo object.

Resuming Billing When Closed Accounts Are Reactivated

When an account's status is changed from closed to active, PCM_OP_CUST_SET_STATUS calls an internal opcode to resume suspended billing.

The opcode sets the PIN_FLD_BILLING_STATUS field in the account's bill units to active and resets the billing information. For example, it resets the last billing date (PIN_FLD_LAST_BILL_T), next billing date (PIN_FLD_NEXT_BILL_T), last accounting cycle (PIN_FLD_ACTG_LAST_T), and next accounting cycle (PIN_FLD_ACTG_NEXT_T).

Note:

The account status is not the same as the account's billing status. For example, an account's status can be active while its billing status is inactive.

BRM does the following:

Resets the account bill unit billing status to active (PIN_BILL_ACTIVE).

Note:

A bill unit with suspended billing has the billing status set to inactive (PIN_BILL_INACTIVE).
Resets the account bill unit's next billing date (PIN_FLD_NEXT_BILL_T) based on the account's billing day of month before billing was suspended. For example, if the billing day of month was the first of every month before billing was suspended, the billing day of month is set to the first of every month when billing is resumed.
Resets the billing start date (PIN_FLD_START_T) in the /bill object to the current time (when billing is resumed).

Note:

BRM does not automatically resume suspended billing for nonpaying bill units. To do that, you must reactivate the accounts that contain those bill units.

When you resume billing, billing is run on the next scheduled billing date. This is true even if billing would have been run when billing was suspended. That is, billing is not run immediately to accommodate billing that was missed during suspension.

Deleting Bill Units

To delete bill units, write custom code that calls PCM_OP_CUST_DELETE_BILLINFO.

If the specified bill unit is a paying parent, this opcode automatically deletes any nonpaying child bill units associated with it.

Note:

You cannot delete a bill unit that has pending payments.

If successful, the PCM_OP_CUST_DELETE_BILLINFO output flist contains:

PIN_FLD_POID field set to the account POID of the /account object that is deleted.
PIN_FLD_BILLINFO array that specifies the billing information that is deleted.

Setting Up Hierarchical and Sharing Relationships among Bill Units

To set up hierarchical and sharing relationships among bill units, see the following sections:

Setting Up Hierarchical Relationships among Bill Units

In account hierarchies, the bill units are the paying or nonpaying entities. To configure accounts in a hierarchy to pay their own charges or to roll their charges up to other accounts in the hierarchy, you must configure their bill units to be paying or nonpaying parents or children of one another.

Note:

Bill unit hierarchies can, but do not have to, match account hierarchies. Bill units in accounts that belong to different account hierarchies can form a bill unit hierarchy. For example, a bill unit belonging to an account in group A can be the nonpaying child of a paying bill unit belonging to an account in group B. See "About Bill Unit Hierarchies" in BRM Managing Customers.

To set up hierarchical bill unit relationships in or across accounts, write custom code that calls PCM_OP_CUST_SET_BILLINFO for each participating bill unit. Set the following fields in the input flist:

For nonpaying bill units in an account hierarchy:
- Set the PIN_FLD_PARENT_BILLINFO_OBJ field to specify the current bill unit's immediate parent bill unit, which can be paying or nonpaying.
- Set the PIN_FLD_AR_BILLINFO_OBJ field to specify the paying bill unit.
  
  Note:
  
  If the paying bill unit is also the immediate parent bill unit, the parent and paying bill unit fields specify the same bill unit.
- Set the value of the PIN_FLD_PAY_TYPE field to nonpaying (PIN_PAY_TYPE_SUBORD).
For paying bill units in an account hierarchy, set the PIN_FLD_PARENT_FLAGS field.

Setting Up Sharing Relationships among Bill Units

In charge and discount sharing groups, the bill units are the paying or nonpaying entities.

To set up sharing relationships among bill units, write custom code that calls PCM_OP_CUST_SET_BILLINFO for each participating bill unit. Set the following fields in the input flist:

For sponsored bill units in a charge or discount sharing group, set the PIN_FLD_SPONSOREE_FLAG field.
For sponsoring bill units in a charge or discount sharing group, set the PIN_FLD_SPONSOR_FLAG field.

Changing Hierarchical and Sharing Relationships among Bill Units

When you change an account hierarchy or a charge or discount sharing group, you might also need to update the relationships among the bill units participating in the original and modified groups. To do so, write custom code that calls PCM_OP_CUST_SET_BILLINFO, and pass the new paying/nonpaying parent/child or owner/member field settings in the input flist.

Billing Delays for Moved Bill Units

When you move a bill unit from one parent to another, the future billing date (stored in the PIN_FLD_ACTG_FUTURE_T field of the /billinfo object) is synchronized with the parent bill unit. However, the date that the current monthly cycle ends (stored in the PIN_FLD_ACTG_NEXT_T field) for the child bill unit is not changed to match the parent bill unit. Therefore, the first billing run following the move might be different for the parent and child bill units.

For example, a child bill unit with a billing date of the 15th is moved to a new parent bill unit that has a billing date of the 30th. If the child is moved on the 20th, it is not billed on the following 30th when the parent is billed. Instead, it is billed on the 15th of the following month. Thereafter, all billing dates are synchronized.

Suppressing Bills

The following opcodes are used to suppress bills and accounts:

PCM_OP_BILL_POL_CHECK_SUPPRESSION. See "Determining Whether Bills Should Be Suppressed".
PCM_OP_BILL_SET_BILL_SUPPRESSION. See "Manually Suppressing Bills".
PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION. See "Suppressing Accounts".
PCM_OP_BILL_REMOVE_ACCOUNT_SUPPRESSION. See "Ending Manual Account Suppression".
PCM_OP_BILL_SET_BILL_SUPPRESSION. See "Manually Suppressing Bills".
PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION. See "Suppressing Accounts".

Determining Whether Bills Should Be Suppressed

After performing the accounting activities at the end of a bill unit's billing cycle, PCM_OP_BILL_MAKE_BILL calls PCM_OP_BILL_POL_CHECK_SUPPRESSION to find out whether the bill should be finalized or suppressed. PCM_OP_BILL_POL_CHECK_SUPPRESSION performs these tasks:

Checks the PIN_FLD_PAY_TYPE field in the input flist to determine whether the bill unit is nonpaying. If it is, the opcode determines that it should not be suppressed.
From the cached /config/suppression object, PCM_OP_BILL_POL_CHECK_SUPPRESSION gets the following information for the customer segment or segments specified in the PIN_FLD_CUSTOMER_SEGMENT_LIST field of the opcode's input flist:
- The minimum balance required for the bill to be generated.
- The maximum number of consecutive billing cycles for which the bill can be suppressed.
  Note:
  - If the account belongs to multiple customer segments, PCM_OP_BILL_POL_CHECK_SUPPRESSION gets the lowest minimum balance and the lowest maximum cycle settings associated with the segments. The lowest settings do not have to be associated with the same customer segment.
  - If the input PIN_FLD_CUSTOMER_SEGMENT_LIST field contains a customer segment ID that is not associated with suppression information, PCM_OP_BILL_POL_CHECK_SUPPRESSION uses bill suppression information associated with the default customer segment (ID 0).
  - If the input PIN_FLD_CUSTOMER_SEGMENT_LIST field is empty, PCM_OP_BILL_POL_CHECK_SUPPRESSION uses bill suppression information associated with the default customer segment (ID 0).
  - If either of the two preceding items is true and the cached configuration object has no default customer segment or if the object is not in the cache, the bill does not qualify for automatic bill suppression.
PCM_OP_BILL_POL_CHECK_SUPPRESSION checks whether any of the following is true:
- The amount due (PIN_FLD_TOTAL_DUE) on the bill is less than the minimum balance specified in the customer segment.
  
  Note:
  
  This check is not done on bills that do not qualify for automatic bill suppression. See step 2.
- The account is suppressed.
When an account is manually suppressed, the PIN_FLD_ACCT_SUPPRESSED field in each /billinfo object associated with the account is set to 1. This value is put in the PIN_FLD_ACCT_SUPPRESSED field of the opcode's input flist.
The number of remaining manually suppressed billing cycles is greater than 0.

This value comes from the PIN_FLD_SUPPRESSION_CYCLES_LEFT field of the /billinfo object.
PCM_OP_BILL_POL_CHECK_SUPPRESSION makes one of the following determinations:
- If none of the preceding conditions is true, the bill should not be suppressed.
- If at least one is true, the bill should be suppressed.
If the bill should be suppressed, PCM_OP_BILL_POL_CHECK_SUPPRESSION checks for any exceptions to that suppression.

To check for exceptions, PCM_OP_BILL_POL_CHECK_SUPPRESSION gets and uses the following information:
- Adjustment events associated with the bill's account. If an adjustment occurred after the last bill was generated, the bill must be finalized.
  
  Note:
  
  In addition to adjustment events, if the payment received exception is in effect, PCM_OP_BILL_POL_CHECK_SUPPRESSION gets payment events associated with the account. In such cases, if a payment was received after the last bill was generated, the bill must be finalized. By default, this exception is commented out of the opcode. To uncomment it, see "Adding Bill Suppression Exceptions".
- The value in the input flist PIN_FLD_NUM_SUPPRESSED_CYCLES field, which indicates for how many consecutive billing cycles, the bill has been suppressed. If the value is equal to the maximum number specified in the customer segment, the bill must be finalized.
  
  Note:
  
  If the maximum number of consecutive billing cycles for which the bill can be suppressed is 0 or missing (see step 2), this exception does not apply, and the bill can be suppressed for an unlimited number of consecutive billing cycles.
- The value in the input flist PIN_FLD_LAST_BILL_OBJ field. If NULL, it means that this is the bill unit's first bill and it must be finalized.
- The value in the PIN_FLD_STATUS field in its input flist. If the value indicates that the status of the bill's account is closed, this is the bill unit's last bill and it must be finalized.
PCM_OP_BILL_POL_CHECK_SUPPRESSION then makes one of the following determinations:
- If an exception exists, the bill cannot be suppressed.
- If no exception exists, the bill can be suppressed.

The PCM_OP_BILL_POL_CHECK_SUPPRESSION output flist contains the values listed in Table 6-6. PCM_OP_BILL_MAKE_BILL uses these values to determine whether the bill should be suppressed or finalized:

Table 6-6 Output Flist for PCM_OP_BILL_POL_CHECK_SUPPRESSION

Output Flist Field	Value	Meaning
PIN_FLD_RESULT	0	Bill should not be suppressed.
PIN_FLD_RESULT	1	Bill's balance is below the minimum required to finalize it, so bill should be automatically suppressed.
PIN_FLD_RESULT	2	Bill is manually suppressed.
PIN_FLD_RESULT	3	Account is manually suppressed.
PIN_FLD_EXCEPTION	0	No exception.
PIN_FLD_EXCEPTION	1	Payment, adjustment, or credit exception.
PIN_FLD_EXCEPTION	2	First bill exception.
PIN_FLD_EXCEPTION	3	Closed account exception.
PIN_FLD_EXCEPTION	4	Maximum cycle exception.

All types of bill suppression can be overridden by exceptions.

Manually Suppressing Bills

To suppress and unsuppress bills manually, use PCM_OP_BILL_SET_BILL_SUPPRESSION. This opcode performs the following tasks:

Suppresses a bill for a specified number of billing cycles.

If the opcode's input flist PIN_FLD_SUPPRESSION_CYCLES_LEFT field contains a value greater than 0, the opcode sets the PIN_FLD_SUPPRESSIOIN_CYCLES_LEFT field in a specified /billinfo object with that value.

This value represents the number of consecutive billing cycles for which the bill is to be suppressed. At the end of each billing cycle, PCM_OP_BILL_MAKE_BILL subtracts 1 from this value in the /billinfo object. When the value reaches 0, bill suppression ends.
Unsuppresses a manually suppressed bill.

If the PIN_FLD_SUPPRESSIOIN_CYCLES_LEFT field in a /billinfo object contains a value greater than 0, the bill is manually suppressed for the specified number of billing cycles. To end the suppression early, call PCM_OP_BILL_SET_BILL_SUPPRESSION, specify the appropriate /billinfo object in the input PIN_FLD_POID field, and set the input PIN_FLD_SUPPRESSION_CYCLES_LEFT field to 0.
Generates an /event/audit/suppression/bill object each time it suppresses or unsuppresses a bill.

If you use customer segments to set the maximum number of consecutive billing cycles that bills can be suppressed, be careful not to suppress bills manually for more than the specified maximum number of cycles. When a suppressed bill exceeds the maximum consecutive cycle number, a suppression exception triggers BRM to generate the bill. This might confuse customers who requested that their bills be manually suppressed for a longer period of time.

To determine the maximum number of consecutive cycles for which a bill can be suppressed:

Find out which customer segments the bill's account belongs to by checking the PIN_FLD_CUSTOMER_SEGMENT_LIST field in the /account object.
Check the PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES field of the appropriate customer segment in the /config/suppression object.
Note:
- If an account belongs to more than one customer segment, the lowest PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES value associated with the segments applies.
- If an account belongs to no customer segments, the PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES value of the default customer segment (ID 0) applies.
- If an account belongs to no customer segments and your system has no default customer segment, the bill can be suppressed for an unlimited number of consecutive cycles.

To determine the current number of consecutive billing cycles for which a bill has been suppressed, check the PIN_FLD_NUM_SUPPRESSED_CYCLES field of the /billinfo object.

Suppressing Accounts

Use PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION to suppress accounts. Manual account suppression enables you to accomplish the following tasks:

Suppress an account immediately or on a specified future date.
- PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION can purchase one account bundle for the account to handle any purchase and cycle fees you want to associate with account suppression. The /deal object POID must be passed to the PIN_FLD_DEAL_OBJ field of the opcode's input flist.
- If you use customer segments to set the maximum number of consecutive billing cycles that bills can be suppressed, be careful not to suppress accounts manually for more than the specified maximum number of cycles . When a suppressed bill exceeds the maximum consecutive cycle number, a suppression exception triggers BRM to generate the bill. This might confuse customers who requested that their bills be manually suppressed for a longer period of time.
  
  To determine the maximum number of consecutive cycles for which a bill can be suppressed:
  
  Find out which customer segments the bill's account belongs to by checking the PIN_FLD_CUSTOMER_SEGMENT_LIST field in the /account object.
  
  Check the PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES field of the appropriate customer segment in the /config/suppression object.
  Note:
  - If an account belongs to more than one customer segment, the lowest PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES value associated with the segments applies.
  - If an account belongs to no customer segments, the PIN_FLD_MAX_SUPPRESSED_BILL_CYCLES value of the default customer segment (ID 0) applies.
  - If an account belongs to no customer segments and your system has no default customer segment, the bill can be suppressed for an unlimited number of consecutive cycles.
  To determine the current number of consecutive billing cycles for which a bill has been suppressed, check the PIN_FLD_NUM_SUPPRESSED_CYCLES field of the /billinfo object.
Unsuppress an account immediately or on a specified future date.

Note:

If a suppression bundle was purchased when the account was manually suppressed, the bundle's POID must be passed to the FLD_DEAL_OBJ field of the opcode's input flist to cancel the bundle.

PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION performs the following tasks:

Inactivates all services and charge offers associated with the account specified in the PIN_FLD_POID field of its input flist.
Optionally purchases an account bundle for the account.

The /deal object POID must be specified in the PIN_FLD_DEAL_OBJ field of the opcode's input flist. It is the only active bundle that can be associated with a suppressed account. You can use it to handle any purchase and cycle fees that you want to charge for suppressing the account.
In each /billinfo object associated with the account, sets the PIN_FLD_ACCT_SUPPRESSED field to 1.
Generates an /event/audit/suppression/account/on object.

To suppress the account on a future date, set the PIN_FLD_END_T field in the PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION input flist to the appropriate date. When a date is specified in this field, the opcode schedules a call to itself on that date.

PCM_OP_BILL_SET_ACCOUNT_SUPPRESSION does not initiate any required provisioning of deactivated services.

Ending Manual Account Suppression

PCM_OP_BILL_REMOVE_ACCOUNT_SUPPRESSION ends manual account suppression immediately or on a specified future date. This opcode does not initiate any required provisioning of reactivated services.

PCM_OP_BILL_REMOVE_ACCOUNT_SUPPRESSION performs the following tasks:

Removes any suppression bundle associated with the account.
Reactivates all services and charge offers associated with the account specified in the PIN_FLD_POID field of its input flist.
In each /billinfo object associated with the account, sets the PIN_FLD_ACCT_SUPPRESSED field to 0.
Generates an /event/audit/suppression/account/off object.

To end account suppression on a future date, set the PIN_FLD_END_T field in the PCM_OP_BILL_REMOVE_ACCOUNT_SUPPRESSION input flist to the appropriate date. When a date is specified in this field, the opcode schedules a call to itself on that date.

Adding Bill Suppression Exceptions

To add a bill suppression exception to your system:

In the PCM_OP_BILL_POL_CHECK_SUPPRESSION source code, make the appropriate modifications to these functions:

fm_bill_pol_get_suppression_reason

This function checks both for reasons to suppress a bill and for exceptions that override reasons to suppress.

fm_bill_pol_get_payment_adjustment_event

If the new exception is based on an event, add the appropriate /event storable class to the eventsBuf array in this function:

char eventsBuf[2000] = "'/event/billing/adjustment/account',\
                    '/event/billing/refund/cash','/event/billing/refund/cc',\
                    '/event/billing/refund/check','/event/billing/refund/dd',\
                    '/event/billing/refund/payorder','/event/billing/refund/postalorder',\
                    '/event/billing/refund/wtransfer','/event/billing/reversal/cc',\
                    '/event/billing/reversal/check','/event/billing/reversal/dd',\
                    '/event/billing/reversal/payorder',\
                    '/event/billing/reversal/postalorder',\
                    '/event/billing/reversal/wtransfer'";
                    
                    /***********************************************************
                     * Payment exceptions are being commented/taken out of the
                     * eventBuf buffer. If required these event ids can be 
                     * included into the buffer to consider the payment
                     * exceptions.
                     ***********************************************************/
                    /*'/event/billing/payment/cash',\
                    '/event/billing/payment/cc','/event/billing/payment/check',\
                    '/event/billing/payment/dd','/event/billing/payment/payorder',\
                    '/event/billing/payment/postalorder',
                    '/event/billing/payment/wtransfer'*/

Note:

By default, the payment-received suppression exception is commented out of the preceding code and is thus disabled. To enable it, remove the comment symbols (/* and */) enclosing the payment events.

In the BRM_home/include/pin_bill.h file, add the appropriate enumerated name and value to the bill_suppression_exceptions variable:

typedef enum bill_suppression_exceptions {
                    PIN_NO_EXCEPTION =                                   0,
                    PIN_DUE_TO_PAYMENT_ADJUSTMENT_MADE =                 1,
                    PIN_DUE_TO_FIRST_BILL =                              2,
                    PIN_DUE_TO_ACCOUNT_CLOSED =                          3,
                    PIN_DUE_TO_MAX_ALLOWED_SUPPRESSION_COUNT_REACHED =   4
} bill_suppression_exceptions_t;

Do not duplicate a value, and do not delimit the last name-value pair with a comma. If you add a name-value pair to the end of the existing list, add a comma to the end of the preceding name-value pair.

The values are used to populate the PIN_FLD_EXCEPTION field of the PCM_OP_BILL_POL_CHECK_SUPPRESSION output flist.

Deleting Bill Suppression Exceptions

To delete a bill suppression exception from your system:

In the PCM_OP_BILL_POL_CHECK_SUPPRESSION source code, delete or comment out the appropriate code in these functions:

fm_bill_pol_get_suppression_reason

This function checks both for reasons to suppress a bill and for exceptions that override reasons to suppress.

Note:

Do not remove logic used by processes that check for other exceptions.

fm_bill_pol_get_payment_adjustment_event

If the deleted exception is based on an event, remove the appropriate /event storable class from the eventsBuf array in this function:

char eventsBuf[2000] = "'/event/billing/adjustment/account',\
                    '/event/billing/refund/cash','/event/billing/refund/cc',\
                    '/event/billing/refund/check','/event/billing/refund/dd',\
                    '/event/billing/refund/payorder','/event/billing/refund/postalorder',\
                    '/event/billing/refund/wtransfer','/event/billing/reversal/cc',\
                    '/event/billing/reversal/check','/event/billing/reversal/dd',\
                    '/event/billing/reversal/payorder',\
                    '/event/billing/reversal/postalorder',\
                    '/event/billing/reversal/wtransfer'";
                    
                    /***********************************************************
                     * Payment exceptions are being commented/taken out of the
                     * eventBuf buffer. If required these event ids can be 
                     * included into the buffer to consider the payment
                     * exceptions.
                     ***********************************************************/
                    /*'/event/billing/payment/cash',\
                    '/event/billing/payment/cc','/event/billing/payment/check',\
                    '/event/billing/payment/dd','/event/billing/payment/payorder',\
                    '/event/billing/payment/postalorder',
                    '/event/billing/payment/wtransfer'*/

In the BRM_home/include/pin_bill.h file, delete or comment out the appropriate enumerated name and value from the bill_suppression_exceptions variable:

typedef enum bill_suppression_exceptions {
                    PIN_NO_EXCEPTION =                                   0,
                    PIN_DUE_TO_PAYMENT_ADJUSTMENT_MADE =                 1,
                    PIN_DUE_TO_FIRST_BILL =                              2,
                    PIN_DUE_TO_ACCOUNT_CLOSED =                          3,
                    PIN_DUE_TO_MAX_ALLOWED_SUPPRESSION_COUNT_REACHED =   4
} bill_suppression_exceptions_t;

If you remove the last name-value pair, also remove the comma at the end of the preceding name-value pair.

The values are used to populate the PIN_FLD_EXCEPTION field of the PCM_OP_BILL_POL_CHECK_SUPPRESSION output flist.

Making Trial Bills

When you run the pin_trial_bill_accts utility to perform trial billing, PCM_OP_BILL_MAKE_TRIAL_BILL is called to create trial invoices and collect revenue assurance data for the trial billing run.

Note:

To collect revenue assurance data for trial billing, you must enable the trial billing utility to generate revenue assurance data. See "Enabling Billing Utilities to Generate Revenue Assurance Data" in BRM Collecting Revenue Assurance Data.

If you enable trial billing to collect revenue assurance data, PCM_OP_BILL_MAKE_TRIAL_BILL returns the summarized data in the PIN_FLD_REVENUES_ARRAY field.

The fields on the PCM_OP_BILL_MAKE_TRIAL_BILL input flist specify if this opcode creates invoices and collects split revenue assurance data for the account specified in the input flist. If invoices are created, this opcode returns an array of trial invoice POIDs for the invoices that were created. If split revenue assurance data is collected, this opcode returns an array of revenue amounts for each item type and associated service type. The opcode opens a separate transaction to create the trial invoices.

The PIN_FLD_PROGRAM_NAME field in the input flist should always contain pin_trial_bill_accts even if you call the opcode from another application.

Note:

If a start date is not provided, PCM_OP_BILL_MAKE_TRIAL_BILL creates trial invoices for all billing cycles that are completed before the end date and that have not been billed. For accounts with skipped billing cycles, more than one trial invoice might be created.

PCM_OP_BILL_MAKE_TRIAL_BILL calls PCM_OP_BILL_MAKE_BILL to compute the balance impacts and the balance due for the accounts specified in the input flist. The input flist includes the following fields:

The POID of the /account object for trial billing.
The name of the program that called PCM_OP_BILL_MAKE_TRIAL_BILL.
The start and end dates that specify the billing cycles for trial billing.
LAST_BILL_STATE_TO_PROCESS with the value 2 to indicate that the bill unit state is final.
Two optional flag fields:
- PIN_FLD_PREINVOICE_MODE specifies whether to generate trial invoices for the trial billing run.
- PIN_FLD_CHECK_SPLIT_FLAGS specifies whether to split the revenue assurance data collected for trial billing into detailed categories. See "Collecting Split Revenue Assurance Data".
  
  Note:
  
  Trial billing stops and reports a warning message when it encounters an account or bill unit with inactive status.

Collecting Split Revenue Assurance Data

If the PIN_FLD_CHECK_SPLIT_FLAGS field is in the PCM_OP_BILL_MAKE_TRIAL_BILL input flist and has a value of 1, PCM_OP_BILL_MAKE_TRIAL_BILL passes the flag to PCM_OP_BILL_MAKE_BILL, which returns amounts associated with each item type and service type combination so that revenue assurance data collected for trial billing can be split into detailed categories. The item and service type details plus the total number of subscription services associated with the account are returned in the PIN_FLD_REVENUES array in the output flist. If any bills were suppressed, the amount suppressed and the suppression reason are also returned.

If PIN_FLD_CHECK_SPLIT_FLAGS has a value of 0 or is not in the input flist, PCM_OP_BILL_MAKE_TRIAL_BILL does not return item type and service type details.

Split revenue assurance data can be viewed by generating a Revenue Assurance Billing Detail report.

Corrective Billing

See the following topics:

Making a Corrective Bill

PCM_OP_BILL_MAKE_CORRECTIVE_BILL creates a corrective bill for a /bill object at the time of billing. It is called by the pin_make_corrective_bill utility.

If PCM_OP_BILL_MAKE_CORRECTIVE_BILL is called with the -validate_only parameter, the opcode does not generate a corrective bill for the selected bill, but merely validates whether a corrective bill can be generated for that bill.

The value in the PIN_FLD_FLAGS input field of the opcode determines whether the opcode merely validates the bill or actually creates the corrective bill object. The pin_bill.h file contains the following predefined values for these constants:

#define PIN_BILL_VALIDATION_ONLY 0x004
#define PIN_BILL_VALIDATION_NO_CHARGES 0x008

PCM_OP_BILL_MAKE_CORRECTIVE_BILL returns a value in the PIN_FLD_RESULT output field to indicate whether the bill passed or failed the validation. The pin_bill.h file contains the following predefined values for these constants:

#define PIN_BILL_VALIDATION_PASSED 0x001
#define PIN_BILL_VALIDATION_FAILED 0x002

PCM_OP_BILL_MAKE_CORRECTIVE_BILL does the following:

Locks the bill's /billinfo object. After BRM locks a /billinfo object, it does not accept any corrections until the /billinfo object is unlocked.

Caution:

If User A and User B both access a bill and User A submits the bill for corrective billing, BRM locks the /billinfo object. BRM applies any adjustments made by User B to the corrected bill object only after BRM unlocks the /billinfo object.

Also, if User B had applied the adjustment before User A submitted the bill for correction, the corrected bill will contain both adjustments.
Verifies that a corrective bill can be generated for the corrections by completing the following:
- Standard validations for the request. See "Standard Bill Validations".
- Policy validations. See "Policy Bill Validations". The opcode also performs any custom validations that you have added and that are necessary.
If the opcode validates that a corrective bill can be generated and such a bill is to be generated, the opcode continues its process. It creates the /history_bills object for the /billinfo object.
Checks to see whether the pin_make_corrective_bills utility called it with the -validate_only parameter. If so, PCM_OP_BILL_MAKE_CORRECTIVE_BILL reports whether BRM can generate a corrective bill for the selected bill and does not proceed further.
Assigns a new bill number for the corrective bill.
Sets the due date for the corrective bill.
Creates the /event/billing/corrective_bill object for the prior bill in the following way:
- The opcode includes all the A/R actions applied or allocated to the prior bill. These actions impact the totals or balances for the respective bill items and the bill. For the bill items that do not have any A/R action, BRM stores the value from the original bill in the current bill.
  
  The following entries for the PIN_FLD_FLAGS field in a bill object indicate that there was an allocation of settlement or refund for the bill. The BRM_home/include/pin_flds.h file contains the values that BRM uses in the PIN_FLD_FLAGS field for a corrective bill.
```
#define PIN_BILL_FLG_SETTLEMENT_ALLOC 0x200
#define PIN_BILL_FLG_REFUND_ALLOC 0x400
```
- The opcode stores a correction reason you provide.
- The opcode stores the name for the corrective bill. The BRM_home/include/pin_bill.h file contains the values that BRM uses in the PIN_FLD_NAME field for a corrective bill:
```
#define PIN_OBJ_NAME_CORRECTIVE_BILL "PIN Corrective Bill"
#define PIN_OBJ_NAME_CORRECTIVE_BILL_NOW "PIN Corrective Bill Now"
#define PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND "PIN Corrective Bill On Demand"
```

If PCM_OP_BILL_MAKE_CORRECTIVE_BILL encounters an error in generating the corrective bill, it logs an error against the prior bill in the default.pinlog utility log file and does not generate the corrective bill.

Validating Bills for the Corrective Billing Process

The corrective billing process uses PCM_OP_BILL_MAKE_CORRECTIVE_BILL to provide standard validations. This opcode calls PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL to complete the policy validations on a selected bill unit. PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL performs default policy validations and/or any custom validations that you provide. PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL validates a bill object to determine whether BRM can generate a corrective bill for it.

PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL requires values for the account POID in PIN_FLD_POID, the bill POID in PIN_FLD_BILL_OBJ, and PIN_FLD_INV_TYPE.

The PIN_FLD_FLAGS input field is optional. If present, this field indicates that there are charges in the bill to be validated by PCM_OP_BILL_MAKE_CORRECTIVE_BILL or requires the opcode to validate the A/R charges in the input bill.

PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL returns the success or failure of the validation in PIN_FLD_RESULT and the reason for the failure to validate the bill in PIN_FLD_ERROR_DESCR.

The BRM_home/include/pin_bill.h file contains the following values that PCM_OP_BILL_MAKE_CORRECTIVE_BILL opcode uses when it validates bills for corrective billing:

Example 6-1 Constants Associated with Validation in pin_bill.h File

#define PIN_BILL_VALIDATION_PASSED 0x001
#define PIN_BILL_VALIDATION_FAILED 0x002
#define PIN_BILL_VALIDATION_ONLY 0x004
#define PIN_BILL_VALIDATION_NO_CHARGES 0x008
#define PIN_BILL_VALIDATION_AR_CHARGES_EXIST 0x010
#define PIN_BILL_VALIDATION_FOR_AR_CHARGES_NEEDED 0x020

See the following discussions in BRM Configuring and Running Billing:

Validating bills for the corrective billing process (includes the standard and policy validations BRM performs)
pin_make_corrective_bill utility

Standard Bill Validations

PCM_OP_BILL_MAKE_CORRECTIVE_BILL checks to see whether you enabled corrective billing and whether the corrective bill is for a finalized bill. If the bill is part of a bill unit hierarchy, it checks whether you are requesting a corrective bill for the parent bill. The opcode returns an error if you attempt to generate a corrective bill for a nonpaying child bill in a hierarchy.

Policy Bill Validations

By default, PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL checks the bill and returns its findings to PCM_OP_BILL_MAKE_CORRECTIVE_BILL. Then, PCM_OP_BILL_MAKE_CORRECTIVE_BILL continues or terminates its process based on the output from PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL.

The checks performed by PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL are as follows:

PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL verifies that an invoice exists for the (original or corrective) bill for which you are attempting to generate a corrective bill. If there is no invoice associated with that bill, the opcode does not permit the generation of a corrective bill. It enters an error message in the PIN_FLD_ERROR_DESCR field and stops any further validation on the bill.
If there are no A/R charges for the prior bill, PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL verifies that it is creating only a replacement invoice for that bill. If a replacement invoice is not being generated for the corrective bill, the opcode enters an error message in the PIN_FLD_ERROR_DESCR field and stops any further validation on the bill.
When balance forward accounting is associated with a bill, PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL verifies that the corrective bill is being generated for the last bill in the billing cycle. If this validation fails, the opcode enters a PIN_BILL_VALIDATION_BILL_NOT_LAST flag in the PIN_FLD_FLAGS field. (For open item accounting, BRM permits the generation of corrective bills for any previous cycle.)
PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL verifies whether you enabled a corrective bill to be generated when there is a payment to be processed against that bill. If this validation fails, the opcode enters a PIN_BILL_VALIDATION_NOT_PAID flag in the PIN_FLD_FLAGS field.
The sum of the corrections must equal or exceed the specified amount threshold necessary to create the corrective bill. If this validation fails, PCM_OP_BILL_POL_VALID_CORRECTIVE_BILL enters a PIN_BILL_VALIDATION_AR_TOO_LOW flag in the PIN_FLD_FLAGS field.

Payment Due Dates for Corrective Bills

BRM determines due dates for regular and corrective bills by using PCM_OP_BILL_POL_CALC_PYMT_DUE_T.

By default, PCM_OP_BILL_POL_CALC_PYMT_DUE_T recalculates the due dates for corrective bills starting with the current time when the opcode generates the corrective bill and taking into account the payment terms. For example, if the payment terms set the due date for a bill to be 30 days from the billing date, and the corrective bill was generated on April 12, the due date for the corrective bill would be May 12.

Using Revenue Assurance Manager

Revenue Assurance Manager uses the following Process Audit FM standard opcodes:

PCM_OP_PROCESS_AUDIT_CREATE

This opcode creates audit objects for revenue assurance. It is called by PCM_OP_BILL_MAKE_BILL_NOW and PCM_OP_BILL_MAKE_BILL_ON_DEMAND.

This opcode performs the following actions:
- Reads the primary database ID for storing /process_audit objects.
- Calls PCM_OP_PROCESS_AUDIT_POL_CREATE to validate audit data and check for duplicate audit objects.
- Calls PCM_OP_CREATE_OBJ to create audit objects.
PCM_OP_PROCESS_AUDIT_CREATE_WRITEOFF_SUMMARY

This opcode creates a summary of a write-off operation. It is triggered by a notification event generated by Suspense Manager when a suspended event record is written off. This opcode gets information about the written-off event records from the notification event, including the record's suspended batch ID and its original batch ID.
PCM_OP_PROCESS_AUDIT_SEARCH

This opcode searches for and returns revenue assurance data from groups of /process_audit/batchstat objects.

You pass in the following information:
- A /process_audit/batchstat storable subclass type.
- A control point name.
- The detailed grouping or summary data you want.
- The type of search to perform.
The opcode returns the relevant statistics.

Customizing Revenue Assurance Manager

You can use the following opcodes to customize Revenue Assurance Manager:

PCM_OP_PROCESS_AUDIT_POL_CREATE.

See "Customizing Audit Object Validation".
PCM_OP_PROCESS_AUDIT_POL_ALERT.

See "Customizing Alert Behavior".
PCM_OP_PROCESS_AUDIT_POL_CREATE_WRITEOFF_SUMMARY.

See "Customizing the Revenue Assurance Written-Off Event Record Summaries".

Customizing Audit Object Validation

PCM_OP_PROCESS_AUDIT_POL_CREATE performs the following actions:

Checks for duplicate audit objects and validates audit data.
Performs validation only if no duplicate audit objects exist.

The opcode returns any validated data and duplicate records.

It is called by PCM_OP_PROCESS_AUDIT_CREATE

You can customize PCM_OP_PROCESS_AUDIT_POL_CREATE by modifying its flist fields, modifying duplicate checks, and adding validation checks.

Customizing Alert Behavior

Revenue Assurance Manager uses PCM_OP_PROCESS_AUDIT_POL_ALERT to send email alerts when threshold values are crossed.

PCM_OP_PROCESS_AUDIT_POL_ALERT reads the details of the alert from the notification event and sends an alert email message using the details in the /config/ra_alerts object. These details include the recipient email addresses, the locale to be used for the subject, and the message body text.

PCM_OP_PROCESS_AUDIT_POL_ALERT calls PCM_OP_DELIVERY_MAIL_SENDMSGS to send email messages using dm_email.

You can customize this opcode to notify an external system or to change the message body or subject of the email. For example, you might want to send alerts via text messages or collect alert information in error logs in addition to sending email messages.

Customizing the Revenue Assurance Written-Off Event Record Summaries

After Suspense Manager writes off an event record, Revenue Assurance Manager creates a summary of the event record by calling PCM_OP_PROCESS_AUDIT_POL_CREATE_WRITEOFF_SUMMARY. You can change this process by adding custom code to the opcode.

By default, PCM_OP_PROCESS_AUDIT_POL_CREATE_WRITEOFF_SUMMARY reads fields from /suspended_usage/telco objects and maps them to fields in the /process_audit/batchstat/status objects. Table 6-7 shows the mapping; grouped by batch ID and original batch ID:

Table 6-7 RA Manager Field Mapping

Maps these fields in /suspended_usage/telco	To these fields in /process_audit/batchstat/status
PIN_FLD_BYTES_IN	PIN_FLD_VOLUME_RECEIVED
PIN_FLD_BYTES_OUT	PIN_FLD_BYTES_VOLUME_SEND
PIN_FLD_BYTES_CALL_DURATION	PIN_FLD_BYTES_EVENT_DURATION
PIN_FLD_BYTES_EDR_COUNT	PIN_FLD_BYTES_EDR_COUNT

PCM_OP_PROCESS_AUDIT_POL_CREATE_WRITEOFF_SUMMARY sets and returns errors if there are any objects other than /suspended_usage/telco objects in the input flist.

You can change the behavior of PCM_OP_PROCESS_AUDIT_POL_CREATE_WRITEOFF_SUMMARY to read and aggregate any fields of the /suspended_usage storable class and its subclasses. The opcode can then map this data to corresponding fields in the /process_audit/batchstat/status storable class.