This chapter describes how to retrieve accounts receivable (A/R) data by using Oracle Communications Billing and Revenue Management (BRM) opcodes.
You can retrieve various kinds of balance information, such as the following:
Current balances for items and bills
A list of open and pending bill items
A list of bills
A list of adjusted items
To retrieve balance information, use the following opcodes:
PCM_OP_AR_GET_ACCT* opcodes: These opcodes retrieve the current balance for open and pending bill items associated with all the /billinfo objects in the account or for a specified /billinfo object. In the latter case, you specify the /billinfo object in the input flist.
PCM_OP_AR_GET* opcodes: These opcodes retrieve the current balance for open and pending bill items associated with the specified /billinfo object. Specify the /billinfo object in the input flist.
Note:
To retrieve information for all of an account's /billinfo objects using PCM_OP_AR_GET*, implement custom code that recursively calls PCM_OP_AR_GET* for each /billinfo object. This technique produces results similar to using PCM_OP_AR_GET_ACCT*, but it involves the overhead of creating a customization.For information on viewing A/R information in Customer Center, see the Customer Center Help.
To find a bill, use the PCM_OP_BILL_FIND opcode. You can use this opcode to search for all /bill objects instead of using the PCM_OP_SEARCH opcode and the PCM_OP_STEP_SEARCH opcode.
Note:
PCM_OP_BILL_FIND does not perform authentication.If you specify an array of bill numbers, PCM_OP_BILL_FIND returns the POID of the /bill object.
If you specify the results array, the fields in the results array are returned.
If you do not specify the results array, PCM_OP_BILL_FIND returns the entire contents of the storable object.
To find the bill units (/billinfo objects) for an account, use the PCM_OP_BAL_GET_ACCT_BILLINFO opcode. This opcode returns the main contact information for an account and a list of the account's /billinfo objects with the default /billinfo marked.
Customer Center calls PCM_OP_BAL_GET_ACCT_BILLINFO to get contact and billing information for an account. The input flist contains the account POID. The output flist contains:
Contact information from the /account object, including the account's contact name, address, and phone number.
The POIDs, names, and payment methods of all the /billinfo objects associated with that account. If more than one /billinfo object is returned, the default /billinfo array contains a PIN_FLD_FLAGS entry of 1. The PIN_FLD_FLAGS entry for each of the other /billinfo arrays is 0.
For information about bill units, see "About Bill Units".
To retrieve a /balance_group POID and, optionally, the balances it contains, use the PCM_OP_BAL_GET_BALANCES opcode. This opcode returns the /balance_group and /billinfo POIDs for an account or service. Using the PIN_FLD_BALANCES array, you can also direct this opcode to return any or all of the balances contained in the /balance_group object.
The opcode finds the /balance_group POID by using the event end time and the /service object's PIN_FLD_TRANSFER_LIST array. For more information, see "Transferring Services between Balance Groups by Using Custom Client Applications".
You can specify the validity period for which to retrieve sub-balances for the given balance group by setting the PIN_FLD_FLAGS field to one of the following values:
PIN_BAL_GET_BARE_RESULTS (0x1): This flag returns all sub-balances for the current cycle that are currently valid.
PIN_BAL_GET_ALL_BARE_RESULTS (0x4): This flag returns all sub-balances for the current cycle, including those that are expired.
PIN_BAL_GET_BASED_ON_PERIOD (0x10): This flag returns all sub-balances whose validity period falls within or overlaps a given period, specified by the PIN_FLD_START_T and PIN_FLD_END_T fields.
For example, if the period is June 1 through June 30, the opcode retrieves all sub-balance that were valid for any time between June 1 and June 30, whether their validity period begins before June 1 or ends after June 30.
PIN_BAL_GET_WITHIN_PERIOD (0x16): This value returns only the sub-balances whose start and end times fall entirely within the given time period specified by the PIN_FLD_START_T and PIN_FLD_END_T fields.
For example, if the period is June 1 through June 30, the opcode retrieves only sub-balances that start on or after June 1 and end on or before June 30.
If no balance is available for the specified period, PCM_OP_BAL_GET_BALANCES returns 0.
To return the balances that were granted by a specific product or discount, specify the POID of the granting product or discount in the PIN_FLD_GRANTOR_OBJ field.
When this opcode is called by the Activity Facilities Module (FM) opcodes or the Resource Reservation Framework (RRF), it searches the /reservation_list objects in In-Memory Database (IMDB) Cache and the /balance_group object in the database to get the balance. It performs the following steps to get the balances:
Reads the PIN_FLD_RESERVED_AMOUNT field in the /balance_group object for the specified account.
Reads the PIN_FLD_AMOUNT field from the PIN_FLD_BALANCES array of the /reservation_list object for the balance group.
Adds the amounts from the /balance_group object PIN_FLD_RESERVED_AMOUNT field and the /reservation_list object PIN_FLD_BALANCES array and returns that amount.
This opcode returns balances that are configured to start when first impacted if their validity periods have not yet been set. When a balance's validity period has not been set, the PIN_FLD_VALID_FROM_DETAILS and PIN_FLD_VALID_TO_DETAILS fields are returned for that balance. These fields store three values in separate bits: the mode of the validity start and end times (such as first usage or relative), the relative offset unit, and the number of offset units in the relative period.
If best pricing is configured, this opcode makes backup copies and resets the balance cache at the beginning of each calc-only rerating operation during the best pricing analysis phase.
Important:
A read/write transaction must be open before calling PCM_OP_BAL_GET_BALANCES. Otherwise, the object is locked, and the read operation returns an error.
You can call this opcode within a read-only operation, but the PIN_FLD_READ_BALGRP_MODE field in the input flist must be set to PIN_BAL_READ_BALGRP_CALC_ONLY.
To retrieve a balance group and service for all the bill units in an account or for a single bill unit, use the PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC opcode.
To retrieve the balance group and service for a single bill unit, use the PCM_OP_BAL_GET_BAL_GRP_AND_SVC opcode.
These opcodes return the /balance_group and /service object POIDs based on the /account POID, /billinfo POID, and event end time (PIN_FLD_END_T) passed in the input flist. The balance groups for a specified bill unit do not have to be associated with a service yet to be returned.
If the CALC_ONLY flag is set, PCM_OP_BAL_GET_BAL_GRP_AND_SVC reads the balance groups and services from the cache instead of from the database.
The PIN_FLD_FLAGS field in the input flist controls the type of information returned in the output flist. The settings for this flag are:
PIN_BAL_GET_SERVICE_DEFAULT (0): do not return login name and balance group name (default).
PIN_BAL_GET_SERVICE_LOGIN (1): Return the login name and balance group name.
PIN_BAL_GET_SERVICE_ALIAS_LIST (2): Return the alias list for the service.
PIN_BAL_GET_DEFAULT_BAL_GRP (3): Return the default balance group of the bill unit.
PIN_BAL_GET_DEFAULT_GRP_AND_SVC (4): Return the default balance group of the bill unit and the default service of the default balance group.
PIN_ BAL_GET_ALL_BAL_GRP_AND_SVC (5):Return all balance groups, including balance groups not associated with a service, balance groups associated with a service, and the account-level balance group.
Note:
You can also pass in flags to get the balance group name and service login aliases.Balance groups not yet associated with a service are returned when the PIN_FLD_FLAGS value is not set or is set to 0, 1, or 2. If the balance group returned is the account-level balance group, the service object field in the output flist is NULL. If the balance group returned is not the account-level balance group, there is no service object field in the output flist. This enables balance groups not associated with a service to be displayed in Customer Center.
If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC over PCM_OP_BAL_GET_BAL_GRP_AND_SVC because it gives you the additional flexibility of retrieving balance groups and services for either multiple or single bill units.
For information about balance groups, see "About Balance Groups".
To find items, use the PCM_OP_PYMT_ITEM_SEARCH opcode. This opcode searches for /item objects with a variable number of input parameters. It is called by other opcodes for handling adjustments and disputes.
Functionality:
This search takes a variable number of arguments to restrict the scope of the search.
The PIN_FLD_POID field is mandatory and is a dummy POID used for getting the database ID for the search.
The bill unit (/billinfo object) field is optional. This field specifies the bill unit that owns the items. You can use either the /billinfo POID or the /billinfo ID. If a /billinfo is not specified, the /billinfo object associated with the account's default balance group is selected.
You can specify either PIN_FLD_ACCOUNT_OBJ or PIN_FLD_ACCOUNT_NO to narrow the search to a particular account.
For collective bills, if they are not located in the bill table, this opcode checks the RejectPaymentForPreviousBill business parameter.
If RejectPaymentForPreviousBill is enabled to prevent BRM from accepting the payment, the opcode sends the payment to the suspense payment account.
If the RejectPaymentForPreviousBill is disabled to prevent BRM from accepting the payments, the opcode will search for the bill in the history_bills objects. If the bill is located in the history_bills objects, the payment is accepted for the bill with the same POID as the bill being processed. If such a bill is not located in history_bills objects, the payment is sent to a suspense payment account.
If PIN_FLD_STATUS, PIN_FLD_BILL_OBJ, or both are specified, the search matches the items equal to these values.
PIN_FLD_START_T and PIN_FLD_END_T specify the time range for the search. These arguments narrow the search to items whose PIN_FLD_CREATED_T value falls between the start and end times.
The PIN_FLD_POID field in the PIN_FLD_ARGS array narrows the search to specific /item object types. This is a TYPE_ONLY POID. Different items have different POID object types.
For example, if you want the search to return only the Cycle Forward and Usage items, create the POID for the PIN_FLD_POID field as shown below:
PIN_POID_CREATE(database,
" '/item/cycle_forward', '/item/usage' " -1, ebufp);
For information about items, see "How BRM Stores Accounts Receivable Information".
To retrieve the balance summary from an account, use the PCM_OP_AR_GET_ACCT_BAL_SUMMARY opcode. This opcode retrieves the unapplied, open bill due, pending bill due, and total dispute balances for all the bill units (/billinfo objects) in a specified account or for a particular bill unit. For example, Customer Center uses PCM_OP_AR_GET_ACCT_BAL_SUMMARY to retrieve the balance summary of a bill unit or bill units displayed on the Balance tab.
You can use the PCM_OP_AR_GET_BAL_SUMMARY opcode to get this information for a single bill unit.
For both opcodes, you can specify whether BRM returns the balance for:
The specified bill units (for PCM_OP_AR_GET_BAL_SUMMARY, this is a single bill unit)
The specified bill units and their nonpaying child bill units (for PCM_OP_AR_GET_BAL_SUMMARY, this is a single bill unit)
For example, in Customer Center, selecting Include child amounts for a parent account includes the amounts of its child accounts' nonpaying bill units in the calculation of its balance summary and bills.
If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_BAL_SUMMARY over PCM_OP_AR_GET_BAL_SUMMARY because it gives you the additional flexibility of retrieving balance summaries for either multiple or single bill units.
PCM_OP_AR_GET_ACCT_BAL_SUMMARY retrieves the following data for the specified bill unit:
Note:
The data includes the amounts of the bill unit's nonpaying child bill units if you set the appropriate flag.Unapplied amount
Amount due for the open bill
Amount due for the pending bill
Total disputed amount
For PCM_OP_AR_GET_BAL_SUMMARY, the Bill in Progress information when there are pending items and the balance is greater than or equal to 0 because of open disputes against the items.
For more information, see the PCM_OP_AR_GET_ACCT_BAL_SUMMARY and PCM_OP_AR_GET_BAL_SUMMARY output flist specs.
You can use the following input criteria for retrieving the balance:
The POID of the A/R bill unit object or paying /billinfo
The POID of the bill unit for which to retrieve the balance summary
A flag indicating whether to retrieve the balances for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return bills for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN flag to 0.
To return bills for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN flag to 1.
For PCM_OP_AR_GET_BAL_SUMMARY, whether to retrieve Bill in Progress information if there are any pending items but the balance is zero.
To do so, PCM_OP_AR_GET_BAL_SUMMARY uses the PIN_FLD_ITEM_PENDING_FLAGS flag. If this flag is set to 1 in the output flist, the opcode provides access to Bill in Progress information on the balance summary displayed in Customer Center. If is flag is set to 0, the opcode does not provide access to Bill in Progress information.
For more information, see the PCM_OP_AR_GET_ACCT_BAL_SUMMARY and PCM_OP_AR_GET_BAL_SUMMARY input flist specs.
Use the PCM_OP_AR_GET_ACCT_BILLS opcode to get a list of bills for all the bill units (/billinfo objects) in a specified account or for a particular bill unit (see BRM Developer's Reference). For example, Customer Center uses this opcode to list an account's bills in the Bills section of the Balance tab.
You can use the PCM_OP_AR_GET_BILLS opcode to get this information for a single bill unit.
If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_BILLS over PCM_OP_AR_GET_BILLS because it gives you the additional flexibility of retrieving the bill list for either multiple or single bill units.
PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS retrieve a list of bills for the account's bill units or it retrieves the bill units and their nonpaying child bill units. PCM_OP_AR_GET_BILLS retrieves only the bill unit you specify in the input flist. For each bill, the output includes the following data:
Current and previous total
Total for nonpaying child bill units, provided you set the appropriate flag
Amounts for adjustments, disputes, transfers, write-offs, and so forth
For more information, see the PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS output flist specs.
When you use PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS, you can use the following input criteria for retrieving the list of bills:
The POID of the account, /billinfo object, or /bill object
These opcodes list a specific bill if the /bill object POID is passed in the input flist. If you specify an account POID for PCM_OP_AR_GET_ACCT_BILLS, the opcode retrieves the bills for all the bill units in the account.
The POID of the A/R bill unit
Note:
For PCM_OP_AR_GET_ACCT_BILLS, this field is mandatory if the input flist specifies the /billinfo or /bill POID instead of the account POID.
For PCM_OP_AR_GET_BILLS, this field is mandatory unless you include the POID of the A/R account.
The POID of the A/R account. This returns the default bill unit for the A/R account
Note:
This field is not available for PCM_OP_AR_GET_ACCT_BILLS.A flag indicating whether to retrieve the balances for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return balances for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.
To return balances for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.
For example, in Customer Center, selecting Include child amounts for a parent account sets this flag, and the data returned by the opcode includes the amounts of the child accounts' nonpaying bill units in the calculation of its balance summary and bills.
The status of the bills to retrieve. If the PIN_FLD_STATUS flag is set to:
2: The opcode retrieves open bills.
4: The opcode retrieves closed bills.
6: The opcode retrieves all bills.
The number of bills to retrieve. If you use PCM_OP_AR_GET_ACCT_BILLS to retrieve bills from all the bill units in an account, this is the number of bills the opcode retrieves from each bill unit. It is not the total number of bills to retrieve from the account unless the account has only one bill unit.
The start and end times for the bills to retrieve.
The sort order, ascending or descending. If you use PCM_OP_AR_GET_ACCT_BILLS to retrieve bills from all the bill units in an account, this is the sort order the opcode applies to the bills within each bill unit, not across all the bill units.
For more information, see the PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS input flist specs.
Use the PCM_OP_AR_GET_ACCT_ACTION_ITEMS opcode (see BRM Developer's Reference) to get a list of A/R items for all the bill units (/billinfo objects) in a specified account or for a particular bill unit. For example, Customer Center uses this opcode to list items that relate to adjustments, payments, reversals, disputes, settlements, refunds, and write-offs for an account or a given bill unit of an account.
The A/R item types returned can be:
/item/adjustment
/item/dispute
/item/payment
/item/refund
/item/writeoff
Items associated with the A/R items, such as, /item/payment/reversal and /item/settlement, are returned in the PIN_FLD_RELATED_ACTION_ITEM_OBJ field.
You can use the PCM_OP_AR_GET_ACTION_ITEMS opcode to get this information for a single bill unit.
If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_ACTION_ITEMS over PCM_OP_AR_GET_ACTION_ITEMS because it gives you the additional flexibility of retrieving the A/R items for either multiple or single bill units.
PCM_OP_AR_GET_ACCT_ACTION_ITEMS and PCM_OP_AR_GET_ACTION_ITEMS return the following data:
Note:
PCM_OP_AR_GET_ACCT_ACTION_ITEMS returns an array. If the PIN_FLD_POID field is the account POID in the input flist, each element in the array is one of the listed fields for a /billinfo object in the account. Otherwise, the returned fields are for the requested single bill info.The /billinfo and A/R bill unit object (PIN_FLD_BILLINFO_OBJ and PIN_FLD_AR_BILLINFO_OBJ) that the item belongs to.
The account's primary contact information (PIN_FLD_NAMEINFO array), such as company, first name, last name, middle name, and salutation.
The number of A/R items that were found (PIN_FLD_THRESHOLD) only if this count exceeds the threshold specified in the input. If the specified threshold is not exceeded, all the A/R items found are returned.
Either the A/R items for only the given bill unit or the A/R items for the given bill unit and its nonpaying child bill units, depending on the flag setting in the input flist
For payments and reversals (that apply):
The POID of the reversal item (PIN_FLD_RELATED_ACTION_ITEM_OBJ)
The revision time when the payment was reversed; that is, when the reversal was posted (PIN_FLD_POSTED_T)
For disputes and settlements (that apply):
The POID of the settlement item (PIN_FLD_RELATED_ACTION_ITEM_OBJ)
The revision time when the dispute was settled; that is, when the settlement was posted (PIN_FLD_POSTED_T)
The bill item to which the dispute or settlement is made (PIN_FLD_RELATED_BILL_ITEM_OBJ)
For PCM_OP_AR_GET_ACTION_ITEMS only:
For event-level adjustments, disputes, and settlements, this opcode returns a PIN_FLD_AGGREGATE_AMOUNTS array for each event that makes up the adjustment, dispute, or settlement item. This array contains the aggregated amounts for each of the resources associated with the event.
For adjustments, disputes, and settlements, this opcode indicates whether the adjustment, dispute, or settlement was created at the event level or the item level. PCM_OP_AR_GET_ACTION_ITEMS also indicates whether the adjustment, dispute, or settlement affects single or multiple resources.
For possible return values of each A/R action retrieved, refer to the fields contained in the PIN_FLDS_RESULTS array in the output flist specification.
PCM_OP_AR_GET_ACCT_ACTION_ITEMS and PCM_OP_AR_GET_ACTION_ITEMS take as input:
The POID of the A/R bill unit (PIN_FLD_AR_BILLINFO_OBJ).
The POID of the bill unit related to the A/R items.
When retrieving A/R items for nonpaying child bill units, the /billinfo object is that of the paying bill unit. Otherwise, it is the /billinfo object of the specified bill.
The POID of the bill unit for which to retrieve A/R items (PIN_FLD_AR_BILLINFO_OBJ). This field is required only when retrieving A/R items for a specific, nonpaying child bill unit.
A flag indicating whether to retrieve the A/R items for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return A/R items for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.
To return A/R items for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.
The maximum number, or threshold, of A/R items to retrieve.
Note:
The threshold is set in the Threshold tab of Customer Center Preferences as the default number of A/R items displayed for an account in the A/R Actions section of the Bill Details panel.
The threshold field is valid only for an A/R bill unit (that is, the paying bill unit of a parent account).
If you use PCM_OP_AR_GET_ACCT_ACTION_ITEMS to retrieve A/R items from all the bill units in an account, this is the maximum number of A/R items the opcode retrieves from each bill unit. It is not the total number of A/R items retrieved from the account unless the account has only one bill unit.
The action-item type to retrieve (for example, /item/adjustment) specified as a comma-delimited string
Note:
When retrieving only payments, both payments and reversals are specified. When retrieving only disputes, both disputes and settlements are specified.The time range for which to retrieve A/R items. The start date is inclusive and the end date is exclusive.
The amount range. The from and to amounts are inclusive.
The amount indicator for whether to retrieve credits or debits for the given range
The item status. You can query based on a status of open, closed, or reversed (valid for payments only).
Note:
There is no pending status for A/R items.To retrieve a list of bill items for a bill unit (/billinfo object), use the PCM_OP_AR_GET_BILL_ITEMS opcode.
Customer Center, for example, uses this opcode to list the usage items, cycle items, and custom items for a given bill in the Item Charges section of the Bill Details panel.
Note:
Bill items are referred to as item charges in Customer Center.Depending on the value of the following Connection Manager (CM) pin.conf entry, the charge and discount for the items is populated in the output flist of the PCM_OP_AR_GET_BILL_ITEMS opcode. The value for this entry can be either 0 or 1. The default is 0.
- fm_ar skip_displaying_charge_and_discount_for_item 1
If the value specified is 1, the charge and discount for the items is not populated in the output flist of PCM_OP_AR_GET_BILL_ITEMS.
Note:
This opcode is used by Customer Center to display the item details in the Balance tab. Setting this flag to 1 skips the query to get the charge and discount from the events belonging to the item, thereby improving performance.PCM_OP_AR_GET_BILL_ITEMS returns:
The bill items for only the given bill unit, if PIN_FLD_INCLUDE_CHILDREN is set to 0
The bill items for the given bill unit and its nonpaying child bill units, if PIN_FLD_INCLUDE_CHILDREN is set to 1
The bill items for the nonpaying child bill units, if PIN_FLD_INCLUDE_CHILDREN is set to 2
The number of bill items that were found (PIN_FLD_THRESHOLD) only if this count exceeds the threshold specified in the input. If the specified threshold is not exceeded, all the bill items found are returned.
For each bill item retrieved, the fields in the PIN_FLDS_RESULTS array are returned. For the fields contained in this array, see the PCM_OP_AR_GET_BILL_ITEMS output flist specification.
If general ledger (G/L) collection is enabled, PCM_OP_AR_GET_BILL_ITEMS retrieves the data from G/L /journal objects. Otherwise, the opcode retrieves the data from the events for each bill item. Using /journal objects improves performance. See "Enabling and Disabling General Ledger Collection in BRM" in BRM Collecting General Ledger Data.
PCM_OP_AR_GET_BILL_ITEMS uses step-search. The step size (the number of items it tries to retrieve simultaneously) is determined by the following CM pin.conf entry:
- fm_bill item_search_batch 10000
PCM_OP_AR_GET_BILL_ITEMS takes as input:
The POID of the A/R bill unit or paying /billinfo object (PIN_FLD_AR_BILLINFO_OBJ)
The POID of the bill object related to the bill items
When PCM_OP_AR_GET_BILL_ITEMS retrieves bill items for nonpaying child bill units, the bill object is that of the paying /billinfo object. Otherwise, it is the bill object of the specified bill unit.
The POID of the /billinfo object (PIN_FLD_BILLINFO_OBJ) for which to retrieve bill items. This field is required only when retrieving bill items for a specific, nonpaying child bill unit.
A flag indicating whether to retrieve the bill items for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return bill items for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.
To return bill items for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.
To return bill items for the nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 2.
The service device ID, or phone number, or login name to retrieve the SERVICE_OBJ for the services with matching ALIAS or LOGIN_NAME. SERVICE_OBJ is used to retrieve the associated bill items.
The maximum number, or threshold, of bill items to retrieve.
This is set in the Threshold tab of Customer Center Preferences as the default number of bill items displayed for an account in the Item Charges section of the Bill Details panel.
The time range in which to retrieve bill items. The start date is inclusive and the end date is exclusive.
The amount range. The from and to amounts are inclusive.
The amount indicator for whether to retrieve credits or debits for the given range
The item status. You can query based on a status of open, closed, or pending.
You can retrieve details for an A/R item or bill item in a bill unit using either of two opcodes:
PCM_OP_AR_GET_ITEMS: Use this opcode to retrieve the details of an A/R item or bill item for a bill unit. For adjustments, disputes, and settlements, this opcode also retrieves the aggregated amount of each resource for the events associated with the item (/item/dispute, /item/adjustment, and so forth). PCM_OP_AR_GET_ITEMS provides details for both currency and non-currency resources.
Customer Center uses PCM_OP_AR_GET_ITEMS to display currency and non-currency details for A/R actions associated with a specific bill item (adjustments, disputes, settlements, payments, refunds, write-offs, and so forth). It also uses PCM_OP_AR_GET_ITEMS to provide details for an A/R action item even if only the non-currency resources were impacted by the action.
PCM_OP_AR_GET_ITEM_DETAIL: Use this opcode to retrieve the details of an A/R item or bill item for a bill unit. This opcode does not return as much information as PCM_OP_AR_GET_ITEMS. For example, it does not return the aggregated resources for dispute events. More importantly, it does not return details on non-currency resources for adjustments, disputes, or settlements unless the item has both a currency and non-currency component.
You should base your choice of opcode on how much information you want to retrieve for the A/R items and bill items.
PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the A/R item or bill item. When returning details for adjustments, disputes, or settlements, it collects details for:
Item-level adjustments, disputes, and settlements (/event/billing/dispute/item, /event/billing/adjustment/item, and so forth)
Event-level adjustments, disputes, and settlements (/event/billing/dispute/event, /event/billing/adjustment/event, and so forth)
Depending on the contents of the input flist, PCM_OP_AR_GET_ITEMS takes one of the following actions:
If the input flist contains the POID of a transfer event, PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the transfer and performs no further action. For information on what this opcode returns for transfer events, see "About the Item Detail Data Retrieved".
If the input flist contains the POID of a bill item or an A/R action such as an adjustment, dispute, or settlement, PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the A/R action or bill item. It also calls the PCM_OP_AR_RESOURCE_AGGREGATION opcode to calculate and return the aggregated amount of each resource for any event-level adjustments, disputes, and settlements.
For A/R actions, it determines whether the action was initiated at the item level or event level. If the action was initiated at the event level, it retrieves both currency and non-currency resources for the event.
For information on PCM_OP_AR_RESOURCE_AGGREGATION, see "Retrieving Details on Available Resources".
PCM_OP_AR_GET_ITEMS returns an array of details for the A/R action or bill item. The transfers_into array provides the details of all items that have a currency or non-currency impact for the A/R item or bill item specified in the input flist. These details include the aggregated resources for each event.
For adjustments, disputes, and settlements, the details for each A/R action include a flag in the transfer array that indicates whether the action was initiated at the event level or item level:
PIN_FLD_ADJUSTMENT_TYPE: Set to 0 for item-level adjustments or 1 for event-level adjustments.
PIN_FLD_DISPUTE_TYPE: Set to 0 for item-level disputes or 1 for event-level disputes.
PIN_FLD_SETTLEMENT_TYPE: Set to 0 for item-level settlements or 1 for event-level settlements.
The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for any adjustments, disputes, or settlements. If this flag is set to 0, the action affected one resource only. If the flag is set to 1, the action affected several different resources; for example, multiple currencies or both a currency and a non-currency resource such as free minutes.
For the fields in the transfer array, see the output flist specification.
PCM_OP_AR_GET_ITEM_DETAIL retrieves details of activities that had a currency impact for the specified A/R item or bill item. If the input flist contains the POID for the transfer event, that POID is used to retrieve the item-level details from the transfer event binary large object (BLOB) file. PCM_OP_AR_GET_ITEM_DETAIL returns an array of the bill items the transfer event affected and the input POID.
The transfers_into array returns the details of all the items that received some currency amount from the item specified in the input flist. For example, when a customer service representative (CSR) opens a dispute for a subscription fee, money is transferred into the dispute item from the subscription bill item (the cycle forward item). When the cycle forward item is passed in the input flist, the details of all the disputes that received money from this bill item are returned in the transfers_into array.
The transfers_out array returns the details of all those items that transferred some currency amount to the item specified in the input flist. For example, when a customer pays for service usage, money is transferred from the payment item to the bill item (usage item). When the usage item is passed in the input flist, the details of all the payments that transferred money to this bill item are returned in the transfers_out array.
For adjustments, disputes, and settlements, the details for the A/R action include a flag in the transfer array that indicates whether the action was initiated at the event level or item level:
PIN_FLD_ADJUSTMENT_TYPE: Set to 0 for item-level adjustments or 1 for event-level adjustments.
PIN_FLD_DISPUTE_TYPE: Set to 0 for item-level disputes or 1 for event-level disputes.
PIN_FLD_SETTLEMENT_TYPE: Set to 0 for item-level settlements or 1 for event-level settlements.
PCM_OP_AR_GET_ITEM_DETAIL determines how to set this flag by checking to see whether the event is stored in an /event/billing/AR_action_type/item object or an /event/billing/action_type/event object. The opcode returns the following information:
Item-level adjustments, disputes and settlements: Returns a transfer array that includes details of the adjustment, dispute, or settlement item in the PIN_FLD_EVENT_OBJ field. In this case, the only event PCM_OP_AR_GET_ITEM_DETAIL looks at is the single event associated with the /item object. For example, it looks at the single /event/billing/dispute/item event associated with the /item/dispute object.
Event-level adjustments, disputes and settlements: Returns a transfer array that includes a PIN_FLD_EVENTS array with the details of all the events that make up the adjustment, dispute, or settlement. In this case, PCM_OP_AR_GET_ITEM_DETAIL looks at all the events identified in the /item object.
The details for each A/R action also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for any adjustments, disputes, or settlements. If this flag is set to 0, the action affected one resource only. If the flag is set to 1, the action affected several different resources; for example, multiple currencies or both a currency and a non-currency resource such as free minutes.
In addition to retrieving the other details of the adjustment, dispute, or settlement, PCM_OP_AR_GET_ITEM_DETAIL determines whether there is a tax reversal already calculated for the event. If so, it adds this information to the PIN_FLD_TAX field in the output flist.
Note:
Tax reversals are calculated at adjustment, dispute, or settlement event creation time only if you have set up tax now as the tax method for adjustments, disputes, and settlements in the CM pin.conf file. For more information, see "Configuring the Default Tax Method for Account-Level Adjustments".The details for each A/R action also include a PIN_FLD_RESOURCE_IMPACTED flag to indicate whether the action affects a single resource (0) or multiple resources (1).
For the fields in the transfer array, see the output flist specification.
PCM_OP_AR_GET_ITEMS and PCM_OP_AR_GET_ITEM_DETAIL take as input:
The POID of the item object or the POID of the transfer event. If the POID is for a transfer event, all other values are ignored.
The POID of the disputed item (PIN_FLD_RELATED_BILL_ITEM_OBJ) if the bill item is disputed. This field is mandatory if the item object is a dispute, but you can also include this field for other types of item objects.
The POID of the settlement item or the reversal item (PIN_FLD_RELATED_ACTION_ITEM_OBJ) if the item is for a dispute or payment and a dispute settlement or payment reversal exists.
You can retrieve dispute details for a bill unit (/billinfo object) using either of two opcodes:
To return a complete set of dispute details, use the PCM_OP_AR_GET_DISPUTE_DETAILS opcode. This opcode retrieves the details of all event-level and item-level disputes for a bill unit and the aggregated amount of each resource for the dispute events associated with a dispute item (/item/dispute object). Customer Center uses PCM_OP_AR_GET_DISPUTE_DETAILS to get the list of disputes and available resources for a bill unit.
To return a limited set of dispute details, use the PCM_OP_AR_GET_DISPUTES opcode. This opcode retrieves details of event-level and item-level disputes for a bill unit. This opcode does not return as much information as PCM_OP_AR_GET_DISPUTE_DETAILS. For example, it does not return the aggregated resources for dispute events.
You should base your choice of opcode on how much information you want to retrieve for the disputes.
PCM_OP_AR_GET_DISPUTE_DETAILS calls PCM_OP_AR_GET_DISPUTES to get the details of each dispute. It collects details for both item-level disputes (/event/billing/dispute/item) and event-level disputes (/event/billing/dispute/event).
When it has the details for each dispute, PCM_OP_AR_GET_DISPUTE_DETAILS creates an input flist that contains the A/R event POID of each dispute and passes it to the PCM_OP_AR_RESOURCE_AGGREGATION opcode. PCM_OP_AR_RESOURCE_AGGREGATION calculates and returns the aggregated amount of each resource for each dispute event. Resources can be currency or non-currency. For information on PCM_OP_AR_RESOURCE_AGGREGATION, see "Retrieving Details on Available Resources".
PCM_OP_AR_GET_DISPUTES returns an array of disputes. This array includes transfer arrays identifying the /item/dispute object for each event-level and item-level dispute. In addition, the arrays for the event-level disputes include an aggregated resource subarray.
Each dispute includes a PIN_FLD_DISPUTE_TYPE flag in the transfer array to indicate whether it was filed as an event-level dispute or an item-level dispute:
If this flag is set to 0, the dispute is an item-level dispute.
If this flag is set to 1, the dispute is an event-level dispute.
The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for the disputes. If this flag is set to 0, the action affected one resource only. If the flag is set to 1, the action affected several different resources; for example, multiple currencies or both a currency and a non-currency resource such as free minutes.
For information on the fields in the dispute array, see the PCM_OP_AR_GET_DISPUTES output flist specification.
PCM_OP_AR_GET_DISPUTES takes as input:
The POID of the bill unit that has a dispute. If the account object is specified, the default account-level bill unit is selected.
The POID of the A/R bill unit or paying /billinfo object (PIN_FLD_AR_BILLINFO_OBJ)
A flag indicating whether to retrieve the dispute details for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return dispute details for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.
To return dispute details for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.
A status flag indicating whether to retrieve open disputes, closed (settled) disputes, or both. If the PIN_FLD_STATUS flag is set to:
2: The opcode retrieves open disputes.
4: The opcode retrieves settled disputes.
6: The opcode retrieves all disputes, open or settled.
PCM_OP_AR_GET_DISPUTES calls the PCM_OP_AR_GET_ACTION_ITEMS opcode to get a list of disputes for the bill unit and passes each disputed item to the PCM_OP_AR_GET_ITEM_DETAIL opcode, which gathers the details on the disputed items. PCM_OP_AR_GET_DISPUTES then creates an output flist that provides the information transferred by PCM_OP_AR_GET_ITEM_DETAIL, including flags to indicate whether the dispute is an event-level dispute or an item-level dispute.
For open disputes, PCM_OP_AR_GET_DISPUTES retrieves unsettled disputes; for resolved disputes, it retrieves settled disputes. This opcode is called directly by Customer Center or by PCM_OP_AR_GET_DISPUTE_DETAILS.
PCM_OP_AR_GET_DISPUTES returns an array of disputes. Each dispute includes a PIN_FLD_DISPUTE_TYPE flag in the transfer array to indicate whether it was filed as an event-level dispute or an item-level dispute:
If this flag is set to 0, the dispute is an item-level dispute.
If this flag is set to 1, the dispute is an event-level dispute.
The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for the disputes. If this flag is set to 0, the action affected one resource only. If the flag is set to 1, the action affected several different resources; for example, multiple currencies or both a currency and a non-currency resource such as free minutes.
For the fields in this array for each element representing a dispute, see the output flist specification of this opcode.
PCM_OP_AR_GET_DISPUTES takes as input:
The POID of the bill unit that has a dispute. If the account object is specified, the default account-level bill unit is selected.
The POID of the A/R bill unit or paying /billinfo object (PIN_FLD_AR_BILLINFO_OBJ)
A flag indicating whether to retrieve the dispute details for only the given bill unit or for the given bill unit and its nonpaying child bill units:
To return dispute details for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.
To return dispute details for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.
A status flag indicating whether to retrieve open disputes, closed (settled) disputes, or both. If the PIN_FLD_STATUS flag is set to:
2: The opcode retrieves open disputes.
4: The opcode retrieves settled disputes.
6: The opcode retrieves all disputes, open or settled.
Use the PCM_OP_AR_RESOURCE_AGGREGATION opcode to retrieve the available resources for the events in a bill item. This opcode calculates the aggregated amount of each resource for an event. If there is an adjustment, dispute, or settlement associated with the event, PCM_OP_AR_RESOURCE_AGGREGATION also calculates the aggregated dispute, adjustment, or settlement amount for each resource. The resource types can include currency resources, non-currency resources, or both. The output flists contains the available amounts for opening new adjustments, disputes, or settlements for each resource in the output flist.
Customer Center uses the aggregated amounts to display the balance impact of an event and help the CSR determine how much of each resource for an event is actually available for A/R activities like adjustments. This opcode is also called by the PCM_OP_AR_GET_DISPUTE_DETAILS opcode and the PCM_OP_AR_GET_ITEMS opcode.
PCM_OP_AR_RESOURCE_AGGREGATION returns an array that lists the following information for each event:
Note:
If PCM_OP_AR_RESOURCE_AGGREGATION is returning adjustment, dispute, or settlement events, it includes a resource array for all resources in the event, whether or not a particular resource is impacted by the adjustment, dispute, or settlement. For example, given a currency adjustment of an event that has US dollars and free minutes as resources, the opcode returns resource arrays for both resources even though the adjustment did not affect free minutes.Resource ID
Amount of the event
If the resource was discounted, the discount amount
If the resource was adjusted, the adjustment amount
If the resource was disputed, the dispute amount and the amount of the original dispute
If a settlement occurred, the settlement amount
The total resource currently available. This is the amount in the PIN_FLD_AMOUNT field minus any discounts, adjustments, disputes (the dispute amount in PIN_FLD_DISPUTED only, not the original dispute amount), and settlements.
Each event in the array can have multiple resource arrays, each of which includes the above information. Some of the preceding information is optional. For more information on optional fields, see the output flist specification for this opcode.
PCM_OP_AR_RESOURCE_AGGREGATION takes as input:
The POID of the account in which to find the events
The array of event POIDs for which to calculate resources
To find all events associated with an account, use the PCM_OP_BILL_POL_EVENT_SEARCH policy opcode.
For filtered searches, this policy opcode supports searching on the following criteria:
POID of the bill unit (the /billinfo object)
POID of the bill
POID of the item
Date ranges
Amount ranges
Event type
Service type
Resource ID
To specify the number of events to return, use a value for the threshold. If the threshold value is greater than or equal to the number of events, all events are returned. If the threshold value is less than the number of events, the number of events is returned.
By default, the PCM_OP_BILL_POL_EVENT_SEARCH policy opcode returns all the events for the account but discards dispute, adjustment, and settlement events. This policy opcode can be customized to retrieve all the events for the account and keep the dispute, adjustment, and settlement events.
If the PIN_FLD_FLAGS field in the output flist's event array is set to 1 for a particular event, the event has a non-currency impact, and Customer Center provides access to Usage Details (through Bill Details). The PCM_OP_BILL_POL_EVENT_SEARCH policy opcode also provides feedback on its success or failure through the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array in the output flist.
For a complete list of all fields returned, see the output flist specification for this opcode.
To find events associated with a bill item, use the PCM_OP_BILL_ITEM_EVENT_SEARCH opcode.
This opcode searches the /event object for details related to a specific item. This opcode retrieves a list of events for a given item POID and flag.
The PIN_FLD_SEARCH_TYPE field in the PCM_OP_BILL_ITEM_EVENT_SEARCH input flist can be set to one or all of the following fields:
PIN_ITEM_EVENT_OWNED: Events owned by an item. If PIN_ITEM_EVENT_OWNED is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID matches the item POID passed in the input flist.
PIN_ITEM_EVENT_SPONSORED: Events sponsored by the item. If the PIN_ITEM_EVENT_SPONSORED flag is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID in the event subtotal array matches the item POID passed in the input flist.
PIN_ITEM_EVENT_TRANSFERRED: A/R events that affect the item's total. If the PIN_ITEM_EVENT_TRANSFERRED flag is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID matches POIDs stored in PIN_OBJ_TYPE_EVENT_ITEM_TRANSFER. Lists are returned in separate arrays so that a list can be returned for each selected flag.
In addition to the above criteria, the event search can be narrowed to reflect the type of event and when the event was created.