This chapter provides an overview of how adjustments, disputes, and settlements are performed in Oracle Communications Billing and Revenue Management (BRM). It also tells you how to configure taxes, resource reservation, and reason codes for this functionality.
For more information on adjustments, disputes, and settlements, see the following topics:
For information on creating adjustments, disputes, and settlements in Customer Center, see the Customer Center Help.
An adjustment is a transaction that debits or credits a customer's account by changing the amount due for a bill item. Adjustments can also change non-currency balances in the account. For information on currency and non-currency adjustments, see "About Adjustments".
Customer service representatives perform adjustments on a variety of levels, as appropriate to the situation. For instance, if the customer made a 10-minute call that was mistakenly billed as a 30-minute call, CSRs perform the adjustment for that specific call at the event level. If, however, the customer's plan provided 100 free minutes a month, but charges started accruing after only 30 minutes, CSRs perform the adjustment at the account level instead.
The way that BRM processes adjustments and records the adjustment's balance impact varies slightly from level to level, as follows:
A/R and individual account level: Adjustments at this level reduce the current balance of the customer's bill. The account's default balance group will be decreased by the amount of the credit.
Subscription service level and member service level: Adjustments at these levels are similar to account-level adjustments. However, the adjustment targets a specific balance group associated with the subscription service or member service rather than using only the default balance group. In this case, BRM uses the balance group supplied by the /service object associated with the subscription service or member service selected by the CSR.
As with account-level adjustments, the CSR must allocate the adjustment before it affects the customer's bill.
Bill level: Like the higher-level adjustments, adjustments at this level reduce the current balance of the customer's bill. Here, the amount of the adjustment is subtracted from the due amount for the bill, and payment for that amount is not requested.
Adjustments can be made to an entire bill or a selection of bill items, distributing the adjustment as a fixed amount per item or as a percentage. In either case, BRM creates a single adjustment item and transfers the credit to the bill items covered by the adjustment. The current balance of the appropriate balance groups is reduced by the amount of the credit.
Bill-level adjustments only act against A/R bills. CSRs cannot adjust a bill from a subordinate bill unit by filing a bill-level adjustment directly against that bill. Instead, they file the bill-level adjustment against the parent A/R bill. Also, the adjustment amount cannot exceed the total amount of the bill against which the adjustment is applied.
Item level: When you adjust a bill item, the amount of the adjustment is subtracted from the Due of the bill item, and payment for that amount is not requested. The current balance of the appropriate balance group is reduced by the amount of the credit.
Event level: Adjustments at this level depend on whether the adjustment occurs before billing or after billing. In either case, the original event is never adjusted.
If the adjustment occurs before billing has run, it changes the balance impact of the shadow event.
If the adjustment occurs after billing has run, it changes the balance impact of the adjustment event (/event/billing/adjustment/event).
An event adjustment that credits currency reduces the balance impact of the event and its General Ledger (G/L) impact. It does not cancel the event, only the cost of the event.
Important:
When adjusting pending items, ensure proper G/L reporting by specifying that BRM create a shadow adjustment instead of a standard adjustment. See "Categorizing Unbilled Event-Level Adjustments in G/L Reports".CSRs can adjust multiple events in one operation. BRM creates one adjustment item for the adjustments performed in an operation and transfers the credit to all the bill items associated with the adjusted events.
CSRs can also adjust a given event multiple times. For example, a customer indicates an evening event was billed at a higher rate than it should have been and the CSR adjusts the event to change the rate from a day rate to an off-hours rate. Later, the CSR realizes that a holiday rate should have been applied instead and performs a second adjustment to switch to the holiday rate.
BRM performs adjustments at each of these levels by calling different adjustment opcodes. For information on how to customize adjustments and on which opcodes to call from your client application, see "Performing Disputes and Settlements with Your Custom Application".
CSRs make adjustments on all levels by using Customer Center. For the steps to perform adjustments in Customer Center, see "About Adjustments".
Note:
Although Customer Center provides the easiest method of adjusting events, CSRs can also make event-level adjustments through Event Browser. For information on using Event Browser for event-level adjustments, see "Adjusting Events".In some situations, you may want to adjust multiple A/R accounts simultaneously. For example, if regular daily rates were mistakenly applied during a holiday discount period, you would most likely want to perform adjustments for all the accounts that used the service over the holiday.
This type of adjustment is called a bulk adjustment and runs as a batch job initiated by operations personnel from the command line. The batch file for the bulk adjustment defines the accounts, balance groups, and amounts involved in the adjustment. The file is in CSV format and is typically supplied by an external source program. Bulk adjustments use the BRM multithreaded application (MTA) framework to process the batch file and perform the adjustment defined in this file for each listed account. For information on the MTA framework, see "Creating BRM Client Applications by Using the MTA framework" in BRM Developer's Guide.
The input file also specifies whether the adjustment is taxable. BRM bases tax calculation on the full adjustment amount for each account. Depending on how adjustment taxation is configured, BRM may apply the adjustment tax reversal when the bulk adjustment runs or send the adjustment amount for deferred taxation during the next billing run. For information on configuring taxes for adjustments, see "Configuring Taxes for Adjustments, Disputes, and Settlements".
When BRM processes a bulk adjustment, it performs each adjustment as a separate transaction. Therefore, there is no need to roll back the successful adjustments if some adjustments fail. BRM reports any accounts that failed the bulk adjustment in a log file so that you can examine them and correct the problem. All the CSV records that failed to process due to wrong format or due to the server side errors are written to an error file. The default name of this file is pin_mta_failed.csv. The names and locations of these files can be defined in the pin_apply_bulk_adjustment pin.conf file.
Bulk adjustments are initiated by operations personnel at the command line by using the pin_apply_bulk_adjustment utility and a CSV file.
To perform a bulk adjustment, you must generate a CSV file that lists each of the accounts that should receive the bulk adjustment and provides information about the adjustment. BRM uses the CSV file to create an input flist for each of the adjustments that are part of the bulk adjustment.
CSV is a standard file format that uses commas as field delimiters and line breaks as record delimiters. CSV files should contain no blank lines. CSV files used for bulk adjustments are typically generated by an external program, and the records must use the following format:
account_POID, adjustment_amount, balance_group_POID, tax_flag, tax_code, tax_supplier_ID, resource_ID, end_time, reason_code_domain, reason_code, description
Note:
A CSV record should not contain the line break implied above. Line breaks should occur at the end of each record.Consider these guidelines:
The account_POID, adjustment_amount, and resource_ID fields are mandatory. You can omit any of the other fields. If you omit any field in a record (including those at the end of the record), you must still include the associated comma so BRM can keep track of which field it's processing.
If you omit the balance_group_POID, BRM adjusts the default balance group.
The tax_flag field indicates whether the adjustment requires tax reversal. If the flag is set to 1, the adjustment does not need tax reversal and the generated input flist contains the PIN_AR_WITHOUT_TAX flag. If the flag is set to 2, the adjustment involves a tax reversal and the generated input flist contains the PIN_AR_WITH_TAX flag instead. If you omit this field, the adjustment occurs without a tax reversal.
Note:
The tax flag is ignored in any records that specify a non-currency resource.The resource_ID is the numeric code for the resource you are adjusting; for example, 840 for US dollars. You can specify currency or non-currency resources.
The format for the end_time field is MM/DD/YYYY. BRM uses midnight for the date you specify as the time stamp for the adjustment.
If you include a reason_code_domain, you must also include a reason_code, and the reverse.
If the description field includes any commas, you must enclose the field in quotation marks ("). Quotation marks are optional for description fields that do not include commas.
The following CSV file segment shows a bulk adjustment with tax:
0.0.0.1 /account 15269 0, -9.5, 0.0.0.1 /balance_group 12901 0, 2, , , 840, , , , Rate issue 0.0.0.1 /account 12581 0, -9.5, 0.0.0.1 /balance_group 16165 0, 1, , , 840, , , , Rate issue 0.0.0.1 /account 15557 0, 10, , , , , 1000010, 04/26/2004, 12, 5, "Service drop, fix this"
In the above example, the first record specifies an adjustment with a tax reversal against the currency resource for a specific balance group. The adjustment amount is $9.50. The second record specifies a similar adjustment, except that this adjustment has no tax reversal. The last record specifies an adjustment of 10 free domestic minutes to the account's default balance group. BRM does not apply a tax reversal for this adjustment.
To run bulk adjustments, generate a CSV file and then run the pin_apply_bulk_adjustment utility to load the file into the database.
Important:
To connect to the BRM database, pin_apply_bulk_adjustment needs a configuration file in the BRM_Home/apps/pin_bulk_adjust directory. Or, if you are not starting the utility from this directory, you need the configuration file in directory from which you run the utility. For more information, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.Generate the CSV file and check it for format problems and spurious blank lines.
Use the following command to run the pin_apply_bulk_adjustment utility:
pin_apply_bulk_adjustment -f input_file.csv
Important:
If the CSV file is not in your working directory, use the full path to the file:pin_apply_bulk_adjustment -f /files/bulk_adjust/input_file.csv
Check the pin_bulk_adjust.pin log file for any failed adjustments.
The bulk adjustment application generates an intermediate file in flist format. The default name of this file is pin_mta_search.flist.
All the CSV records that failed to process due to wrong format or due to the server side errors are written to an error file. The default name of this file is pin_mta_failed.csv.
The names and locations of these files can be defined in the pin_apply_bulk_adjustment pin.conf file.
Any account-level adjustments or service-level adjustments for a past bill must be allocated to the prior bill before BRM generates the corrective bill for that bill. To ensure that the totals and balances for the bill item and the bill correctly reflect the corrections, enter all adjustments either manually or automatically through the rerating process before you generate the creative invoice for such a bill.
When it generates the corrective bill for such a prior bill, BRM includes all the A/R actions applied or allocated to that bill. It does not enable you to select some allocated A/R items and exclude others to be included in the next bill or the bill in progress.
The AllocateReratingAdjustments business parameter is used to specify whether BRM should allocate automatic adjustments from rerating to original bills.
Note:
To ensure that the corrective billing process includes or excludes these adjustments, check the setting for this business parameter before you run the rerating process.You can set AllocateReratingAdjustments to the following values:
disabled: This is the default value. BRM does not make any automatic allocation during the rerating. It creates only unallocated adjustments with no information about the original items.
enabled: BRM automatically allocates adjustments to the items on the original bill.
For information on configuring AllocateReratingAdjustments, see BRM Setting Up Pricing and Rating.
If you enable the AllocateReratingAdjustments business parameter, BRM displays the adjustment details by original item by original bill on the next bill.
When you enable AllocateReratingAdjustments business parameter, BRM allocates adjustments to the corrected bill items in the following manner:
For open item accounting, the adjustment items are allocated to each bill that was corrected. And allocation is made to each of the original bills which included events or items that were corrected by these adjustments.
For balance forward accounting, corrections are posted to the last bill only. Therefore, the rerating allocation is made to the final bill only. This final bill carries over the balances for all prior bill periods.
The value of the subARItemsIncluded business parameter determines how BRM displays the adjustments in the summary and detailed versions of a Replacement Invoice or an Invoice Correction Letter.
For more information on corrective invoices, see BRM Designing and Generating Invoices.
The dispute process involves two distinct activities; opening a dispute and settling that dispute. A dispute is a transaction that records a customer's objection to a currency amount billed to an account. A settlement is a transaction that resolves a dispute by crediting or debiting all, part, or none of the dispute amount to the account. Customers can also dispute events that use non-currency resources in the account. In this case, settling the dispute affects non-currency balances.
CSRs perform disputes and settlements at various levels, as appropriate to the situation. The way that BRM processes disputes and settlements varies slightly from level to level, as follows:
Bill level: CSRs can dispute or settle an entire bill or a selection of bill items. In either case, BRM creates a single dispute or settlement item and alters the Due of each bill item covered by the dispute or settlement. Bill-level disputes and settlements can be thought of as a set of item-level disputes or settlements covered under the umbrella of a single dispute or settlement item.
Bill-level disputes and settlements can only act against A/R bills. CSRs cannot dispute or settle a bill from a subordinate bill unit by filing a bill-level dispute or settlement directly against that bill. Instead, they file the bill-level dispute or settlement against the parent A/R bill. The dispute amount cannot exceed the total amount of the bill against which the dispute is applied, and the settlement amount cannot exceed the total dispute amount for the bill.
Item level: Disputes and settlements at this level operate as either a CSR-initiated action against a single bill item or as a unilateral action against a set of bill items initiated by a bill-level dispute or settlement. Depending on how the dispute or settlement was initiated, BRM creates dispute and settlement items as follows:
If the CSR initiated the dispute or settlement at the item level, one dispute or settlement item is created for the item he or she chooses.
If the dispute or settlement was initiated at the bill level, a single dispute or settlement item will cover all the individual item-level disputes that make up the bill-level dispute.
Event level: CSRs can dispute and settle any event and they can dispute or settle multiple events from an account in one operation.
When an event-level dispute is opened, BRM creates one dispute event for each disputed event, establishing a one-to-one correspondence between the dispute event and the original event. The dispute event updates the original item's Dispute field. BRM bundles all the individual dispute events into one dispute item.
Similarly, when you settle an event-level dispute, BRM creates a settlement event for each dispute event. In this case, BRM transfers the settlement amount to the Adjusted field of the original item and the denied amount to the Due field. As with disputes, BRM bundles all individual settlement events into one settlement item.
BRM performs disputes and settlements at each of these levels by calling different dispute and settlement opcodes. For information on how to customize disputes and settlements and on which opcodes to call from your client application, see "Performing Adjustments with Your Custom Application".
CSRs open and resolve disputes for items and events by using Customer Center. For information about managing item-level and event-level disputes and settlements in Customer Center, see the Customer Center Help.
Note:
CSRs cannot perform bill-level disputes and settlements through Customer Center. To dispute and settle bills, CSRs dispute and settle individual bill items, one by one. However, if you use a third-party CRM, you can implement disputes and settlements at the bill level by calling the appropriate opcode.BRM system does not differentiate between bill-level and item-level disputes. Therefore, the person settling the dispute must keep track of the dispute type and settle the dispute with the corresponding settlement opcode.
Disputes, settlements, and write-offs impact the content of a corrective bill. If you must prevent the generation of corrective bills for certain A/R actions, set up a custom validation policy for BRM to use when you generate the corrective bills. Such a validation could be used to prevent BRM from generating corrective bills when the prior bill is in dispute and a settlement has not been reached.
Corrective bills can be generated for a dispute entered at the bill level, item level or event level. When BRM generates the corrective bill for a prior bill in dispute, the corrective bill contains the details of the dispute, the disputed bill item under the corrected items, and the bill balance reduced by the disputed amount.
Corrective bills can be generated for a dispute settled at the bill level, item level or event level. When BRM generates the corrective bill when a bill item on the prior bill is in settlement, the corrective bill contains the details of the settlement, the settled bill item under the corrected items, and the bill balance reduced or increased by the settlement.
A dispute may be settled for the full amount of the dispute in the customer's favor. If you submitted a corrective bill at the time of such a dispute, the corrective bill at settlement time may become a duplicate as there may not be any additional corrections to the second bill.
You perform write-offs after the account is past due and considered delinquent in collections. When BRM generates the corrective bill for a write-off on a bill item on the prior bill, the corrective bill contains the details of the write-off, the written-off bill item under the corrected items, and the bill balance reduced by the write-off amount.
You can specify whether to perform an adjustment, dispute, or settlement with or without taxes at the bill, item, and event level. For taxable account-level, bill-level and item-level adjustments, BRM uses information supplied by a tax configuration file to calculate the tax reversal for the account.
If you include taxes in an A/R action and the billing has already occurred, they are always calculated at the time the adjustment, dispute, or settlement is created. If the billing has not occurred, the calculated amount is applied only if the item has real-time taxes. If the item has deferred taxes, only the adjustment, dispute, or settlement amount is applied; the tax amount is calculated and applied at the time of billing.
Important:
To ensure tax calculations are performed correctly for adjustments, disputes, settlements, and write-offs:Configure a separate item for taxes exclusively. To configure a separate item for taxes, see "Cumulative Custom Item for Taxes" in BRM Configuring and Running Billing.
All events associated with an item must use the same tax method; tax now (real-time taxes) or tax deferred. Nontaxable events are valid in either taxation scenario.
BRM calculates tax as a percentage of the net amount (amount without taxes) of the original item. For example, consider a $110 item that has a 10% tax. The net amount is $100 and tax amount is $10. You perform a 50% adjustment with tax. In this case, the net adjustment amount is $50 and the tax reversal amount is $5 (10% of 50).
When BRM computes tax, it compares the calculated tax amount with the cycle tax's due amount:
If the calculated tax amount is greater than the cycle tax due amount, the cycle tax due amount is transferred to the tax item.
If the calculated tax amount is less than or equal to the cycle tax due amount, the calculated tax amount is used.
Note:
For untaxed adjustments, BRM adjusts the amount but does not calculate or apply a tax reversal for the adjustment amount.To calculate adjustment, dispute, or settlement tax, BRM acquires tax information from one of two sources:
For taxable adjustments, disputes, and settlements at the account, bill, and item level, BRM uses information supplied by a tax configuration file to calculate the tax reversal.
Note:
This tax configuration file supports only a single tax code, that is, for account-, bill- and item-level adjustments, the tax reversal would happen as per the single tax code mentioned in the configuration object.For taxable adjustments, disputes, and settlements at the event level, BRM obtains tax information from the event itself if BRM is configured for the tax now method. Otherwise, BRM obtains the taxes from the /event/billing/cycle/tax object.
In either case, this information typically includes the event type, tax supplier, and tax code. BRM uses this information in concert with the tax locale determined at bill run time to calculate the adjustment tax. For information on tax suppliers and tax codes, see "About Calculating Taxes" in BRM Calculating Taxes.
For BRM to correctly apply adjustment, dispute, and settlement taxes, you must configure tax information for events, define characteristics such as whether BRM should defer taxes, and set up tax defaults for Customer Center. For more information, see "About Configuring Taxes for Adjustments, Disputes, and Settlements".
If the adjustment occurs at the account, subscription service, or member service level, BRM uses the total amount of the adjustment, without consideration of the specific events that are included in the adjustment.
For bill-level, item-level, and event-level adjustments, BRM distinguishes between items and events that need real-time taxes and those that need deferred taxes. If some adjusted items or events are nontaxable, BRM omits these from the deferred amount that it will transfer for taxation during billing. For partial adjustments, BRM also proportions the deferred amount according to how much of an adjustment was actually granted.
For bill-level and item-level disputes and settlements, real-time taxes are applied at the time the dispute or settlement is created. When processing a dispute or settlement with deferred taxes, BRM determines whether the original item has been billed. If billing has not yet occurred, BRM has not levied the tax for the original item. In this case, there is no need apply the taxes separately because the dispute or settlement will have acted on the balance of the original item before BRM ever calculates the taxes for that item.
However, if the dispute or settlement is opened against an item that has already been billed, the customer has already been charged tax for the item. In this case, BRM must specifically accommodate dispute or settlement tax. BRM defers applying the tax reversal amount until billing is run.
For partial disputes and settlements, BRM proportions the deferred amount in accordance with the relative size of the dispute or settlement.
Depending on tax law, jurisdictions, and other factors, you may need to specify whether to apply a tax reversal when performing certain adjustments, disputes, and settlements. For example, the law may require that you reverse taxes for any adjustment you apply to a charge for a call placed outside the country, but not require you to reverse taxes for adjustments to prepaid balances.
As a prerequisite for all but the event-level adjustment, dispute, and settlement opcodes, you must load a /config/ar_taxes object that defines tax treatment parameters for each event type. BRM uses this object to enrich the adjustment, dispute, and settlement opcode flists with the tax information needed to calculate the tax reversal. You load /config/ar_taxes by running a configuration utility against a pin_config_ar_taxes.xml file you create. For more information, see "About the pin_config_ar_taxes.xml File".
To specify whether tax reversals occur when performing certain adjustments, disputes, and settlements, set the value of the PIN_FLD_FLAGS field in the input flist of the appropriate opcode. See "Configuring the Tax Treatment for Adjustments, Disputes, and Settlements".
To specify that tax reversals occur at the time account-level adjustments are created rather than deferring them until billing, modify the Connection Manager (CM) pin.conf file. For event, item, and bill level A/R actions, the time at which tax reversals occur is determined by the rate plan associated with the event. See "Configuring the Default Tax Method for Account-Level Adjustments".
If you use Customer Center, the tax reversal entry in the pin.conf file is ignored. Instead, you use the Customer Center Configurator to set up the tax treatment. See "Configuring the Default Tax Treatment for Customer Center".
The pin_config_ar_taxes.xml file provides information on the tax supplier and tax code for each adjustment, dispute, and settlement event type.
The tax suppliers you specify in the pin_config_ar_taxes.xml file must be listed in the tax_supplier_map file.
The tax code you use in the pin_config_ar_taxes.xml file must be present in the taxcodes_map file. The tax code is mapped to a package that calculates tax for that product type, and can be a numeric or descriptive string.
For information on tax suppliers, tax codes, the associated map files, see "About Supplying the Data Needed for Calculating Taxes" in BRM Calculating Taxes.
The pin_config_ar_taxes.xml file must follow all standard XML formatting rules. The following example shows a typical pin_config_ar_taxes.xml file.
Note:
The <Name> field in the sample identifies the tax supplier.
<?xml version="1.0" encoding="UTF-8" ?>
<AccountReceivablesConfiguration>
<TaxConfigurationList>
<TaxConfiguration>
<Event>/event/billing/adjustment/item</Event>
<Name>ABC Inc - California branch</Name>
<TaxCode>usage</TaxCode>
</TaxConfiguration>
<TaxConfiguration>
<Event>/event/billing/dispute/item</Event>
<Name>ABC Inc - California branch</Name>
<TaxCode>usage</TaxCode>
</TaxConfiguration>
<TaxConfiguration>
<Event>/event/billing/settlement/item</Event>
<Name>ABC Inc - New Jersey branch</Name>
<TaxCode>usage</TaxCode>
</TaxConfiguration>
<TaxConfiguration>
<Event>/event/billing/adjustment/account</Event>
<Name>ABC Inc - Illinois branch</Name>
<TaxCode>cycle</TaxCode>
</TaxConfiguration>
</TaxConfigurationList>
</AccountReceivablesConfiguration>
Important:
Before you load the tax configuration, you must first load the tax suppliers. See "About Defining Tax Suppliers" in BRM Calculating Taxes.To load the tax configuration, edit the sample pin_config_ar_taxes.xml file, then run the "load_pin_ar_taxes" utility to load the contents into the /config/ar_taxes object in the BRM database:
Important:
To connect to the BRM database, load_pin_ar_taxes needs a configuration file in the directory from which you run the utility. For more information, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.Caution:
The load_pin_ar_taxes utility overwrites the existing tax information that BRM uses for the various adjustment and dispute events types. If you are updating the current tax information base to add event types or change the tax specifications for an event type, you cannot load the new tax information only. You must load complete sets of tax information for all event types each time you run the load_pin_ar_taxes utility.Edit the sample pin_config_ar_taxes.xml file in the BRM_Home/sys/data/config/ directory.
Note:
You can rename the file and save it at a location of your choice.Save the pin_config_ar_taxes.xml file.
Use the following command to run the load_pin_ar_taxes utility:
load_pin_ar_taxes input_file.xml
If the tax configuration XML file is not in your working directory, use the full path to the file:
load_pin_ar_taxes -f /files/tax_config/input_file.xml
Stop and restart the Connection Manager (CM) and, if necessary, your client application.
For more information on restarting CM, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To verify that the pin_config_ar_taxes.xml file was loaded, you can display the /config/ar_taxes object by using the Object Browser, or use the robj command with the testnap utility. (See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.)
By default, BRM defers calculating tax for all account-level adjustments until the end of the billing cycle. To change this so that BRM calculates tax when the adjustment is created, add an entry to the pin.conf file.
To enable the tax now feature for account-level adjustments:
Open the Connection Manager configuration file (BRM_Home/sys/cm/pin.conf).
To specify the tax now method, add the following line to the file:
-fm_ar tax_now 1
Note:
If this line is not present in the file, is commented out, or is set to 0, BRM uses the deferred tax method for all account-level adjustments.Important:
To ensure tax calculations are performed correctly, all events associated with an item must use the same tax method; tax now or tax deferred. Tax-exempt events are valid in either taxation scenario.You do not need to restart the CM to enable this entry.
To ensure that you can control whether BRM applies adjustment, dispute, and settlement tax reversals, your CRM implementation should set the following flags in the input flists for all account, bill, and item level adjustment, dispute, and settlement opcodes:
PIN_AR_WITH_TAX: Set this flag for all adjustments, disputes, and settlements that involve a tax reversal.
PIN_AR_WITHOUT_TAX: Set this flag for adjustments, disputes, and settlements that do not require a tax reversal.
If you do not pass in one of the flags, BRM uses the fm_ar tax_reversal_with_tax entry in the CM configuration file to determine the default behavior. This entry takes one of the tax flags (PIN_AR_WITH_TAX or PIN_AR_WITHOUT_TAX). If you do not pass in one of the flags and this entry is not present, BRM does not perform a tax reversal.
Note:
Event-level adjustments, disputes, and settlements use different flags for tax reversal. For more information on tax flags for event-level opcodes, see "Flags for Event Adjustments", "Flags for Event Disputes", and "Flags for Event Settlements".If you are using Customer Center as your CRM application, you can configure a default tax treatment for adjustments, disputes, and settlements. Customer Center uses this configuration to determine whether these activities always have a tax reversal, never have a tax reversal, or have a tax reversal at the CSRs discretion. Configuring a default tax treatment can help you enforce uniform tax treatments for a given location and eliminate the need for a decision by the CSR.
You configure the tax treatment on the Balance tab in the Customer Center Configurator. This configuration overrides any tax treatment specification in the pin.conf file. To set up tax treatment for adjustments, disputes, and settlements, select one of the following options under Tax treatment on the Configurator Balance tab:
Include tax: Always perform a tax reversal for the adjustment, dispute, or settlement.
Exclude tax: Never perform a tax reversal for the adjustment, dispute, or settlement.
None: Allow the CSR to choose whether to include taxes.
For information on using the Customer Center Configurator Balance tab and the implications of these three options, see "Balance Configurator" in BRM Developer's Guide.
To ensure that resources are not misused when a dispute is open, BRM reserves resources disputed at the event level. The reservation process protects the account balance from being credited for the dispute amount until settlement occurs. Resource reservation is particularly important for prepaid accounts, where the dispute amount might incorrectly be added to prepaid resources. For example, if the customer disputed a 10 minute charge on his or her bill, this amount would be credited to the account balance and, for prepaid accounts, would increase the prepaid amount. However, placing a reservation on that 10 minutes lowers the credit limit for the account and prevents the disputed time from being freely used as it would be in a normal credit situation.
When you open a dispute, BRM uses Resource Reservation Manager and new policies you define to create a reservation object for each dispute event. The reservation object prevents the resource associated with the event from being credited to the account; in essence, locking the resource amount until settlement. Upon settlement of the dispute, BRM releases each reservation associated with the dispute and credits the account by subtracting the settlement amount from the Due amount.
BRM performs event-level resource reservation for disputes and settlements using these two policy opcodes:
PCM_OP_RESERVE_POL_POST_DISPUTE creates a /reservation object for each entry in the balance impact arrays for each of the events associated with the dispute item.
PCM_OP_RESERVE_POL_POST_SETTLEMENT changes the PIN_FLD_RESERVATION_STATUS field in each of the /reservation objects for the dispute from 0 to 1, indicating that the resource is now available.
These two opcodes are called by PCM_OP_ACT_USAGE whenever it processes an event-level dispute or settlement, provided the following requirements are met:
You have Resource Reservation Manager, an optional BRM component.
Event notification is enabled in your system.
See "Configuring Event Notification for Disputes and Settlements".
When an event-level dispute is opened or settled, BRM uses event notification to call opcodes that perform the appropriate follow-up operations.
Although any subclass of the /event class can be used to trigger event notification, the dispute and settlement opcodes generate the following events specifically to use for event notification:
/event/billing/dispute/notify: By default, when PCM_OP_AR_EVENT_DISPUTE generates this event and passes it to PCM_OP_ACT_USAGE, PCM_OP_RESERVE_POL_POST_DISPUTE is called.
/event/billing/settlement/notify: By default, when PCM_OP_AR_EVENT_SETTLEMENT generates this event and passes it to PCM_OP_ACT_USAGE, PCM_OP_RESERVE_POL_POST_SETTLEMENT is called.
Before you can use the event-level dispute and settlement feature, you must configure the event notification feature as follows:
If your system has multiple configuration files for event notification, merge them.
See "Merging Event Notification Lists" in BRM Developer's Guide.
Ensure that the merged file includes the following information from the BRM_Home/sys/data/config/pin_notify file:
# Settlements and disputes related event notifications 2354 0 /event/billing/settlement/notify 2355 0 /event/billing/dispute/notify
(Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list.
See "Editing the Event Notification List" in BRM Developer's Guide.
(Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger.
See "Triggering Custom Operations" in BRM Developer's Guide.
Load your final event notification list into the BRM database.
See "Loading the Event Notification List" in BRM Developer's Guide.
For more information, see "Using Event Notification" in BRM Developer's Guide.
Reason codes explain why an adjustment, dispute, or settlement is being granted. In typical implementations, the BRM client application provides the CSR with a selectable set of reasons appropriate to the event type. The CSR chooses a reason that matches the situation or, in some cases, composes a new reason. BRM populates the input flist for the opcode with this information, and the reason is recorded in the /event object that the opcode creates for the adjustment, dispute, or settlement.
Reason codes are stored in the objects based on the /event/billing class, which is the parent class for all adjustment, dispute, and settlement event objects (for example, /event/billing/adjustment/item, /event/billing/dispute/event, and so forth). You typically select from a list of reasons appropriate to the event type, as defined in the reasons.locale configuration file. When Connection Manager starts, BRM uses this file to construct the list of valid adjustment, dispute, or settlement reasons for each event type.
For event-level adjustments, BRM determines whether the reason code you select makes sense for each event in a batch. If the reason for the adjustment is not appropriate for a given event, that event is omitted from the adjustment. For example, if the batch of events to be adjusted includes both dial-up and telco events, and the reason supplied for the adjustment is that invalid roaming charges were applied, BRM excludes the dial-up events from the adjustment since a dial-up service is never subject to roaming charges.
To implement reason codes, you create and load a reasons.locale file that lists each reason code and associates it with a reason code domain. The domain classifies the reason code according to the type of activity it applies to. You can also include information in the reasons.locale file that prevents inappropriate event-level adjustments based on reason code and service.
The reasons.locale file defines each reason code domain, the reason codes that belong to the domain, and the event G/L ID. The domain and reason code information is used to build the /strings object and the event G/L ID is used to build the /config/map_glid object.
For event-level adjustments, you can also define which services are valid for the reason code and specify the valid event types within those services. This information is used to build the /config/reason_code_scope object. For each event in an event-level adjustment batch, BRM checks /config/reason_code_scope to determine whether the associated service and event type are included in the PIN_FLD EVENT array. If they are not, BRM skips the adjustment for that event.
The following example shows a single reasons.locale file segment defining a reason code domain.
Note:
The service block is optional; it is used to define the reason code scope. If you do not include it, BRM adjusts all events in the batch regardless of whether the reason for the adjustment makes sense for the service and event.
DOMAIN = "Reason Codes - Event Adjustment Reasons";
STR
ID = 3;
VERSION = 22;
STRING = "Net Speed Was Slow";
SERVICE
TYPE = "/service/ip";
EVENT
TYPE = "/event/session";
EVENT-END
EVENT
TYPE = "/event/session/dialup";
EVENT-END
SERVICE-END
SERVICE
TYPE = "/service/telco/gsm/data";
EVENT
TYPE = "/event/session/gsm/telco";
EVENT-END
SERVICE-END
EVENT-GLID
"/event/billing/adjustment/event" 105;
EVENT-GLID END
END
For more information on the reasons.locale file, see "String Manipulation Functions" in BRM Developer's Reference.
To define reason codes for adjustments, disputes and settlements, you edit the reasons.en_US sample file in the BRM_Home/sys/msgs/reasoncodes directory. You then use the load_localized_strings utility (see "load_localized_strings" in BRM Developer's Guide) to load the contents of the file into the /strings, /config/map_glid, and /config/reason_code_scope objects.
When you run the load_localized_strings utility, use this command:
load_localized_strings reasons.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.
If you add your own reason codes to the reasons.locale file, you should use IDs above 100,000.
Caution:
The load_localized_strings utility overwrites existing /config/map_glid and /config/reason_code_scope objects. If you are updating these objects, you cannot load new G/L ID maps and reason code scopes only. You must load complete sets of data each time you run the load_localized_strings utility. This is also true when using the /strings object, but only if you specify the -f parameter. Otherwise, the load_localized_strings utility appends the new data to the object.For information on loading the reasons.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide. For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
You can perform adjustments at a variety of levels by calling different adjustment opcodes. Calling the full range of these opcodes through your BRM client application gives you the flexibility of making anything from low-level adjustments against specific events to high-level adjustments distributed across an A/R account and its child accounts. For example, you might implement different adjustment levels to enable the CSR to help a customer who was charged too many minutes for a call and a customer whose prepaid service experienced a 3-day outage.
For background information about adjustments, see "About Adjustments".
For information about performing adjustments in Customer Center, see the Customer Center Help.
Use the following opcodes to perform and customize adjustments:
PCM_OP_AR_ACCOUNT_ADJUSTMENT
See "Adjusting Accounts, Subscription Services, and Member Services".
PCM_OP_AR_BILL_ADJUSTMENT
See "Adjusting Bills".
PCM_OP_AR_ITEM_ADJUSTMENT
See "Adjusting Items".
PCM_OP_BILL_POL_VALID_ADJUSTMENT
PCM_OP_AR_EVENT_ADJUSTMENT
See "Adjusting Events".
PCM_OP_ACT_POL_SPEC_GLID
To make adjustments at the account level, subscription service level, or member service level, use PCM_OP_AR_ACCOUNT_ADJUSTMENT. This opcode debits or credits the currency resource balance for the specified account.
If the input flist specifies a balance group, BRM debits or credits that /balance_group object. If the input flist specifies a bill unit, the adjustment is applied to the default balance group of the bill unit. If the input flist specifies account only, it debits or credits the account-level balance group.
You can open an account-level adjustment with or without tax. For information on how PCM_OP_AR_ACCOUNT_ADJUSTMENT performs adjustments taxation, see "Including Taxes in the Adjustment".
The /event/billing/adjustment/account object records the balance impact. The item_total and due fields of the adjustment item show the amount of adjustment. The adjustment item is billed immediately after the transaction occurs. The status of the item is set to PIN_ITEM_STATUS_OPEN.
If a balance group is not specified in the input flist, PCM_OP_AR_ACCOUNT_ADJUSTMENT adjusts the default account-level balance group. If the input flist identifies a balance group, PCM_OP_AR_ACCOUNT_ADJUSTMENT updates the matching sub-balance or creates a new sub-balance if it cannot find a match. The sub-balance that must be updated is also specified in the input flist.
If your client application enables you to specify a subscription service and a member service in the input flist, you can perform subscription service-level adjustments and member service-level adjustments. These adjustment levels use PCM_OP_AR_ACCOUNT_ADJUSTMENT to perform adjustments against all the services that belong to the balance group, which the /service object supplies.
If an account, subscription service, or member service adjustment is for non-currency resources, use the PCM_OP_BILL_DEBIT opcode to adjust the non-currency resource. For more information on how PCM_OP_BILL_DEBIT works with resources, see "Applying Debits and Credits".
BRM creates a G/L ID for every account-level adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".
When performing account-level, subscription service-level, and member-service level adjustments, set these fields in the PCM_OP_AR_ACCOUNT_ADJUSTMENT input flist:
PIN_FLD_POID for the account to which the adjustment applies. You obtain this value from the /account object that the CSR selects. Account-level, subscription service-level, and member service-level adjustments require this field.
PIN_FLD_BILLINFO_OBJ for the bill unit to which the adjustment applies. The adjustment balance impact is applied to the default balance group of the bill unit.
PIN_FLD_BAL_GRP_OBJ for the balance group to which the adjustment applies. You obtain this value from the /account or /service object that the CSR selects.
This field is used for account-level, subscription service-level, and member service-level adjustments. If you omit this field from the input flist for an account-level adjustment, the adjustment uses the default balance group of the bill unit specified. Otherwise, it uses the account-level balance group. Subscription service-level and member service-level adjustments require PIN_FLD_BAL_GRP_OBJ in the input flist.
PIN_FLD_AMOUNT for the adjustment amount. The value supplied for this field should be negative when crediting and positive when debiting.
PIN_FLD_CURRENCY for the resource to be adjusted.
PIN_FLD_FLAGS for the tax treatment:
PIN_AR_WITHOUT_TAX: The account adjustment is nontaxable.
If the PIN_AR_WITH_TAX: The account adjustment is taxable.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.PCM_OP_AR_ACCOUNT_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Adjustment".
For information on reason codes, see "Including Reason Codes in the Adjustment".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_ACCOUNT_ADJUSTMENT.
If the PCM_OPFLG_READ_RESULT flag is set, all the 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 created. The fields that would have been used to create the event object and adjustment item are returned to the caller.
If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/adjustment/account object is created to record details of the operation.
To make adjustments at the bill level, use PCM_OP_AR_BILL_ADJUSTMENT. This opcode debits or credits a currency balance for the specified /bill object. You can open a bill-level adjustment with or without tax. For information on how PCM_OP_AR_BILL_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".
Important:
PCM_OP_AR_BILL_ADJUSTMENT does not check to determine whether the item you are adjusting is billed yet. However, using this opcode to adjust pending items is not recommended. If you try to adjust pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any adjustments against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_BILL_ADJUSTMENT does not make adjustments when:
The specified bill is not an A/R bill; for example, a bill from a nonpaying subordinate bill unit.
The amount of the adjustment exceeds the total amount of the bill. For example, if the bill due is $5, you cannot perform a credit adjustment for $6. Similarly, if the bill due -$5, you cannot perform a debit adjustment for $6.
However, if a bill is fully or partially paid, PCM_OP_AR_BILL_ADJUSTMENT does not make adjustments when the amount of the adjustment exceeds the remaining due amount of the bill. To use PCM_OP_AR_BILL_ADJUSTMENT to adjust the total amount of a fully or partially paid bill, see "Adjusting Fully or Partially Paid Bills".
Bill-level adjustments can be performed against the entire bill or just specific bill items. When it receives an input flist, PCM_OP_AR_BILL_ADJUSTMENT creates a single, umbrella adjustment item for all bill items that require adjustment, as follows:
If the input flist specifies individual bill items, the adjustment item is associated with each of these bill items. You must specify the adjustment amount for each bill item in the flist.
If the flist does not specify any bill items, all bill items are eligible for adjustment. PCM_OP_AR_BILL_ADJUSTMENT opens adjustments for as many bill items as it can before it consumes the adjustment amount or percentage. In this case, the adjustment item will cover only those bill items that PCM_OP_AR_BILL_ADJUSTMENT was able to fully or partially adjust before using up the adjustment amount or, if the adjustment is defined as a percentage of the bill, the specified percentage.
In either case, PCM_OP_AR_BILL_ADJUSTMENT passes the POID of the adjustment item and the appropriate adjustment amount to PCM_OP_AR_ITEM_ADJUSTMENT, which performs the adjustment for each of the associated bill items. An /event/billing/adjustment/item object is created for each adjusted item in the bill, recording the balance impact. The due fields of the adjustment items become 0 after the adjustment and the status of the item is set to PIN_ITEM_STATUS_CLOSED. For details on how PCM_OP_AR_ITEM_ADJUSTMENT works, see "Adjusting Items".
Before passing the adjustment item and amount to the PCM_OP_AR_ITEM_ADJUSTMENT opcode, PCM_OP_AR_BILL_ADJUSTMENT determines whether the adjustment has tax implications. If so, it checks the original /item object to determine the taxable portion of the item:
If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.
If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.
If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the adjustment tax reversal only for the usage amount and not the tax amount.
For each item that can be adjusted, the opcode checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the adjustment tax reversal. As a result of eliminating any non-taxable components of the original item, the adjustment tax is calculated proportionally to the actual taxable amount of the item.
If the adjustment fails, PCM_OP_AR_BILL_ADJUSTMENT returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.
BRM creates a G/L ID for every bill-level adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".
When performing bill-level adjustments, set these fields in the PCM_OP_AR_BILL_ADJUSTMENT input flist:
PIN_FLD_POID for the bill to which the adjustment applies. You obtain this from the /bill object that the CSR identifies. The adjusted amount is applied to the default balance group of the bill unit associated with the bill.
PIN_FLD_POID for the items to be adjusted under the PIN_FLD_ITEMS array. This array is required only to adjust a particular set of bill items within the bill.
Important:
This field must be at level 1 of the input flist in order for the item adjustment to work.PIN_FLD_AMOUNT for the adjustment amount. The value supplied for this field should be negative when crediting and positive when debiting.
You can specify the adjustment amount through either PIN_FLD_AMOUNT or PIN_FLD_PERCENT. The PIN_FLD_AMOUNT field is mandatory and the PIN_FLD_PERCENT field is optional. If the input flist includes both fields, BRM uses the value in PIN_FLD_PERCENT and ignores the value in PIN_FLD_AMOUNT.
You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the adjustment is against an array of bill items, for the individual bill items. If you are performing an adjustment that credits the bill, the absolute value of PIN_FLD_AMOUNT must be greater than 0 and less than the total bill amount and its sign should be negative.
PIN_FLD_FLAGS for the tax treatment:
PIN_AR_WITHOUT_TAX: The bill adjustment is nontaxable.
If the PIN_AR_WITH_TAX: The bill adjustment is taxable.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.Note:
If the bill adjustment is taxable, the absolute value of PIN_FLD_AMOUNT must be less than or equal to the total bill amount excluding the tax amount.PCM_OP_AR_BILL_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Adjustment".
For information on reason codes, see "Including Reason Codes in the Adjustment".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_BILL_ADJUSTMENT.
BRM creates a G/L ID for every bill-level adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".
If the PCM_OPFLG_READ_RESULT flag is set, all the 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 created. The fields that would have been used to create the event object and adjustment item are returned to the caller.
If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/adjustment/item object is created to record details of the operation.
You can use PCM_OP_AR_BILL_ADJUSTMENT to perform bill-level adjustments for fully or partially paid bills. By default, PCM_OP_AR_BILL_ADJUSTMENT makes adjustments only up to the remaining due amount of a bill if the bill is fully or partially paid.
To use PCM_OP_AR_BILL_ADJUSTMENT to make adjustments up to the total amount of a fully or partially paid bill, set the BillPaymentDeallocation field in the ar instance of the /config/business_params object to enabled. See "Improving Bill-Level Adjustments for Fully or Partially Paid Bills".
When the BillPaymentDeallocation field is enabled, you can use PCM_OP_AR_BILL_ADJUSTMENT to adjust the total bill amount for a fully or partially paid bill. The amount of adjustment for the bill can be more than the remaining due, but it cannot exceed the total bill amount. For example, if the total bill amount is $5 and you have already made a partial payment of $2, the remaining due is $3. In this scenario, you can perform a credit adjustment for up to $5 (total bill amount).
However, if there is an A/R action (such as an adjustment or a dispute) already performed on the bill, you can perform adjustments for only up to the amount due after the initial A/R action is performed. For example, if an item-level adjustment of $1 is made on a bill of $5 and you have already made a partial payment of $2, the remaining due is $2. In this scenario, you can perform a credit adjustment for only up to $4 (which is the amount due after item-level adjustment).
In case if the payment already made for the bill is more than the bill amount due after adjustment, the excess amount is left unallocated and it is displayed as Adjustment/payments not applied in Customer Center.
By default, PCM_OP_AR_BILL_ADJUSTMENT does not perform bill-level adjustments for an amount more than the remaining due amount if the bill is fully or partially paid.
You can improve bill-level adjustments for fully or partially paid bills by setting the BillPaymentDeallocation field in the ar instance of the /config/business_params object to enabled.
To improve bill-level adjustments for fully or partially paid bills:
Use the following command to create an editable XML file for the BusParamsAR parameter class:
pin_bus_params -r BusParamsAR bus_params_AR.xml
This command creates the XML file named bus_params_AR.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.
Search the XML file for following line:
<BillPaymentDeallocation>disabled</BillPaymentDeallocation>
Change disabled to enabled.
Caution:
BRM uses the XML in this file to overwrite the existing /config/business_params object for the ar instance. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRM's billing configuration.Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_AR.xml
You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see pin_bus_params.
Read the object with the testnap utility or the Object Browser to verify that all fields are correct.
See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.
Stop and restart the Connection Manager (CM). For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in the BRM System Administrator's Guide.
To make adjustments at the item level, use PCM_OP_AR_ITEM_ADJUSTMENT. This opcode debits or credits a currency resources for the bill item specified in the input flist. The item adjustment balance impact is applied to the default balance group of the bill unit that is associated with the bill item. This opcode is also called by PCM_OP_AR_BILL_ADJUSTMENT to adjust items in a bill.
Important:
PCM_OP_AR_ITEM_ADJUSTMENT does not check to determine whether the item you are adjusting is billed yet. However, using this opcode to adjust pending items is not recommended. If you try to adjust pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any adjustments against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_ITEM_ADJUSTMENT does the following:
Reads the original /item object and prepares the changes to reflect the balance impact of the adjustment.
For credit adjustments, these changes reduce the Due amount (PIN_FLD_DUE) for the item. For debit adjustments, the opposite occurs.
Calls the PCM_OP_BILL_POL_VALID_ADJUSTMENT policy opcode to validate the changes.
You can customize the validation criteria for PCM_OP_BILL_POL_VALID_ADJUSTMENT. For information on customizing the opcode, see "Customizing Item-Level Adjustments".
Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.
If so, PCM_OP_AR_ITEM_ADJUSTMENT checks the contents of the field to determine:
Whether the field contains a POID, indicating that the opcode is being called by PCM_OP_AR_BILL_ADJUSTMENT to complete a bill-level adjustment.
This POID identifies the /item/adjustment object that PCM_OP_AR_BILL_ADJUSTMENT created to store information on the bill-level adjustment. This is the /item/adjustment object that PCM_OP_AR_ITEM_ADJUSTMENT will associate with each of the adjustment events it creates for the bill-level adjustment.
Whether the field is NULL, indicating that the opcode is being called directly from the client application to perform an item-level adjustment. In this case, PCM_OP_AR_ITEM_ADJUSTMENT will create its own /item/adjustment object. This object is exclusive to the individual item being adjusted.
If the adjustment has tax implications and the opcode is not being called as part of a bill-level adjustment, checks the original /item object to determine the taxable portion of the item:
If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.
If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.
If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the adjustment tax reversal only for the usage amount and not the tax amount.
For each item that it can adjust, the opcode checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the adjustment tax reversal.
As a result of eliminating any non-taxable components of the original item, the adjustment tax is calculated proportionally to the actual taxable amount of the item.
Note:
If the item adjustment is being performed as part of a bill-level adjustment, the PCM_OP_AR_BILL_ADJUSTMENT opcode performs this step before calling PCM_OP_AR_ITEM_ADJUSTMENT.Creates an /event/billing/adjustment/item object.
If the item adjustment is part of a bill-level adjustment, the event object for each adjusted item is associated with a single, umbrella /item/adjustment object.
Examines the flags in the input flist to determine whether the adjustment has any tax implications.
For information on how PCM_OP_AR_ITEM_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".
Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.
If the Due amount after adjustment is 0 and there are no open disputes, PCM_OP_AR_ITEM_ADJUSTMENT sets the PIN_ITEM_STATUS field to CLOSED.
If an over-adjustment is made on an item, the following occurs:
For deferred taxation, the adjustment amount is left unallocated in the adjustment item. If the tax to be adjusted is greater than the cycle tax amount, then the cycle tax item is adjusted for its due amount.
For tax now taxation, the excess adjustment amount is left unallocated in the adjustment item. This appears in Customer Center as Adjustment/payments not applied.
Writes the modified version of the original /item object.
Provides feedback on whether the adjustment was successfully created.
If the adjustment creation failed, it indicates the reason for the failure.
BRM creates a G/L ID for item-level adjustments. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".
When performing item-level adjustments, set these fields in the input flist:
PIN_FLD_POID for the item to be adjusted. The adjusted amount is applied to the default balance group of the bill unit associated with the item.
PIN_FLD_AMOUNT for the adjustment amount. The value should be negative when crediting and positive when debiting.
PIN_FLD_CURRENCY for the resource to be adjusted.
PCM_OP_AR_ITEM_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Adjustment".
For information on reason codes, see "Including Reason Codes in the Adjustment".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_ITEM_ADJUSTMENT.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_ADJUSTMENT returns not only the POID, but all the fields in the /event/billing/adjustment/item object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_ADJUSTMENT does not change any fields in the database and does not create an /event/billing/adjustment/item object. However, it does provide an adjustment calculation to the caller by returning the fields that would have been used to create the event object and adjustment item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_ADJUSTMENT behaves in a standard manner, creating an /event/billing/adjustment/item object to record details of the operation.PIN_FLD_FLAGS for the tax treatment:
PIN_AR_WITHOUT_TAX flag: The item adjustment is nontaxable.
PIN_AR_WITH_TAX flag: The item adjustment is taxable. Tax is reversed on an item-by-item basis.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.When you initiate a bill-level or item-level adjustment, PCM_OP_AR_ITEM_ADJUSTMENT calls the PCM_OP_BILL_POL_VALID_ADJUSTMENT policy opcode to validate all proposed changes to the fields in the original /item object. This opcode checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.
To customize the adjustment validation criteria, use the PCM_OP_BILL_POL_VALID_ADJUSTMENT policy opcode. Changing a result from PIN_BOOLEAN_FALSE to PIN_BOOLEAN_TRUE enables the specified field value to pass. Changing a result from PIN_BOOLEAN_TRUE to PIN_BOOLEAN_FALSE causes the specified field value to fail.
To make adjustments at the event level, use PCM_OP_AR_EVENT_ADJUSTMENT. This opcode debits or credits a resources for a particular event.
PCM_OP_AR_EVENT_ADJUSTMENT receives a list of events to be adjusted as a batch on the input flist, and returns the adjusted /event/billing/adjustment/event data on the output flist. Events that can be adjusted are stored in the /config/adjustment/event object. There can be multiple events in a given batch, and the events to be adjusted do not need to belong to the same account specified in the PIN_FLD_POID for PCM_OP_AR_EVENT_ADJUSTMENT. Events that can be adjusted are defined in the init_objects.source file and stored in the /config/adjustment/event object.
If you are adjusting pending items, you can ensure proper recording of the adjustment in the General Ledger by using PCM_OP_AR_EVENT_ADJUSTMENT to create a shadow adjustment rather than the standard event-level adjustment you would normally want to create for a billed item. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment" and "Categorizing Unbilled Event-Level Adjustments in G/L Reports".
By default, the adjustable events are:
/event/billing/debit
/event/billing/product/fee/cycle/cycle_arrear
/event/session/dialup
/event/billing/product/fee/purchase
/event/billing/product/fee/cancel
/event/billing/product/fee/cycle/cycle_forward_monthly
/event/billing/product/fee/cycle/cycle_forward_bimonthly
/event/billing/product/fee/cycle/cycle_forward_quarterly
/event/billing/product/fee/cycle/cycle_forward_semiannual
/event/billing/product/fee/cycle/cycle_forward_annual
/event/billing/product/fee/cycle/cycle_forward_arrear
If you create custom events that you must adjust or if you must adjust additional events, use PCM_OP_WRITE_FLDS to add additional event types to the /config/adjustment/event object.
When PCM_OP_AR_EVENT_ADJUSTMENT receives a batch of events, it:
Identifies all events in the batch to be adjusted, and runs the validation checks against those events.
If the event has any tax implications, the tax implications must be adjusted.
For information on how PCM_OP_AR_EVENT_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".
Creates a single /item/adjustment object for all the events in the batch for the account.
For each event to be adjusted for an account, a new /event/billing/adjustment/event object containing the amount to be adjusted is created.
The /event/billing/adjustment/event object has the PIN_FLD_ITEM_OBJ pointing to the adjustment item created in step 3.
After the adjustment item and the /event/billing/adjustment/event object are created, the amount is transferred from the adjustment item to the original item where the adjusted event belongs.
The original item may or may not be open. If the transfer happens to a closed item, the closed item will be reopened automatically.
Note:
Once the entire Due amount from the adjustment item is transferred to other items, the adjustment item will be closed.BRM creates a G/L ID for event-level adjustments.
For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment" and "Categorizing Unbilled Event-Level Adjustments in G/L Reports".
When performing adjustment, set these fields in the input flist:
PIN_FLD_POID for each of the events to be adjusted. The adjusted amount is applied to the default balance group of the bill unit associated with the /item object that the event belongs to.
PIN_FLD_AMOUNT or PIN_FLD_PERCENT for the adjustment amount. The value supplied for this field should be positive for adjustments that credit the event and negative for adjustments that debit the event. If you omit both of these fields, BRM adjusts the entire amount for each event.
PIN_FLD_RESOURCE_ID for the resource to be adjusted.
PCM_OP_AR_EVENT_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Adjustment".
For information on reason codes, see "Including Reason Codes in the Adjustment".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_EVENT_ADJUSTMENT.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_ADJUSTMENT returns not only the POID, but all the fields in the /event/billing/adjustment/event object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_ADJUSTMENT does not change any fields in the database and does not create an /event/billing/adjustment/event object. However, it does provide an adjustment calculation to the caller by returning the fields that would have been used to create the event object and adjustment item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_ADJUSTMENT behaves in a standard manner, creating an /event/billing/adjustment/event object to record details of the operation.If the PIN_ADJ_NO_TAX flag is set, the event adjustment is nontaxable. If this flag is not set, the adjustment is taxable.
If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is adjusted; not the event itself.
Important:
Do not set this flag for adjustments against unbilled events that use deferred taxation.If the PIN_EVENT_ADJ_BATCH is set, the adjustment amount will be distributed among the events in the batch on a first-come-first-serve basis until the adjustment amount is consumed.
If the PIN_EVENT_ADJ_EVENT is set, the adjustment amount will be applied individually to each of the events in the batch.
If the PIN_EVENT_ADJ_FOR_RERATE flag is set, the adjustment is the result of rerating the original event.
If the PIN_AR_RECORD_SHADOW_ADJUSTMENT_EVENT is set, BRM creates a shadow adjustment instead of an /event/billing/adjustment/event object. This flag should be set when the event being adjusted is pending and results in the adjustment being recorded as unbilled in the General Ledger.
To report adjustments as unbilled in the G/L, use PCM_OP_AR_EVENT_ADJUSTMENT to create shadow event objects instead of adjustment event objects. A shadow event object is a new version of the original event object. It is identical to the original event object except for a new creation timestamp and a new balance impact resulting from the event adjustment.
To create shadow adjustments, set the value of the PIN_FLD_FLAGS field at the top level to 1 (PIN_AR_RECORD_SHADOW_ADJUSTMENT_EVENT) on the PCM_OP_AR_EVENT_ADJUSTMENT input flist. The shadow object is created only if the original event to be adjusted has not been billed or posted to a G/L report.
Note:
When the PIN_FLD_FLAGS field is not present in the input flist, BRM creates an /event/billing/adjustment/event object by default.Unlike standard event-level adjustments, when creating shadow events, only one event should be present on the input flist.
As with standard event-level adjustments, you can adjust both currency and non-currency resources. Regardless of whether PCM_OP_AR_EVENT_ADJUSTMENT is performing a standard or shadow adjustment, it only adjusts the resources specifically indicated in the input flist; it does not automatically adjust all resources for an event.
For information on the shadow adjustment flags, see "Flags for Event Adjustments".
You can specify an optional tax treatment for adjustments through flags in the input flist. For information, see:
If the input flist flags the adjustment as taxable or the pin.conf file specifies that BRM tax all adjustments, the opcode obtains tax information from a configuration file read into BRM when Connection Manager starts. For information on loading this tax information into BRM, see "Loading the Tax Configuration into the BRM Database".
The PCM_OP_AR_ACCOUNT_ADJUSTMENT opcode uses this information as follows:
If adjustment tax method is tax now, it uses this information to calculate the tax and apply it immediately.
If adjustment tax method is tax deferred, it enriches the input flist with this information, and then passes it to PCM_OP_ACT_USAGE for deferred tax calculation.
If the input flist flags the adjustment as taxable or the pin.conf file specifies that BRM tax all adjustments, the opcode obtains tax information from a configuration file read into BRM when Connection Manager starts.
The PCM_OP_AR_ITEM_ADJUSTMENT and PCM_OP_AR_BILL_ADJUSTMENT opcodes perform either of the following two actions:
If the adjustment tax method is tax now, the opcodes use information from the event associated with the original bill item to calculate taxes and apply the amount immediately with the adjustment amount.
If the adjustment tax method is tax deferred, the taxes are contained in the tax item. In such cases, PCM_OP_AR_ITEM_ADJUSTMENT does the following to handle the taxes:
Calls PCM_OP_BILL_TAX_EVENT to calculate the tax amount.
Compares the calculated tax with the due amount of the tax item to determine the amount to reverse.
Creates the /event/billing/adjustment/tax_event event to contain the tax amount.
Transfers the calculated tax amount to the original tax item.
The due amount is reduced by the adjustment amount excluding the tax amount.
Validations are made to ensure that an item's net amount and cycle tax amount are not over-adjusted during an adjustment. If the adjustment amount is greater than the item's due amount, the excess amount is left unallocated in the adjustment item and must be allocated either manually or when the next payment is applied on the account. The tax amount is always adjusted to the maximum amount due in the tax item.
Note:
The adjustment tax method (tax now or tax deferred) is determined based on whether the events associated with the item are taxed at event time or at bill time.If the input flist flags the adjustment as taxable, the event adjustment opcode performs one of two steps:
If adjustment tax method is tax now, the opcode uses information from the adjusted event to calculate the tax and apply it immediately.
If adjustment tax method is tax deferred, the opcode uses information from the /event/billing/cycle/tax object to calculate the adjustment tax. When it has calculated the tax, it creates the /event/billing/adjustment/tax_event event.
Note:
If the adjustment is created in the same billing cycle as the adjusted item, the original item will not have been taxed yet. In this case, there is no need to create the /event/billing/adjustment/tax_event event because the adjustment precedes initial tax calculation for the original item.Reason codes explain why an adjustment is being granted. In typical implementations, the BRM client application provides a selectable set of reasons appropriate to the event type. You choose a reason that matches the situation or, in some cases, compose a new reason. The client application populates the input flist for the opcode with this information, and BRM records the reason in the adjustment event object (for example, /event/billing/adjustment/item or /event/billing/adjustment/event). The flist fields that provide reason code information are PIN_FLD_REASON_ID and PIN_FLD_REASON_DOMAIN_ID. These fields are optional.
For event-level adjustments, you can filter a batch of adjustments based on the reason code supplied in the input flist. If the input flist for PCM_OP_AR_EVENT_ADJUSTMENT includes a reason code and domain, PCM_OP_AR_EVENT_ADJUSTMENT performs a validation check of the reason code. It does so by comparing the reason code in its input flist against a stored global flist created by reading reason code configuration information from the /config/reason_code_scope object at Connection Manager (CM) start time. The global flist serves as a filter that indicates all the reason codes that are valid for a given event and service type.
Reason code validation produces these results:
For all instances where the reason code is valid for the event and associated service, the opcode proceeds with the adjustment.
For each instance where the reason code is not valid, the opcode indicates the failure in the PIN_FLD_RESULTS field for the output flist and describes the problem in the PIN_FLD_DESCR field.
For general information about reason codes, see "String Manipulation Functions" in BRM Developer's Reference. For information about setting up reason codes for adjustments, see "Working with Reason Codes for Adjustment, Disputes, and Settlements".
The G/L ID for an adjustment event is assigned like other pre-rated events in the BRM system. The PCM_OP_ACT_POL_SPEC_GLID policy opcode assigns the G/L ID for the adjustment. The PIN_FLD_GL_ID field in the /event/billing/adjustment/event object points to the same G/L ID as the original event, ensuring that both the original event and the adjustment are correctly recorded in the general ledger. For information on preconfiguring the adjustment event to modify the /config/map_glid configuration object, see "Assigning G/L IDs to Nonrated Events" in BRM Collecting General Ledger Data.
For background information, see "About Adjustments".
To apply debits and credits to the non-currency resources, use PCM_OP_BILL_DEBIT.
Customer Center calls PCM_OP_BILL_DEBIT to debit sub-balances for a specific /balance_group object associated with an account.
There are three ways to use PCM_OP_BILL_DEBIT:
Pass in the POID of an account to impact that account's default /balance_group object.
Pass in the POID of a specific balance group to impact that /balance_group object.
For either the account or a balance group, pass in a specific sub-balance to impact that sub-balance.
The PIN_FLD_DEBIT array on the input object contains the amount of the resource to debit. The amount is a signed value, so the result can be a debit (positive value) or a credit (negative value) to the resource.
The PIN_FLD_SUB_BALANCES array contains a specific element ID, or uses PIN_ELEMID_ASSIGN to identify or create the specific sub-balance to receive the debit.
You specify validity information using the VALID_FROM and VALID_TO fields on the PIN_FLD_SUB_BALANCES array to credit or debit a sub-balance for specific dates. These are usually used with the PIN_ELEMID_ASSIGN field to specify a sub-balance to credit or debit.
Note:
If you are performing a non-currency account-level or service-level adjustment, PCM_OP_BILL_DEBIT determines whether the sub-balance being adjusted is still open. Open sub-balances are those whose VALID_TO date has not yet been reached. If the sub-balance is no longer open, the opcode creates a new sub-balance for the adjustment. This sub-balance has the same validity period as the sub-balance you were trying to adjust.If validity information is not specified, PCM_OP_BILL_DEBIT updates the "most valid" sub-balance first, and then continues through the rest of the sub-balances until the debit amount is used up. If no other sub-balances are left, or if there were no valid sub-balances to begin with, PCM_OP_BILL_DEBIT it creates a new sub-balance to hold the debit amount.
Note:
You can change the order in which PCM_OP_BILL_DEBIT updates sub-balances. For information, see "Specifying the Order in Which Resource Sub-Balances Are Consumed" in BRM Setting Up Pricing and Rating.
PCM_OP_BILL_DEBIT opens a local transaction.
If the PCM_OPFLG_READ_RESULT flag is set, all the fields in the event object are returned and not just 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/debit object is created to record the details of the operation.
You can create disputes and settlements at a variety of levels by calling different dispute and settlement opcodes. As with adjustments, using the full range of these opcodes lets you process anything from a low-level dispute for a specific event to a higher-level dispute against an entire bill.
For information on creating disputes and settlements in Customer Center, see the Customer Center Help.
Use the following opcodes to perform and customize disputes and settlements:
PCM_OP_AR_BILL_DISPUTE
See "Disputing Bills".
PCM_OP_AR_BILL_SETTLEMENT
PCM_OP_AR_ITEM_DISPUTE
See "Disputing Items".
PCM_OP_AR_ITEM_SETTLEMENT
PCM_OP_BILL_POL_VALID_DISPUTE
PCM_OP_AR_EVENT_DISPUTE
See "Disputing Events".
PCM_OP_AR_EVENT_SETTLEMENT
PCM_OP_ACT_POL_SPEC_GLID
To open a dispute at the bill level, use PCM_OP_AR_BILL_DISPUTE. This opcode debits or credits a currency balance for the specified /bill object. You can open a bill-level dispute with or without tax. For information on how PCM_OP_AR_BILL_DISPUTE performs dispute taxation, see "Including Taxes in the Dispute or Settlement".
Important:
PCM_OP_AR_BILL_DISPUTE does not check to determine whether the item you are disputing is billed yet. However, using this opcode to dispute pending items is not recommended. If you try to dispute pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any disputes against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_BILL_DISPUTE does not create disputes when:
The specified bill is not an A/R bill; for example, a bill from a nonpaying subordinate bill unit.
The amount of the dispute exceeds the total amount of the bill against which the dispute applies. For example, if the bill due is $5, you cannot open a credit dispute for $6. Similarly, if the bill due -$5, you cannot open a debit dispute for $6.
Bill-level disputes can apply to the entire bill or to specific bill items. When PCM_OP_AR_BILL_DISPUTE receives an input flist, it creates a single, umbrella dispute item for all bill items covered by the dispute, as follows:
If the input flist specifies individual bill items, the dispute item is associated with each of these bill items. Further, the dispute amount for each bill item is equivalent to the entire due for that item unless otherwise specified in the input flist.
If the flist does not specify any bill items, all bill items are eligible for dispute. PCM_OP_AR_BILL_DISPUTE opens disputes for as many bill items as it can before it consumes the dispute amount. In this case, the dispute item will cover only those bill items that the opcode was able to fully or partially dispute before using up the dispute amount. If the input flist does not supply a dispute amount, BRM uses amounts equivalent to the entire due for each dispute item.
In either case, PCM_OP_AR_BILL_DISPUTE passes the POID of the dispute item and the appropriate dispute amount to PCM_OP_AR_ITEM_DISPUTE, which opens the dispute for each of the associated bill items and creates the dispute events. An /event/billing/dispute/item object is created for each disputed item in the bill, recording the balance impact. The bill dispute event balance impact is applied to the default balance group of the bill unit associated with the bill. For details on how PCM_OP_AR_ITEM_DISPUTE works, see "Disputing Items".
Before passing the dispute item and amount to the PCM_OP_AR_ITEM_DISPUTE opcode, PCM_OP_AR_BILL_DISPUTE determines whether the dispute has tax implications. If so, it checks the original /item object to determine the taxable portion of the item:
If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.
If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.
If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the dispute tax reversal only for the usage amount and not the tax amount.
For each item that can be disputed, the opcode checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the dispute tax reversal. As a result of eliminating any non-taxable components of the original item, the dispute tax is calculated proportionally to the actual taxable amount of the item.
If the dispute fails, PCM_OP_AR_BILL_DISPUTE returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.
BRM creates a G/L ID for every bill-level dispute. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the input flist when creating bill-level disputes:
PIN_FLD_POID for the bill under dispute. You obtain this from the /bill object that the CSR identifies through the client application. The disputed amount is applied to the default balance group of the bill unit associated with the bill.
PIN_FLD_POID for the item under dispute. This field is only required to dispute a particular set of bill items within the bill.
PIN_FLD_AMOUNT for the dispute amount. The value supplied for this field should be negative when crediting and positive when debiting. This field is optional.
You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the dispute is against an array of bill items, for the individual bill items. If PIN_FLD_AMOUNT is NULL for a dispute, BRM assumes that the dispute is for the entire amount of the bill or the individual bill items, as appropriate. If you are performing a dispute that credits the bill, the absolute value of PIN_FLD_AMOUNT must be greater than 0 and less than the total bill amount and its sign should be negative.
PIN_FLD_CURRENCY for the resource to be disputed.
PCM_OP_AR_BILL_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_BILL_DISPUTE.
If the PIN_AR_WITHOUT_TAX flag is set, the dispute is nontaxable.
If the PIN_AR_WITH_TAX flag is set, the dispute is taxable. Tax is reversed on an item-by-item basis.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The dispute is nontaxable if the pin.conf entry is absent.For information on flags that indirectly affect PCM_OP_AR_BILL_DISPUTE, see "Flags for Item Disputes".
To settle a dispute at the bill level, use PCM_OP_AR_BILL_SETTLEMENT. This opcode debits or credits a currency balance for the specified /bill object. You can create a bill-level settlement with or without tax. For information on how PCM_OP_AR_BILL_SETTLEMENT performs settlement taxation, see "Including Taxes in the Dispute or Settlement".
Important:
PCM_OP_AR_BILL_SETTLEMENT does not check to determine whether the item you are settling is billed yet. However, using this opcode to settle pending items is not recommended. If you try to settle pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any disputes settled against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_BILL_SETTLEMENT does not create settlements in these cases:
The specified bill is not an A/R bill; for example, a bill from a nonpaying subordinate bill unit.
The amount of the settlement exceeds the amount of the associated dispute.
Bill-level settlements can apply to the entire bill or to specific bill items. When PCM_OP_AR_BILL_SETTLEMENT receives an input flist, it creates a single, umbrella settlement item for all bill items covered by the settlement, as follows:
If the input flist specifies individual bill items, the settlement item is associated with each of these bill items. The settlement amount for each bill item must be specified in the input flist.
If the flist does not specify any bill items, all disputed items in the bill are eligible for settlement. PCM_OP_AR_BILL_SETTLEMENT opens settlements for as many disputed items as it can before it consumes the settlement amount. After it uses up the settlement amount, it continues to open settlements for the remaining disputed items, but with a settlement amount of 0.
For each bill item it must settle, PCM_OP_AR_BILL_SETTLEMENT passes the POID of the settlement item and the appropriate settlement amount to PCM_OP_AR_ITEM_SETTLEMENT, which creates a settlement event for each bill item it receives. An /event/billing/settlement/item object is created for each settled item in the bill, recording the balance impact. For details on how PCM_OP_AR_ITEM_SETTLEMENT works, see "Settling Disputed Items".
If the settlement fails, PCM_OP_AR_BILL_SETTLEMENT returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.
BRM creates a G/L ID for every bill-level settlement. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the PCM_OP_AR_BILL_SETTLEMENT input flist when creating bill-level settlements:
PIN_FLD_POID for the bill under dispute or settlement. You obtain this from the /bill object that the CSR identifies through the BRM client application. The settled amount is applied to the default balance group of the bill unit associated with the bill.
PIN_FLD_POID for the item to be settled. This field is only required to settle a particular set of bill items within the bill.
PIN_FLD_AMOUNT for the settlement amount. The value supplied for this field should be negative when crediting and positive when debiting.
You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the settlement is against an array of bill items, for the individual bill items. If you supply a value for PIN_FLD_AMOUNT, it must be less than the dispute amount.
PCM_OP_AR_BILL_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_BILL_SETTLEMENT.
If the PIN_AR_WITHOUT_TAX flag is set, the settlement is nontaxable. This is the default.
If the PIN_AR_WITH_TAX flag is set, the settlement is taxable. Tax is reversed on an item-by-item basis.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The settlement is nontaxable if the pin.conf entry is absent.For information on flags that indirectly affect PCM_OP_AR_BILL_SETTLEMENT, see "Flags for Item Settlements".
To open a dispute at the item level, use PCM_OP_AR_ITEM_DISPUTE. This opcode debits or credits a currency resources for a particular bill item. This opcode is also called by PCM_OP_AR_BILL_DISPUTE to dispute items in a bill.
Important:
PCM_OP_AR_ITEM_DISPUTE does not check to determine whether the item you are disputing is billed yet. However, using this opcode to dispute pending items is not recommended. If you try to dispute pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any disputes against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_ITEM_DISPUTE does the following:
Reads the original /item object and prepares the changes to reflect the balance impact of the dispute.
For credit disputes, these changes reduce the Due amount (PIN_FLD_DUE) for the item. For debit disputes, the opposite occurs.
Calls PCM_OP_BILL_POL_VALID_DISPUTE to validate the changes.
You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT. For information on customizing the opcode, see "Customizing Item-Level Disputes".
Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.
If so, PCM_OP_AR_ITEM_DISPUTE checks the contents of the field to determine:
Whether the field contains a POID, indicating that the opcode is being called by PCM_OP_AR_BILL_DISPUTE to complete a bill-level dispute.
This POID identifies the /item/dispute object that PCM_OP_AR_BILL_DISPUTE created to store information on the bill-level dispute. This is the /item/dispute object that PCM_OP_AR_ITEM_DISPUTE will associate with each of the dispute events it creates for the bill-level adjustment.
Whether the field is NULL, indicating that PCM_OP_AR_ITEM_DISPUTE is being called directly from the client application to perform an item-level dispute. In this case, PCM_OP_AR_ITEM_DISPUTE will create its own /item/dispute object. This object is exclusive to the individual item being disputed.
If the dispute has tax implications and the opcode is not being called as part of a bill-level dispute, checks the original /item object to determine the taxable portion of the item:
If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.
If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.
If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the dispute tax reversal only for the usage amount and not the tax amount.
For each item that it can dispute, the opcode checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the dispute tax reversal.
As a result of eliminating any non-taxable components of the original item, the dispute tax is calculated proportionally to the actual taxable amount of the item.
Note:
If the item dispute is being performed as part of a bill-level dispute, the PCM_OP_AR_BILL_DISPUTE opcode performs this step before calling PCM_OP_AR_ITEM_DISPUTE.Creates an /event/billing/dispute/item object.
The item dispute event balance impact is applied to the default balance group of the bill unit associated with the item. If the item dispute is part of a bill-level dispute, the event object for each disputed item is associated with a single, umbrella /item/dispute object.
Examines the flags in the input flist to determine whether the dispute has any tax implications.
For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".
Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.
Writes the modified version of the original /item object.
Provides feedback on whether the dispute was successfully created.
If the dispute creation failed, it indicates the reason for the failure.
BRM creates a G/L ID for item-level disputes. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the PCM_OP_AR_ITEM_DISPUTE input flist when creating item-level disputes:
PIN_FLD_POID for the item under dispute. The disputed amount is applied to the default balance group of the bill unit associated with the item.
PIN_FLD_AMOUNT for the dispute amount. The value for this field should be negative when crediting and positive when debiting.
PIN_FLD_CURRENCY for the resource to be disputed.
PCM_OP_AR_ITEM_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_ITEM_DISPUTE.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_DISPUTE returns not only the POID, but all the fields in the /event/billing/dispute/item object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_DISPUTE does not change any fields in the database and does not create an /event/billing/dispute/item object. However, it does provide a dispute calculation to the caller by returning the fields that would have been used to create the event object and dispute item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_DISPUTE behaves in a standard manner, creating an /event/billing/dispute/item object to record details of the operation.If the PIN_AR_WITHOUT_TAX flag is set, the item dispute is nontaxable.
If the PIN_AR_WITH_TAX flag is set, the item dispute is taxable. Tax is reversed on an item-by-item basis.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The dispute is nontaxable if the pin.conf entry is absent.When you initiate a bill-level or item-level dispute, PCM_OP_AR_ITEM_DISPUTE calls the PCM_OP_BILL_POL_VALID_DISPUTE policy opcode to validate all proposed changes to the fields in the original /item object. This opcode checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.
You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT by modifying the policy source file. Changing a result from PIN_BOOLEAN_FALSE to PIN_BOOLEAN_TRUE enables the specified field value to pass. Changing a result from PIN_BOOLEAN_TRUE to PIN_BOOLEAN_FALSE causes the specified field value to fail.
To settle a dispute at the item level, use PCM_OP_AR_ITEM_SETTLEMENT. This opcode debits or credits the currency balance of a particular item to settle a dispute against that item. This opcode is also called by PCM_OP_AR_BILL_SETTLEMENT to settle the dispute items associated with a bill.
Important:
PCM_OP_AR_ITEM_SETTLEMENT does not check to determine whether the item you are settling is billed yet. However, using this opcode to settle pending items is not recommended. If you try to settle pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.Note:
You cannot move a balance group to a new bill unit if there are any disputes settled against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.PCM_OP_AR_ITEM_SETTLEMENT does the following:
Reads the original /item object and prepares the changes to reflect the balance impact based on the settlement amount.
Settlement amounts have components:
Granted amount: The portion of the disputed amount granted by the settlement. This is the amount in the PIN_FLD_DISPUTED field of the PCM_OP_AR_ITEM_SETTLEMENT input flist.
Denied amount: The portion of the disputed amount that was denied by the settlement. This is the original dispute amount minus the granted amount. Settlements always work with the denied amount.
For credit settlements, PCM_OP_AR_ITEM_SETTLEMENT makes the following changes to the balance impact:
Increases the Due amount (PIN_FLD_DUE) for the item by adding the amount denied during the settlement, if any.
For item-level disputes, it impacts the Adjusted amount (PIN_FLD_ADJUSTED) of the bill item by adding the settled amount and zeroing out the disputed amount (PIN_FLD_DISPUTED). Any dispute amount due to event-level disputes is not touched.
For debit settlements, the opposite occurs.
Calls PCM_OP_BILL_POL_ITEM_VALID_SETTLEMENT to validate the changes.
You can customize the validation criteria for PCM_OP_BILL_POL_ITEM_VALID_SETTLEMENT.
For information on customizing the opcode, see "Customizing Item-Level Settlements".
Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.
If so, PCM_OP_AR_ITEM_SETTLEMENT checks the contents of the field to determine:
Whether the field contains a POID, indicating that PCM_OP_AR_ITEM_SETTLEMENT is being called by PCM_OP_AR_BILL_SETTLEMENT to complete a bill-level settlement.
This POID identifies the /item/settlement object that PCM_OP_AR_BILL_SETTLEMENT created to store information on the bill-level settlement. This is the /item/settlement object that PCM_OP_AR_ITEM_SETTLEMENT associates with each of the settlement events it creates for the bill-level settlement.
Whether the field is NULL, indicating that PCM_OP_AR_ITEM_SETTLEMENT is being called directly from the client application to perform an item-level settlement. In this case, PCM_OP_AR_ITEM_SETTLEMENT creates its own /item/settlement object. This object is exclusive to the individual item being settled.
Creates an /event/billing/settlement/item object.
If the item settlement is part of a bill-level settlement, the event object for each settled item is associated with a single, umbrella /item/settlement object.
Examines the flags in the input flist to determine whether the dispute has any tax implications.
For information on how PCM_OP_AR_ITEM_SETTLEMENT performs settlement taxation, see "Including Taxes in the Dispute or Settlement".
Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.
Before transferring the funds, PCM_OP_AR_ITEM_SETTLEMENT filters disputed events that were created by event-level disputes and subtracts the amount associated with these events from the PIN_FLD_DISPUTED of the disputed item. What remains is the amount associated solely with the item-level dispute, with no contribution from event-level disputes.
If the Due amount after settlement is 0 and there are no other open disputes, PCM_OP_AR_ITEM_SETTLEMENT sets the PIN_ITEM_STATUS field to CLOSED.
Writes the modified version of the original /item object.
Provides feedback on whether the settlement was successfully created.
If the settlement creation failed, the opcode indicates the reason for the failure.
BRM creates a G/L ID for item-level settlements. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the PCM_OP_AR_ITEM_SETTLEMENT input flist when creating item-level settlements:
PIN_FLD_POID for the item to be settled. The settled amount is applied to the default balance group of the bill unit associated with the item.
PIN_FLD_AMOUNT for the settlement amount. The value for this field should be negative when crediting and positive when debiting.
PIN_FLD_CURRENCY for the resource to be settled.
PCM_OP_AR_ITEM_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_ITEM_SETTLEMENT.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_SETTLEMENT returns not only the POID, but all the fields in the /event/billing/settlement/item object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_SETTLEMENT does not change any fields in the database and does not create an /event/billing/settlement/item object. However, it does provide a settlement calculation to the caller by returning the fields that would have been used to create the event object and settlement item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_SETTLEMENT behaves in a standard manner, creating an /event/billing/settlement/item object to record details of the operation.If the PIN_AR_WITHOUT_TAX flag is set, the item settlement is nontaxable.
If the PIN_AR_WITH_TAX flag is set, the item settlement is taxable. Tax is reversed on an item-by-item basis.
Note:
If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The settlement is nontaxable if the pin.conf entry is absent.When you initiate a bill-level or item-level settlement, PCM_OP_AR_ITEM_SETTLEMENT calls the PCM_OP_BILL_POL_VALID_DISPUTE policy opcode to validate all proposed changes to the fields in the original /item object. This opcode checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.
You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT by modifying the policy source file. Changing a result from PIN_BOOLEAN_FALSE to PIN_BOOLEAN_TRUE enables the specified field value to pass. Changing a result from PIN_BOOLEAN_TRUE to PIN_BOOLEAN_FALSE causes the specified field value to fail.
To open a dispute at the event level, use PCM_OP_AR_EVENT_DISPUTE.
This opcode receives a batch of events on the input flist, and returns the disputed /event/billing/dispute/event data on the output flist. There can be multiple events in a given batch, and the events to be disputed do not need to belong to the account specified in the PIN_FLD_POID for PCM_OP_AR_EVENT_DISPUTE. The input flist can optionally include a reason code domain and descriptive string that indicates why the dispute is being made.
Caution:
PCM_OP_AR_EVENT_DISPUTE does not verify whether there are other disputes against the events it processes. Multiple disputes for the same event can cause conflicts in BRM, so make sure your client application prevents the CSR from logging more than one dispute for an event.When it receives a batch of events, PCM_OP_AR_EVENT_DISPUTE performs these tasks:
It reads the batch, identifying all events to be disputed
It examines the flags in the input flist to determine whether the dispute has any tax implications.
For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".
It creates a single dispute item, /item/dispute, for all the disputed events in the batch.
For each event to be disputed, it creates a new /event/billing/dispute/event object containing the dispute amount.
The PIN_FLD_ITEM_OBJ field of /event/billing/dispute/event points to the dispute item created in step 3.
After the /item/dispute and /event/billing/dispute/event objects are created, it calls PCM_OP_BILL_ITEM_TRANSFER to transfer the dispute amount from the dispute item to the original item that owns the disputed event.
Note:
If the opcode transfer targets a closed item, that item is reopened automatically.It creates a notification event (/event/billing/dispute/notify) and passes it to PCM_OP_ACT_USAGE for processing.
If event notification is enabled in your system, this triggers the reservation of the disputed resources until the dispute is settled (see "Configuring Event Notification for Disputes and Settlements"). For information on reserving resources and customizing resource reservation for disputes, see "Customizing Resource Reservation for Disputes".
When it finishes, it provides feedback on whether the dispute was successfully created or, if dispute creation failed, the reason for the failure.
BRM creates a G/L ID for event-level disputes. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the input flist when creating event-level disputes:
PIN_FLD_POID for each of the events to be disputed. These fields form a PIN_FLD_EVENTS array. The disputed amount is applied to the default balance group of the bill unit associated with the /item object that the event belongs to.
PIN_FLD_AMOUNT for the dispute amount. The value supplied for this field should be positive for adjustments that credit the event and negative for adjustments that debit the event.
You can specify the dispute amount through either PIN_FLD_AMOUNT or PIN_FLD_PERCENT. If you omit both of these fields, BRM disputes the entire amount for each event.
PIN_FLD_RESOURCE_ID for the disputed resource.
PCM_OP_AR_EVENT_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_EVENT_DISPUTE.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_DISPUTE returns not only the POID, but all the fields in the /event/billing/dispute/event object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_DISPUTE does not change any fields in the database and does not create an /event/billing/dispute/event object. However, it does provide a dispute calculation to the caller by returning the fields that would have been used to create the event object and dispute item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_DISPUTE behaves in a standard manner, creating an /event/billing/dispute/event object to record details of the operation.If the PIN_ADJ_NO_TAX flag is set, the event dispute is nontaxable. If this flag is not set, the dispute is taxable.
If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is disputed; not the event itself.
Important:
Do not set this flag for disputes against unbilled events that use deferred taxation.If the PIN_EVENT_ADJUST_BATCH is set, the dispute amount will be distributed among the events in the batch on a first-come-first-serve basis until the dispute amount is consumed.
If the PIN_EVENT_ADJUST_EVENT is set, the dispute amount will be applied individually to each of the events in the batch.
Resource reservation for disputes is performed by the PCM_OP_RESERVE_POL_POST_DISPUTE policy opcode, which reserves resources equivalent to the dispute amount for as long as the dispute is active. PCM_OP_RESERVE_POL_POST_DISPUTE enables you to perform custom processing of the reservation (/reservation object) that it creates for the dispute.
When PCM_OP_RESERVE_POL_POST_DISPUTE receives a dispute notification event (/event/billing/dispute/notify) from PCM_OP_ACT_USAGE, it reads the dispute item POID from the input flist and obtains all associated dispute events. From the balance impact arrays for each dispute event, it reads:
PIN_FLD_ACCOUNT_OBJ: to obtain the account or accounts affected by the dispute
PIN_FLD_AMOUNT: to obtain the balance impact amounts
PIN_FLD_RESOURCE_ID: to identify the resource type (currency or non-currency)
PCM_OP_RESERVE_POL_POST_DISPUTE then creates a /reservation object for each distinct entry in the balance impact arrays and stores the dispute item in the PIN_FLD_SESSION_OBJ field of the /reservation object. The output flist provides a pass/fail status to PCM_OP_AR_EVENT_DISPUTE and returns the POID for each /reservation object it creates.
You can customize PCM_OP_RESERVE_POL_POST_DISPUTE to notify third parties of the dispute. For example, you can customize PCM_OP_RESERVE_POL_POST_DISPUTE to notify a collection agency of any disputes so that they can postpone collection efforts for the disputed item until settlement. Or, if you have an automatic customer confirmation service in place, you can customize PCM_OP_RESERVE_POL_POST_DISPUTE to notify that service, which can, in turn, inform the customer that the dispute has been created.
You can also customize PCM_OP_RESERVE_POL_POST_DISPUTE by determining whether PCM_OP_ACT_USAGE will call it at all. In most cases, this opcode should be part of the dispute process. However, if you determine that you do not need resource reservation even to ensure accurate credit treatment for prepaid customers, you can omit it.
To configure BRM to run PCM_OP_RESERVE_POL_POST_DISPUTE, you must enable event notification. See "Configuring Event Notification for Disputes and Settlements".
To settle a dispute at the event level, use PCM_OP_AR_EVENT_SETTLEMENT. This opcode debits or credits the resources of an event to settle a dispute against that event.
Note:
You cannot settle an event more than once. If PCM_OP_AR_EVENT_SETTLEMENT settles an event that has more than one open dispute, it settles all the disputes for that event.PCM_OP_AR_EVENT_SETTLEMENT receives dispute item POID in the input flists and retrieves the associated dispute events. It returns the settled /event/billing/settlement/event data on the output flist. The input flist can optionally include a reason code domain and descriptive string that indicates why the settlement is being made.
When it receives a batch of events, PCM_OP_AR_EVENT_SETTLEMENT performs these tasks:
It verifies that, for backdated settlements, the settlement date falls after the dispute date.
It examines the flags in the input flist to determine whether the settlement has any tax implications.
For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".
It searches for all dispute events whose PIN_FLD_ITEM_OBJ field points to the dispute item and creates a single settlement item, /item/settlement, for all these events.
For each dispute event to be settled, it creates a new /event/billing/settlement/event object containing the denied amount.
The PIN_FLD_SESSION_OBJ field of /event/billing/settlement/event points to the corresponding dispute event.
After the /item/settlement and /event/billing/settlement/event objects are created, it calls PCM_OP_BILL_ITEM_TRANSFER to transfer the denied amount from the settlement item to the original item against which the settlement was filed and recalculate the Due of the original item accordingly.
Note:
If PCM_OP_AR_EVENT_SETTLEMENT transfer targets a closed item, that item will be reopened automatically.To prevent misallocation of resources during settlement, PCM_OP_AR_EVENT_SETTLEMENT calculates the combined dispute amount for the all of the dispute events with respect to the original disputed item. This amount is associated solely with the event-level dispute being settled. It has no contribution from any item-level disputes or any event-level disputes other than the one being settled. It is this amount that PCM_OP_BILL_ITEM_TRANSFER works with when transferring the item.
It creates a notification event (/event/billing/settlement/notify) and passes to PCM_OP_ACT_USAGE for processing.
If event notification is enabled in your system, this triggers the release of the dispute /reservation object, indicating that the event has been settled (see "Configuring Event Notification for Disputes and Settlements"). For information on reserving resources and customizing resource reservation for disputes, see "Customizing Resource Reservation for Settlements".
When it finishes, PCM_OP_AR_EVENT_SETTLEMENT provides feedback on whether the settlement was successfully created or, if settlement creation failed, the reason for the failure.
BRM creates a G/L ID for event-level settlements. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".
Set these fields in the PCM_OP_AR_EVENT_SETTLEMENT input flist when creating event-level settlements:
PIN_FLD_ITEM_OBJ for the dispute item.
PIN_FLD_AMOUNT for the settlement amount. The value supplied for this field should be positive for settlements that credit the event and negative for settlements that debit the event.
You can specify the settlement amount through the PIN_FLD_AMOUNT field or omit the field altogether. If you omit this field, BRM settles the entire amount for each event.
PIN_FLD_RESOURCE_ID for the resource to be settled.
PCM_OP_AR_EVENT_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so forth.
For information on tax treatment, see "Including Taxes in the Dispute or Settlement".
For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".
For information on any remaining fields, see the input flist specification for PCM_OP_AR_EVENT_SETTLEMENT.
If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_SETTLEMENT returns not only the POID, but all the fields in the /event/billing/settlement/event object as well.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_SETTLEMENT does not change any fields in the database and does not create an /event/billing/settlement/event object. However, it does provide a settlement calculation to the caller by returning the fields that would have been used to create the event object and settlement item.
Note:
If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_SETTLEMENT behaves in a standard manner, creating an /event/billing/settlement/event object to record details of the operation.If the PIN_ADJ_NO_TAX flag is set, the event settlement is nontaxable. If this flag is not set, the settlement is taxable.
If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is settled; not the event itself.
Important:
Do not set this flag for settlements against unbilled events that use deferred taxation.If the PIN_EVENT_ADJUST_BATCH is set, the settlement amount will be distributed among the events in the batch on a first-come-first-serve basis until the settlement amount is consumed.
If the PIN_EVENT_ADJUST_EVENT is set, the settlement amount will be applied individually to each of the events in the batch.
Resource reservation processing for settlements is performed by the PCM_OP_RESERVE_POL_POST_SETTLEMENT policy opcode, which releases resources reserved when an event-level dispute is created. This opcode enables you to perform custom processing of the reservation (/reservation object) that it releases during the settlement.
When it receives a settlement notification event (/event/billing/settlement/notify) from PCM_OP_ACT_USAGE, PCM_OP_RESERVE_POL_POST_SETTLEMENT reads the dispute item POID from the input flist and searches for all reservation objects that have the dispute item in the PIN_FLD_SESSION_OBJ field. For each of these /reservation objects, PCM_OP_RESERVE_POL_POST_SETTLEMENT updates the PIN_FLD_RESERVATION_STATUS field to indicate that the reservation is released and to create a timestamp for the reservation release. The PCM_OP_RESERVE_POL_POST_SETTLEMENT output flist provides a pass/fail status to PCM_OP_AR_EVENT_SETTLEMENT and can optionally generate a descriptive message concerning its success or failure.
You can customize PCM_OP_RESERVE_POL_POST_SETTLEMENT to notify third parties of the settlement; for example a collection agency or an automatic confirmation service.
You can also customize PCM_OP_RESERVE_POL_POST_SETTLEMENT by determining whether PCM_OP_ACT_USAGE will call it at all. If you included dispute reservation as part of the dispute process, PCM_OP_RESERVE_POL_POST_SETTLEMENT should also participate in the settlement process. If you do not, /reservation objects created by dispute reservation will not be released on settlement.
To configure BRM to run PCM_OP_RESERVE_POL_POST_SETTLEMENT, you must enable event notification. See "Configuring Event Notification for Disputes and Settlements".
You specify an optional tax treatment for disputes and settlements through flags in the input flist. For information, see:
The dispute opcodes calculate taxes when the dispute is created. Before calculating taxes, they validate that the item due is not zero. If it is zero, the dispute is not allowed.
If the input flist flags the dispute or settlement as taxable, the dispute opcode either includes or excludes the tax:
If it is tax now, the opcode uses information from the disputed event to calculate the tax and apply it immediately.
If it is tax deferred, taxes are contained in the tax item. In such cases, the opcode does the following to handle the taxes:
Calls PCM_OP_BILL_TAX_EVENT to calculate the tax amount.
Compares the calculated tax with due amount of the tax item to determine the amount to reverse.
Creates the /event/billing/dispute/tax_event event to contain the tax amount.
Transfers the calculated tax amount to the original tax item.
Note:
If the dispute is created in the same billing cycle as the disputed item, the original item will not have been taxed yet. In this case, there is no need to create the /event/billing/dispute/tax_event or /event/billing/settlement/tax_event event because the dispute or settlement precedes initial tax calculation for the original item.The settlement opcodes calculates taxes when the settlement is created. Before calculating taxes, they validate that the settlement amount is less than or equal to the disputed amount. If the settlement amount is greater, the settlement is not allowed.
If the original bill item uses taxation, the tax is considered tax inclusive or tax exclusive, depending on the amount of the dispute:
If the disputed amount is partially granted, the settlement amount is considered to be tax-exclusive. The amount due on the bill item is increased by the net denied amount and the amount due on the cycle tax item is increased by the denied tax amount.
If the disputed amount is completely granted (there is no denied amount), the settlement amount is considered to be tax-inclusive. The amount due on the bill item does change for taxes.
Note:
If the disputed amount is completely denied, the amount due on the bill item is increased by the net amount and the amount due on the tax item is increased by the tax amount.If the input flist flags the settlement as taxable, the settlement opcode determines whether the tax method is tax now or tax deferred.
If the tax method is tax now, the settlement opcodes use information from the event associated with the original bill item to calculate taxes and apply the amount immediately with the settlement amount.
If the tax method is tax deferred, taxes are contained in the tax item associated with the dispute. In such cases, the opcode does the following to handle the taxes:
Calls PCM_OP_BILL_TAX_EVENT to calculate the net and tax amount from the total settlement amount. If a denied amount exists, it then calculates the net and tax amount from the total denied amount.
Creates the /event/billing/settlement/tax_event event to contain the denied tax amount.
Transfers the denied net amount to the original item and the denied tax amount to the tax item.
Reason codes explain why a dispute is being opened or settled. In typical implementations, the BRM client application provides a selectable set of reasons appropriate to the event type. You choose a reason that matches the situation or, in some cases, compose a new reason. The client application populates the input flist for the opcode with this information, and BRM records the reason in the dispute or settlement event object (for example, /event/billing/dispute/item or /event/billing/settlement/event). The flist fields that provide reason code information are PIN_FLD_REASON_ID and PIN_FLD_REASON_DOMAIN_ID. These fields are optional.
For general information about reason codes, see "String Manipulation Functions" in BRM Developer's Reference. For information about setting up reason codes for adjustments, see "Working with Reason Codes for Adjustment, Disputes, and Settlements".
The G/L ID for an dispute or settlement event is assigned like other pre-rated events in the BRM system. The PCM_OP_ACT_POL_SPEC_GLID policy opcode assigns the G/L ID for the adjustment. For information on preconfiguring the adjustment event to modify the /config/map_glid configuration object, see "Assigning G/L IDs to Nonrated Events" in BRM Collecting General Ledger Data.