This chapter describes how to create and manage bill units (/billinfo objects) in Oracle Communications Billing and Revenue Management (BRM) by using your custom application.
For information about bill units, see "About Bill Units" in BRM Managing Accounts Receivable.
Use the following opcodes to manage bill units:
To create a /billinfo object, use PCM_OP_CUST_CREATE_BILLINFO.
To update a /billinfo object, use PCM_OP_CUST_SET_BILLINFO.
To customize how /billinfo objects are created, use PCM_OP_CUST_POL_PREP_BILLINFO to prepare /billinfo data and PCM_OP_CUST_POL_VALID_BILLINFO to validate /billinfo data.
See "Preparing /billinfo Data" and "Validating /billinfo Data".
To delete a /billinfo object, use PCM_OP_CUST_DELETE_BILLINFO.
To postpone finalizing a bill until the end of a future billing cycle, suppress billing for the /billinfo object.
To suspend billing of a /billinfo object in a closed account, use PCM_OP_BILL_POL_POST_BILLING.
When you reactivate a closed account, BRM automatically resumes billing for that account.
Use PCM_OP_CUST_CREATE_BILLINFO to create /billinfo objects. This opcode creates the /billinfo object by using the information provided in the input flist.
You can set each /billinfo object's billing cycle fields, such as the billing type, the billing frequency, and the billing DOM, by passing information in the opcode's input flist fields.
If the object is successfully created, the output flist contains:
The POID of the /account storable object to which the /billinfo belongs.
PIN_FLD_BILLINFO array that specifies the billing information that is created.
For information about creating /billinfo hierarchies and sponsorship, see "Creating /billinfo Object Hierarchy and Sponsorship".
After creating a new /billinfo object, 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 your plans in Pricing Center. See the discussion about tracking service-level resources in the Pricing Center online help.
To associate account balances with a new bill, see the discussion about moving a balance group to a new /billinfo object in the Pricing Center online help.
Use PCM_OP_CUST_SET_BILLINFO to update billing information in existing /billinfo objects. 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.
Use the following opcodes to customize PCM_OP_CUST_SET_BILLINFO functionality:
Use PCM_OP_CUST_POL_PREP_BILLINFO to prepare /billinfo data. See "Preparing /billinfo Data".
Use PCM_OP_CUST_POL_VALID_BILLINFO to validate /billinfo data. See "Validating /billinfo Data".
Both of these opcodes are called by PCM_OP_CUST_SET_BILLINFO.
You can set each /billinfo object's billing cycle fields, such as the billing type, the billing frequency, and the billing DOM, by passing information in the opcode's input flist fields.
For information about creating /billinfo hierarchies and sponsorship, see "Creating /billinfo Object Hierarchy and Sponsorship".
The PCM_OP_CUST_POL_PREP_BILLINFO policy opcode processes the account billing fields in the /billinfo storable object during customer registration or while updating billing information to prepare for validation. For information about the PREP opcodes, see "About the PREP and VALID Opcodes" in BRM Developer's Guide.
The policy 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 DOMs to /billinfo Objects".
The policy opcode 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
The PCM_OP_CUST_POL_PREP_BILLINFO policy opcode provides a mechanism for taking the information passed to PCM_OP_CUST_SET_BILLINFO and processing the fields before their validation by the PCM_OP_CUST_POL_VALID_BILLINFO policy opcode. See "Validating /billinfo Data".
Processing includes adding any missing fields whose values are derived or generated by this opcode, 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 the PCM_OP_CUST_POL_VALID_BILLINFO policy opcode 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.
For more information, see "About the PREP and VALID Opcodes" in BRM Developer's Guide.
The PCM_OP_CUST_POL_PREP_BILLINFO policy opcode prepares the billing information for on-line registration by implementing default values as shown below:
If not already specified in the in the input flist, the PIN_FLD_BILL_WHEN field is set to the value specified in the CM pin.conf file's bill_when entry. If no value is found in the pin.conf file, it is defaulted to 1. See "Setting the Default Billing-Cycle Length".
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. See "Setting the Default Account Currency" in BRM Managing Customers.
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). See "Setting the Default Accounting Type".
If the primary currency is EURO, the PIN_FLD_CURRENCY_SECONDARY field is set to the default secondary currency.
PCM_OP_CUST_POL_PREP_BILLINFO assigns a DOM to a /billinfo object based on the following order of priority:
The DOM assigned to the billing segment. The policy opcode assigns the DOM set for the billing segment in the /config/billing_segment object. For more information, see "Assigning DOM Based on the Billing Segment".
Note:
To customize how the policy opcode assigns the DOM according to the billing segment, see "Customizing the DOM Assignment Process".The DOM used by first /billinfo object in the account. If a DOM is not assigned to the billing segment, the policy opcode assigns the DOM to that of the first /billlinfo object in the account.
Default setting in the Connection Manager pin.conf file. If a DOM is not assigned to the billing segment nor is available from another /billinfo object, 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 where you installed BRM components). To set the default value, see "Setting the Default Accounting Day of Month (DOM)".
The current date. If a DOM is not available from the billing segment, other /billinfo objects, or the CM pin.conf file, the policy opcode assigns the DOM to the current date that is 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 a DOM assigned, the policy opcode would assign a DOM to BU2 as follows:
If BU2 is the second /billinfo array element in the /account object, the policy opcode assigns the DOM to that of the first /billinfo array element.
If BU2 is the first /billinfo array element in the /account object, the policy opcode assigns the DOM to the value 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 that is passed in the input flist's PIN_FLD_END_T field.
When a /config/billing_segment object exists in the Connection Manager (CM) cache and contains an array of billing segments, the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode 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 /billinfo object.
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 /billinfo object:
By default, the opcode assigns the first open DOM in the specified billing segment, starting with the current DOM. See "About Accounting DOM Status".
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 (see "About Accounting DOM Status"). 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.
To increase the probability that the assigned billing DOM has the lightest billing load of all the open days in a billing segment, this policy opcode 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 /billinfo object. (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 /billinfo Y belongs, has the following open DOMs and associated billing-run processing times as shown in Table 5-1:
| DOM/Process | Value | Value | Value | Value | Value |
|---|---|---|---|---|---|
|
Open DOMs |
5 |
11 |
16 |
20 |
75 |
|
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 5-2:
Table 5-2 Sample Bill-Run Processing Times
| DOM/Process | Value | Value | Value | Value | Value |
|---|---|---|---|---|---|
|
Open 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 |
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 /billinfo object. 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 5-3:
Table 5-3 Sample Values for DOM
| DOM/Process | Value | Value | Value | Value | Value |
|---|---|---|---|---|---|
|
Open 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 /billinfo Y to 16.
The PCM_OP_CUST_POL_VALID_BILLINFO policy opcode validates an account's billing information in the /billinfo storable object passed to it by the PCM_OP_CUST_POL_PREP_BILLINFO policy opcode during customer registration or administrative update.
The billing information can include:
Payment method
Parent /billinfo object
Next bill time
Currency used
Billing frequency
Accounting cycle duration
Accounting type
Billing segment ID
For more information, see "About the PREP and VALID Opcodes" in BRM Developer's Guide.
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 storable 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.
All customizing should be done with the Field Validation Editor in Configuration Center. Users should not change the fm_cust_pol_valid_billinfo.c file for PCM_OP_CUST_POL_VALID_BILLINFO because it could corrupt the database. The Field Validation Editor is used to create and edit the /config/fld_validate storable object.
If the PIN_FLD_BILLING_SEGMENT field in the PCM_OP_CUST_POL_VALID_BILLINFO input flist contains a value other than 0, the opcode 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. See "About Accounting DOM Status".
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.
To suspend and resume billing of a bill unit (/billinfo object) in a closed account, see the following:
For an overview of bill suspension, see "About Suspending Billing of Accounts and Bills".
To suspend billing of a closed account, use the PCM_OP_BILL_POL_POST_BILLING policy opcode.
This policy opcode is called by PCM_OP_BILL_MAKE_BILL. It enables you to perform custom processing on a bill unit (/billinfo object) at the time of billing.
By default, this policy opcode 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 hierarchical accounts, the balance due amount includes the open and pending item totals of every subordinate bill unit in child accounts.
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 policy opcode suspends billing at the end of the last accounting cycle.
If delayed billing is enabled, the default implementation of this policy opcode suspends billing at the end of the billing delay interval.
To indicate billing is suspended, this policy opcode sets the PIN_FLD_BILLING_STATUS field in the /billinfo object to inactive.
This policy opcode returns the POID of the /billinfo object. For a complete list of all fields returned, see the output flist specification for this opcode.
When an account's status is changed from closed to active, PCM_OP_CUST_SET_STATUS calls PCM_OP_BILL_RESUME_BILLING to resume suspended billing. Therefore, you do not need to call PCM_OP_BILL_RESUME_BILLING directly.
PCM_OP_BILL_RESUME_BILLING sets the PIN_FLD_BILLING_STATUS field in the account's bill units (/billinfo objects) 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.PCM_OP_BILL_RESUME_BILLING 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:
PCM_OP_BILL_RESUME_BILLING does not automatically resume suspended billing for subordinate bill units. To do that, you must reactivate the subordinate 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.
To delete /billinfo objects, write custom code that calls PCM_OP_CUST_DELETE_BILLINFO.
If the specified /billinfo storable object is a nonsubordinate parent /billinfo, this opcode automatically deletes any subordinate /billinfo objects that are associated with it.
Note:
You cannot delete a /billinfo object that has pending payments.If successful, the output flist contains:
PIN_FLD_POID field set to the account POID of the /account storable object that is deleted.
PIN_FLD_BILLINFO array that specifies the billing information that is deleted.
In account sponsorship and hierarchies, the /billinfo objects are the paying or nonpaying entities. When an account in a hierarchy or sponsorship has multiple /billinfo objects, you must designate specific /billinfo objects as parent or child, and sponsor or sponsoree. For more information, see "About Hierarchical Bill Units" in BRM Managing Accounts Receivable.
Note:
The /billinfo objects of accounts that have different parent accounts can form a /billinfo hierarchy. A /billinfo object in a child account can be subordinate to a /billinfo object in a different parent account. For more information, see "Creating Hierarchical Bill Units" in BRM Managing Accounts Receivable.To create /billinfo hierarchy and sponsorship for accounts that have multiple /billinfo objects, write custom code that calls PCM_OP_CUST_SET_BILLINFO for each /billinfo object that will participate in the hierarchy or sponsorship. Specify the following relationship fields in the input flist:
If the /billinfo is a nonpaying (subordinate) /billinfo in a hierarchy:
Set the PIN_FLD_PARENT_BILLINFO_OBJ field to specify paying (nonsubordinate) /billinfo in the parent account.
Set the PIN_FLD_AR_BILLINFO_OBJ field to specify the AR /billinfo object. This is the parent account's default /billinfo object.
Note:
If the AR /billinfo is also the parent /billinfo, the parent and AR /billinfo fields specify the same /billinfo object.Set the value of the PIN_FLD_PAY_TYPE field to subordinate (PIN_PAY_TYPE_SUBORD).
If the /billinfo is a paying /billinfo in a hierarchy, set the PIN_FLD_PARENT_FLAGS field.
If the /billinfo has charges that are sponsored by another /billinfo object, set the PIN_FLD_SPONSOREE_FLAG field.
If the /billinfo sponsors charges in another /billinfo object, set the PIN_FLD_SPONSOR_FLAG field.
When you change an account hierarchy and sponsorship by using Customer Center, all /billinfo objects that participate in that hierarchy or sponsorship are also changed. To add or remove individual /billinfo objects from a hierarchy or sponsorship, write custom code that calls PCM_OP_CUST_SET_BILLINFO and pass the new parent and child or sponsor and sponsoree fields on the input flist.
When you move a /billinfo object from one parent to another, the future billing date (stored in the PIN_FLD_ACTG_FUTURE_T field) is synchronized with the parent /billinfo. However, the date that the current monthly cycle ends (stored in the PIN_FLD_ACTG_NEXT_T field) for the child /billinfo is not changed to match the parent /billinfo. Therefore, the first billing run following the move might be different for the parent and child /billinfo objects.
For example, a child /billinfo with a billing date of the 15th is moved to a new parent /billinfo 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.