21 Subscription Opcode Workflows
Learn about the Oracle Communications Billing and Revenue Management (BRM) subscription opcode workflows.
Topics in this document:
- Opcodes Described in This Chapter
- Pricing Component Object Names
- Managing Charge Offers
- Managing Discount Offers
- Managing Bundles
- Managing Packages
- Managing Contracts
- Managing Purchase, Cycle, and Usage Charges in Purchased Offers
- Applying Recurring Charges
- Applying Folds
- Getting Data about Bundles, Charge Offers, Discount Offers, and Services
- Applying Promotions for Special Dates, Events, or Actions
- Managing Promotions with Siebel CRM
- Managing Provisioning
- Validating Product Specification Attributes for Pricing Components
Opcodes Described in This Chapter
Table 21-1 lists the opcodes described in this chapter.
Caution:
- Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
- Do not use SQL commands to change data in the database. Always use the API.
Table 21-1 Opcodes Described in This Chapter
| Opcode | Topic |
|---|---|
|
PCM_OP_ACT_SCHEDULE_CREATE |
How BRM Transitions Accounts from Source Packages to Target Packages |
|
PCM_OP_ACT_USAGE |
|
|
PCM_OP_BAL_APPLY_MULTI_BAL_IMPACTS |
|
|
PCM_OP_BAL_GET_BALANCES |
|
|
PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE |
|
|
PCM_OP_BILL_CYCLE_ARREARS |
|
|
PCM_OP_BILL_CYCLE_FORWARD |
|
|
PCM_OP_BILL_MAKE_BILL |
|
|
PCM_OP_CONTRACT_CANCEL_CONTRACT |
|
|
PCM_OP_CONTRACT_CREATE_CONTRACT |
|
|
PCM_OP_CONTRACT_MODIFY_CONTRACT |
|
|
PCM_OP_CONTRACT_RENEW_CONTRACT |
|
|
PCM_OP_CUST_COMMIT_CUSTOMER |
|
|
PCM_OP_CUST_CREATE_CUSTOMER |
|
|
PCM_OP_CUST_CREATE_PROFILE |
|
|
PCM_OP_CUST_DELETE_PROFILE |
|
|
PCM_OP_CUST_MODIFY_CUSTOMER |
How BRM Transitions Accounts from Source Packages to Target Packages |
|
PCM_OP_CUST_MODIFY_PROFILE |
|
|
PCM_OP_CUST_POL_GET_DEALS |
|
|
PCM_OP_CUST_POL_GET_PLANS |
|
|
PCM_OP_CUST_POL_GET_PRODUCTS |
|
|
PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS |
|
|
PCM_OP_CUST_POL_READ_PLAN |
|
|
PCM_OP_CUST_POL_TRANSITION_DEALS |
Customizing Bundle Transitions Customizing Package Transitions without Configuring /transition Objects |
|
PCM_OP_CUST_SET_STATUS |
About Closing a Required Service |
|
PCM_OP_CUST_UPDATE_SERVICES |
About Closing a Required Service How BRM Transitions Accounts from Source Packages to Target Packages |
|
PCM_OP_PROV_POL_UPDATE_SVC_ORDER |
|
|
PCM_OP_PROV_PUBLISH_SVC_ORDER |
|
|
PCM_OP_PROV_UPDATE_SVC_ORDER |
|
|
PCM_OP_SUBSCRIPTION_CANCEL_DEAL |
|
|
PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT |
|
|
PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT |
How Charge Offers Are Canceled Customizing Charge Offer Cancellation Customizing How Folds Are Applied |
|
PCM_OP_SUBSCRIPTION_CHANGE_DEAL |
|
|
PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS |
|
|
PCM_OP_SUBSCRIPTION_CRUD_OFFER_OVERRIDE |
Overriding Charges and Discounts for a Period of Time |
|
PCM_OP_SUBSCRIPTION_CYCLE_ARREARS |
Calculating the Cycle Arrears Fee Customizing Which Balances to Fold When Charge Offers Are Canceled |
|
PCM_OP_SUBSCRIPTION_CYCLE_FOLD |
Customizing the Order to Apply Folds Customizing Which Balances to Fold When Charge Offers Are Canceled |
|
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD |
Calculating the Cycle Forward Fee How Cycle Fees Are Calculated for Backdated Cancellation or Inactivation Customizing Which Balances to Fold When Charge Offers Are Canceled |
|
PCM_OP_SUBSCRIPTION_GET_HISTORY |
Finding Events Associated with Bundles, Charge Offers, Discount Offers, and Services |
|
PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS |
Reading Data for All Valid Purchased Charge Offers and Discount Offers |
|
PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT |
|
|
PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING |
|
|
PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS |
|
|
PCM_OP_SUBSCRIPTION_POL_PRE_FOLD |
|
|
PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL |
|
|
PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN |
Customizing Bundle Transitions How BRM Transitions Accounts from Source Packages to Target Packages Customizing Package Transitions without Configuring /transition Objects |
|
PCM_OP_SUBSCRIPTION_POL_PREP_FOLD |
Customizing How to Apply Folds Customizing Which Balances to Fold When Charge Offers Are Canceled |
|
PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING |
|
|
PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING |
|
|
PCM_OP_SUBSCRIPTION_POL_SNOWBALL_DISCOUNT |
|
|
PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL |
|
|
PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT |
|
|
PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD |
|
| PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING |
How Discount Offers Are Purchased Validating Product Specification Attributes for Pricing Components |
|
PCM_OP_SUBSCRIPTION_PROVISION_ERA |
|
|
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL |
How Discount Offers Are Purchased Managing Purchase, Cycle, and Usage Charges in Purchased Offers |
|
PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT |
How Discount Offers Are Purchased Managing Purchase, Cycle, and Usage Charges in Purchased Offers |
|
PCM_OP_SUBSCRIPTION_PURCHASE_FEES |
|
|
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT |
Backdating Charge Offer, Discount Offer, Bundle, or Package Purchases About Delayed Cycle Start and End Times Applying Purchase and Cycle Fees to the Balance Managing Purchase, Cycle, and Usage Charges in Purchased Offers |
|
PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS |
Getting a List of Bundles, Charge Offers, Discount Offers, and Services |
|
PCM_OP_SUBSCRIPTION_SET_BUNDLE |
|
|
PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS |
How BRM Changes Discount Offer Status How Discount Offer Purchase, Cycle, and Usage Validity Is Modified |
|
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO |
How Discount Offer Purchase, Cycle, and Usage Validity Is Modified |
|
PCM_OP_SUBSCRIPTION_SET_PRODINFO |
How Charge Offers Are Modified How BRM Changes Charge Offer Status Changing the Purchase, Usage, and Cycle Start and End Times Calculating the Cycle Forward Fee |
|
PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS |
|
|
PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION |
|
|
PCM_OP_SUBSCRIPTION_TRANSITION_DEAL |
Applying Purchase and Cycle Fees to the Balance |
|
PCM_OP_SUBSCRIPTION_TRANSITION_PLAN |
How BRM Transitions Accounts from Source Packages to Target Packages |
|
PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY |
|
|
PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY |
Pricing Component Object Names
When you publish pricing components to the BRM database, the pricing components are stored as objects in the BRM database. Table 21-2 shows the pricing component object names. Developers and database managers must know these object names.
Table 21-2 Pricing Component Object Names
| Pricing Component | Object |
|---|---|
|
bundle |
/deal Bundles owned by a customer are stored as /purchased_deal objects. |
|
charge |
/rate_plan |
|
charge pricing |
/rate |
|
charge offer |
/product Charge offers owned by a customer are stored as /purchased_product objects. |
|
charge selector |
/rate_plan_selector |
|
discount offer |
/discount Discount offers owned by a customer are stored as /purchased_discount objects. |
| product specification attribute | /offer_attribute_group Attribute names and values are stored as /offer_attribute_group arrays. Pricing components contain a PIN_FLD_ATTRIBUTE_OBJ field to point to these arrays. |
|
package |
/plan |
|
package list |
/group/plan_list |
Managing Charge Offers
See the following topics:
Purchasing Charge Offers
To purchase a charge offer, use PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT.
Note:
Do not call PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT directly. This opcode is always called by PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT is called to purchase charge offers for the account or service object specified in the input flist.
Note:
- If a /service object is specified, the charge offer is purchased for that service and is a service charge offer. The /service object must belong to the account.
- If the /service object is NULL, the charge offer is purchased for the /account object and is an account bundle.
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT performs these operations:
- If billing is due, triggers billing.
- Opens a transaction.
- Checks the value of the PIN_FLD_MODE field.
- If the value is 0, continues with the purchase.
- If the value is 1, 2, or 3, processes the purchase as described in "Purchasing the Same Charge Offer Multiple Times".
- Validates any product specification attributes on the charge offer by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.
- Retrieves the charge offer's package ID, name, and type, which are passed in the input flist, and opens a bundle instance. For information about how a bundle is generated, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.
- Validates that the charge offer is available for purchase. A charge offer is
not available for purchase when any of the following apply:
- The charge offer's validity period has not yet started (the PURCHASE_START_T value is greater than the current time).
- The charge offer's validity period has already ended (the PURCHASE_END_T value is less than or equal to the current time).
- The cycle or usage start time is less than the purchase start time.
- The cycle or usage end time is greater than the purchase end time.
- There is a PIN_FLD_PERMITTED field for the charge offer but the POID type is not explicitly permitted.
- The purchase quantity is 0 or is not passed.
- The purchase quantity is less than the minimum purchase quantity set in your product offerings.
- The purchase quantity is greater than the maximum purchase quantity set in your product offerings.
- An attempt is made to purchase a partial quantity.
- The total quantity purchased for this charge offer exceeds the maximum ownership quantity in your product offerings for this account or service. This applies only to subscription charge offers that have a maximum ownership quantity specified.
- The total quantity purchased for this charge offer is less than the minimum ownership quantity in your product offerings for this account or service. This applies only to subscription charge offers that have a minimum ownership quantity specified.
- If the charge offer purchase is backdated, validates that:
- The date to which the charge offer purchase is backdated is not prior to the G/L posting date.
- The date to which the charge offer purchase is backdated is not prior to the effective date of the account or service.
- The date to which the charge offer purchase is backdated is not prior to the date of the last status change of the account or service.
- If the purchase product provisioning tag is set for the charge offer, calls
PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING. See "Customizing Provisioning When a Charge Offer Is Purchased".
If a /config/provisioning_tag object is associated with the charge offer, PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING runs the opcodes specified in that object to run at charge offer purchase time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag.
- Determines the various start and end dates for the charge offer. See "Handling Purchase, Cycle, and Usage Start and End Times".
- Verifies the charge offer purchase with the specified account.
- Applies the charge offer to the account:
- If it is a subscription charge offer, generates a /purchased_product object with a pointer to the /account object.
- If it is an item charge offer, creates an audit record for the
/au_purchased_product object.
Note:
Item charge offers cannot be deferred. The audit object is used for rerating events.
- Sets the purchase, cycle, and usage discounts, if applicable.
- Sets the charge offer status in /purchased_product.
- Checks the PIN_FLD_FLAGS value set by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL to determine whether the charge offer purchase is due to a bundle or package transition. If so, sets the value to PIN_TRANS_WAIVE_PURCHASE_FEES.
- Applies the appropriate purchase and cycle fees to the balance.
- Updates the charge offer flags for applying purchase and cycle fees.
- Creates the audit log event object (/event/billing/product/action/purchase) after the charge offer is added to the account and all applicable fees are applied.
- Closes the transaction.
If the charge offer purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT returns a confirmation message.
During a bundle or package transition, additional validations are performed that may prevent a successful purchase:
- If the service contains at least one required bundle, the service flag is set to Required. If all bundles for the service are optional, the service flag is set to Optional. A required service cannot be canceled; therefore, the purchase portion of the transition does not occur.
- If the system flag validate_deal_dependencies is 1, BRM checks to see whether prerequisites exist or whether the bundles are mutually exclusive before PCM_OP_SUBSCRIPTION_PURCHASE_DEAL is called.
- If the permitted field in the package is service_type, the flag is set to PBS.
Applying Deferred Charge Offer Purchase Fees
To apply deferred purchase fees, use PCM_OP_SUBSCRIPTION_PURCHASE_FEES.
By default, purchase fees are applied at the time of charge offer purchase. However, you can defer the purchase fees to a later date. For example, a customer can sign up for a charge offer that is not available until a later date. The charge offer's purchase fees are deferred and applied when the charge offer becomes available.
PCM_OP_SUBSCRIPTION_PURCHASE_FEES is called by the pin_cycle_fees utility to apply deferred purchase fees. When pin_cycle_fees is run with the -purchase parameter, it searches for /account objects with an expired PURCHASE_START_TIME value. For each account that it finds, it calls PCM_OP_SUBSCRIPTION_PURCHASE_FEES to apply the purchase fees.
PCM_OP_SUBSCRIPTION_PURCHASE_FEES applies deferred purchase fees only for charge offers with an expired purchase start time.
Note:
For item charge offers, the /purchased_product object is removed after the deferred fees are applied.
After the purchase fees are applied to the account, an /event/billing/purchase_fee object is created for auditing purposes.
If the purchase fee is applied successfully, PCM_OP_SUBSCRIPTION_PURCHASE_FEES returns the POIDs of the /account object and the /event/billing/purchase_fee object.
About Delayed Cycle Start and End Times
If you configure delayed purchase, cycle, or usage start and end times when you set up your price list, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT sets the delayed start and end times in the /purchased_product object when the charge offer is purchased.
The day of month to which the start date is set depends on whether you configure to align the start and end dates with the accounting cycle by setting the fm_bill cycle_delay_align entry to 1 in the CM pin.conf file.
For example, you configure a charge offer to start relative to the purchase date, and you set the relative period in the pricing package to one accounting cycle. If the account creation day is January 5, the billing day of month is 5, and the bundle is purchased on January 20, then the start date is set as follows:
-
If start and end dates are not aligned with the accounting cycle, the start date is set to February 20.
-
If start and end dates are aligned with the accounting cycle, the start date is set to February 5 if the accounting cycle is short or March 5 if the accounting cycle is long.
Handling Purchase, Cycle, and Usage Start and End Times
When using PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT, you pass the purchase, cycle, and usage start and end times. You can specify fixed dates, start on first usage and end relative to the start date, or start relative to the purchase date and end relative to the start date.
The start and end times are passed in by PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. The start and end times are specified in the same way for PCM_OP_SUBSCRIPTION_PURCHASE_DEAL and PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT.
For information on setting purchase, cycle, and usage start and end times, see "Managing Purchase, Cycle, and Usage Charges in Purchased Offers".
If the system is configured for time-stamp rounding, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT rounds the start and end times to 00:00:00 hours.
However, when a charge offer's purchase, cycle, and usage start and end units are set to 1 (seconds), 2 (minutes), or 3 (hours), and the validity period is less than 24 hours, time stamps are not rounded, regardless of your system configuration. If the validity is greater than 24 hours, or crosses the threshold of a calendar day, the purchase, cycle, and usage end time stamps are rounded when calculating the scale to determine the cycle fee amount to charge. For example, at 23:00:00 on June 10, a customer purchases a charge offer that is valid for three hours. Because the validity crosses into the next day, the timestamps for the scale calculation are rounded to 00:00:00 on June 11 rather than 02:00:00.
Purchasing the Same Charge Offer Multiple Times
Customers can purchase the same charge offer multiple times using PCM_OP_SUBSCRIPTION_PURCHASE_DEAL, which accepts PIN_FLD_MODE as part of the input flist and passes it to PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT.
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT checks the value of PIN_FLD_MODE to determine how to process the purchase.
If the value is 0, the normal product purchase flow proceeds, purchasing the charge offer as a new, unrelated purchased product. This is the default option.
If the value is 1, 2, or 3, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT uses the account, service, and bundle in the input flist to search for an existing purchased product. If no matching product is found, the product is treated as a new subscription, and the purchase flow continues as normal.
If there is a matching product and the value of PIN_FLD_MODE is 1 or 2:
Note:
This is applicable only to one-time offers and not recurring offers.-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT determines whether the additional charge offer has been purchased within the grace period and then does one of the following:
-
If the repurchase occurs within the defined grace period, the existing charge offer is extended and the opcode proceeds to the next step.
-
If the repurchase occurs after the defined grace period, the additional charge offer is treated as a new, unrelated purchased product.
-
-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT calculates the new balance validity and purchase, usage, and cycle end dates as follows:
-
If PIN_FLD_MODE is set to 1, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT compares the existing validity period to the new one, and chooses the later of the two.
For example, an existing balance is valid until June 7th. The new charge offer is purchased on June 3rd, and is valid for 7 days. The end of the new validity period is later than the existing one, so the new end date of June 10th will be used.
-
If PIN_FLD_MODE set to 2, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT adds the new validity period to the existing one.
For example, an existing balance is valid until June 7th. The new charge offer is purchased on June 3rd, and is valid for 7 days. The 7 days are added to the end of the existing validity period, so the new end date of June 14th will be used.
-
-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT calls PCM_OP_RATE_EVENT to add the balance impacts from the new charge offer as sub-balances of the existing balance, and sets the validity of the total balance calculated according to the different PIN_FLD_MODE values.
-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT then calls PCM_OP_SUBSCRIPTION_SET_PRODINFO to update the purchase, usage, and cycle end dates of the product to the new end dates calculated according to the different PIN_FLD_MODE values.
If there is a matching product and the value of PIN_FLD_MODE is 3:
-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT calls PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT to cancel the existing product and prorate any remaining balances.
-
The normal product purchase flow continues, purchasing the charge offer as a new, unrelated purchased product.
Backdating Charge Offer, Discount Offer, Bundle, or Package Purchases
To backdate a charge offer, discount offer, bundle, or package purchase, enter the backdated time in the PIN_FLD_ END_T field of the corresponding opcode. For example, to backdate a charge offer purchase, enter the date to which you want to backdate the purchase in the PIN_FLD_ END_T field of the PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT opcode.
When you backdate a charge offer, discount offer, bundle, or package purchase, BRM does the following:
-
Sets the purchase, usage, and cycle start dates to the backdated date unless they are explicitly set to a different date.
-
Prorates the cycle fee based on the proration settings.
-
Applies the purchase fee on the backdate date.
BRM does not allow you to backdate the charge offer, discount offer, bundle, or package purchase if:
-
The backdated purchase date is prior to the G/L posting date.
-
The backdated purchase date is prior to the account or service's effective date.
-
The backdated purchase date is prior to the date of the last status change of the account or service.
For example, consider that you create an account on December 1. On December 10, you change the status of the account to Inactive. On December 15, you change the status of the account back to Active. You cannot backdate a charge offer purchase prior to December 15, which is the date of the last status change.
Note:
-
BRM does not apply a fold, rollover charge offer, or billing time discount for the past accounting cycles when you backdate the purchase of the fold, rollover charge offer, or billing time discount.
-
Backdating discount offers with discount offer proration options is supported only for discount offers that are prorated.
-
How Sub-balance Buckets Are Created for Backdated Charge Offer Purchases
When a backdated charge offer purchase spans beyond the current accounting cycle, multiple cycle events and sub-balance buckets are created. That is, if a backdated purchase of a charge offer spans multiple cycles, one cycle event is created for each cycle and the free sub-balance buckets are split into multiple cycles.
For example, consider that you create an account on January 1. On April 1, you backdate the purchase of a charge offer to January 15. The charge offer grants 3600 Anytime Minutes monthly. BRM creates the following three sub-balances for the three cycles:
-
1800 Anytime Minutes for January 15 to February 1.
-
3600 Anytime Minutes for February 1 to March 1.
-
3600 Anytime Minutes for March 1 to April 1.
Note:
If you backdate the purchase of a discount offer on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.
How Cycle Fees Are Calculated for Backdated Purchase or Activation
BRM uses the PCM_OP_SUBSCRIPTION_CYCLE_FORWARD and PCM_OP_ SUBSCRIPTION_CYCLE_ARREARS opcodes to calculate cycle forward and cycle arrears fees for the subscription operations.
When you backdate a purchase or activation, the opcodes determine the scale values that are used for prorating the amount to be charged. The charges for the events that occurred during the backdated period are prorated and applied accordingly. These charges for the backdated period appear as normal recurring fees in the bill of the current cycle.
When you backdate the purchase of a charge offer that includes cycle forward events, cycle forward fees are prorated and applied from the backdated purchase date through the current date.
Applying Purchase and Cycle Fees to the Balance
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT handles the purchase and cycle fees for the charge offer as follows:
-
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT does not apply either deferred purchase or cycle forward fees. These fees are applied when the pin_cycle_fees utility is run as part of the pin_bill_day billing script. See "Applying Deferred Charge Offer Purchase Fees".
-
If the charge offer has a purchase fee and if the purchase start time is not deferred, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies the purchase fee and creates the associated /event/billing/product/fee/purchase object.
Note:
Unlike flexible cycle forward events, BRM does not support custom events for purchase fee events. Purchase fees associated with a charge offer are stored in /event/billing/product/fee/purchase object.
-
If the charge offer has a cycle forward fee and if the cycle start time is not deferred, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies the cycle forward fee by calling the necessary opcodes. This creates the /event/billing/product/fee/cycle/cycle_forward_feetype object, where feetype is the type of cycle forward fee.
-
If the charge offer is purchased as part of a bundle transition, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT can waive the purchase fees based on the PIN_FLD_FLAGS value passed in by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL. For more information, see "How Bundles Are Transitioned".
How Charge Offers Are Modified
To modify a charge offer owned by a customer, use PCM_OP_SUBSCRIPTION_SET_PRODINFO.
PCM_OP_SUBSCRIPTION_SET_PRODINFO performs these operations:
-
If billing is due, triggers billing.
-
Opens a transaction.
-
For backdating operations, validates and sets the charge offer's purchase, cycle, or usage start and end dates to a backdated date. See "About Backdated Purchase, Usage, or Cycle End Dates".
-
Modifies the charge offer information as specified. For information on how PCM_OP_SUBSCRIPTION_SET_PRODINFO handles start and end dates, see "Changing the Purchase, Usage, and Cycle Start and End Times".
-
Creates an audit record object (/au_purchased_product) used for rerating events.
-
Applies the charge offer changes to the charge offer object (/purchased_product) owned by the account.
-
Calculates and applies appropriate cycle fees for the event to the balance and, if necessary, calls other opcodes to record the cycle events. See "Calculating the Cycle Forward Fee".
-
Creates the /event/billing/product/action/modify event objects.
-
Closes the transaction.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_SUBSCRIPTION_SET_PRODINFO returns the entire event flist for the events created as a result of the modification. Otherwise, it returns the event POID of all event objects created as a result of the modification.
An error occurs in the following cases:
-
If an attempt is made to change the cycle start date to a date earlier than any period for which cycle forward or arrears fees have already been applied.
-
If an attempt is made to change the cycle end date to a date before the current time but after the end of any period for which cycle forward or cycle arrears fees have already been applied.
How BRM Changes Charge Offer Status
To set the status of a /purchased_product object owned by an account, use PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS.
PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS is called in the following cases:
- When the status of an account or service is changed.
- When a charge offer status is changed. You might need to change only the charge offer status itself if, for example, the charge offer was purchased as inactive because of future provisioning and you activate it later, or if a customer's subscription was suspended, and is now being reactivated.
PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS performs the following tasks:
- Opens a transaction.
- Retrieves the new status from the PIN_FLD_STATUSES array in the input flist. If the charge offer status change is due to an account or service status change, PIN_STATUS_FLAG_DUE_TO_ACCOUNT is passed in the PIN_FLD_STATUS_FLAGS field of the array.
- Reads the old status of the charge offer from the database.
- If PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS is not called in CALC_ONLY mode, applies the new status to the charge offer.
- If the charge offer is inactive due to future provisioning and is now
being activated, then PCM_OP_SUBSCRIPTION_SET_PRODINFO is called to modify the
purchase start date and time to the date and time of reactivation. If the original
cycle and usage start date is earlier than the new purchase start date,
PCM_OP_SUBSCRIPTION_SET_PRODINFO also resets the cycle and usage start date and time
to the new purchase start date.
If PCM_OP_SUBSCRIPTION_SET_PRODINFO is not called, an /au_purchased_products audit object is generated, which is used for rerating events.
- If the charge offer is inactive due to a suspended subscription that is
now being reactivated and PIN_FLD_RENEWAL_MODE and PIN_FLD_CYCLE_FEE_FLAGS are both
set to 1, then PCM_OP_SUBSCRIPTION_SET_PRODINFO is called to modify the cycle
end date and time to align with the date and time of the reactivation.
If the PIN_FLD_CALENDAR_DOM field is also set, the end date and time will be whichever is later, the value of PIN_FLD_CALENDAR_DOM or the reactivation date.
- If PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS is called while activating an account, sets the purchase time to NOW and sets the usage and cycle fees by calling PCM_OP_SUBSCRIPTION_SET_PRODINFO.
- If the charge offer status change is backdated, validates that:
- The date to which the charge offer status change is backdated is not prior to the G/L posting date.
- The date to which the charge offer status change is backdated is not prior to the account or service's effective date.
- The date to which the charge offer status is backdated is not prior to the last status change of the account or service.
- Creates an audit log event object (/event/billing/product/action/modify/status).
- Closes the transaction.
If the PCM_OP_CALC_ONLY flag is set when calling PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS, it returns the entire event flist for the events created as a result of the modification. Otherwise, it returns the event POIDs of all event objects created as a result of the modification.
How Charge Offers Are Canceled
To cancel a charge offer, use PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT. This opcode cancels the charge offers associated with the /account object specified in the input flist.
- PCM_OP_SUBSCRIPTION_CANCEL_DEAL to cancel each charge offer associated with a specific bundle. Depending on how many charge offers are included in the bundle, PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT may be called more than once.
- PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT to cancel an existing charge offer when the same one is purchased multiple times and the charge offer's PIN_FLD_MODE field is set to 3.
The input flist identifies the charge offers to cancel in the PIN_FLD_OFFERING_OBJ (/purchased_product POID) field.
PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT performs the following tasks:
- Closes billing if the account balance is affected.
- Opens a transaction.
- Verifies that the charge offer is valid for cancellation.
- Checks if the corresponding bundle is a required bundle. If so, does not perform the cancellation.
- Calls PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL to determine whether to cancel and delete
the charge offer, to cancel without deleting the charge offer, or to not allow the
cancellation. If the corresponding bundle has any dependencies, the charge offer
cannot be deleted.
Note:
By default, BRM retains canceled charge offers. You can change this behavior by customizing PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL. See "Customizing Charge Offer Cancellation".
- If the cancel product provisioning tag is set for the charge offer,
PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT calls
PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING to clear fields in the service
object. See "Customizing Provisioning When Canceling a Charge Offer".
If a /config/provisioning_tag object is associated with the charge offer, PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT runs the opcodes specified in that object to run at charge offer cancellation time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag.
- Validates the charge offer quantity requested for cancellation. The quantity must
be less than or equal to the quantity owned by the account.
Note:
When the quantity to cancel is less than the quantity owned, the charge offer quantity is modified; the charge offer is not canceled.
- If the charge offer cancellation is backdated, validates that:·
- The date to which the charge offer cancellation is backdated is not prior to the G/L posting date·
- The date to which the charge offer cancellation is backdated is not prior to the effective date of the account or service.·
- The date to which the charge offer cancellation is backdated is not prior to the last status change date of the account or service.
- Sets the charge offer's purchase, usage, and cycle end dates to the cancellation date.
- Reads the PIN_FLD_FLAGS value passed in from PCM_OP_SUBSCRIPTION_TRANSITION_DEAL to determine if cancellation fees should be waived.
- Applies the following fees, if applicable:
- If the charge offer is active and has any cycle forward fee associated with it, and if the charge offer is canceled in the middle of the cycle, the cycle forward fee is refunded for the unused portion of the cycle and an appropriate cycle forward event is generated.
- If the charge offer is active and has a cycle arrears fee associated with it, and if the charge offer is canceled in the middle of the cycle, the cycle arrears fee is charged for the used portion of the cycle and an /event/billing/product/fee/cycle/cycle_arrears event object is generated.
- If the charge offer has a cancellation fee, the cancellation
fee is applied and an /event/billing/product/fee/cancel event object
is generated.
Note:
If the charge offer's validity period is configured to start on first usage and has not yet been set, the charge offer has not been activated. In this case, cycle fees are not charged.
- Refunds the charge offer's cycle fees, and then reapplies them based on the new validity.
- Creates the audit log /event/billing/product/action/cancel object to record the cancellation of the charge offer.
- Returns the POIDs of all event objects created as a result of the modification.
PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT fails in the following cases:
- If the specified charge offer in the input flist does not exactly match the /purchased_product object.
- If the cancellation quantity is not passed in the input flist or is passed as 0.
- If the charge offer pricing quantity is less than the cancellation quantity specified in the input flist.
Customizing Charge Offer Cancellation
To customize charge offer cancellation, use PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL.
This opcode is called by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT.
By default, when a charge offer is canceled, the /purchased_product object is not deleted, but its status is set to Canceled. In addition, the end date is set to the charge offer cancellation date. PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL allows you to specify whether the /purchased_product object is deleted or remains with a status of Canceled.
Note:
BRM requires information stored in the /purchased_product object to rate events when you use delayed billing and when events are rerated. In these cases, /purchased_product objects should not be deleted.
You can customize the behavior of PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL by setting the PIN_FLD_ACTION field to one of these values:
-
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY, which sets the status of the /purchased_product object to Canceled and does not delete the /purchased_product object when canceled.
-
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE, which deletes the /purchased_product object when it is canceled.
-
PIN_BILL_CANCEL_PRODUCT_ACTION_DONOT_CANCEL, which stops the charge offer cancellation.
Note:
The pin_bill.h header file defines all action strings.
By default, PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL reads the provisioning tag of the /purchased_product object. If a provisioning tag is configured for the charge offer, the action is set to PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY. If there is no provisioning tag, the action is set to PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE.
Customizing How to Apply Folds
You can customize how folds are applied:
-
Use PCM_OP_SUBSCRIPTION_POL_PRE_FOLD to apply custom logic to how folds are applied.
-
Use PCM_OP_SUBSCRIPTION_POL_PREP_FOLD to customize the list of balance impacts that must be folded when a charge offer is canceled.
-
Use PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD to customize the order in which folds are applied. By default, an account's balances are folded in ascending order based on the balance element ID.
Managing Discount Offers
See the following topics:
How Discount Offers Are Purchased
To purchase a discount offer, use PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT.
Note:
Do not call PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT directly. This opcode is always called by PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT performs these operations:
- Closes the bill.
- If billing is due, triggers billing.
- Opens a transaction.
- Reads the discount offer information.
- Checks the value of the PIN_FLD_MODE field:
- If the value is 0, the purchase continues as normal.
- If the value is 1, 2, or 3,
PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT uses the account, service, and bundle
in the input flist to search for an existing purchased discount.
If no matching discount is found, the discount is treated as new, and the purchase continues as normal.
If a matching discount is found and the the value of PIN_FLD_MODE is 1 or 2, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT determines whether the additional discount offer has been purchased within the grace period. If the repurchase occurs within the defined grace period, the existing discount offer is extended and the opcode proceeds to the next step. If the repurchase occurs after the defined grace period, the additional discount offer is treated as new, and the purchase continues as normal.
Note:
This is applicable only to one-time offers and not reccuring offers.-
If PIN_FLD_MODE is set to 1, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT compares the existing validity period to the new one, and chooses the later of the two.
For example, an existing balance is valid until June 7th. The new discount offer is purchased on June 3rd, and is valid for 7 days. The end of the new validity period is later than the existing one, so the new end date of June 10th will be used.
-
If PIN_FLD_MODE is set to 2, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT adds the new validity period to the existing one.
For example, an existing balance is valid until June 7th. The new discount offer is purchased on June 3rd, and is valid for 7 days. The 7 days are added to the end of the existing validity period, so the new end date of June 14th will be used.
-
If PIN_FLD_MODE is set to 3, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT calls PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT to cancel the existing discount, then continues with the purchase as normal.
-
- Performs the following validations:
- Date validation, to make sure that the charge offer is available for purchase.
- Status validation, to check whether the discount offer is active or inactive.
- Ownership quantity validation, to make sure that the discount offer instance purchase quantity is within minimum and maximum limits for ownership.
- Purchase quantity validations, to make sure that a partial quantity purchase is not made and to check that the purchased quantity is within the minimum and maximum limits for purchase.
- product specification attribute validation, by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components"in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.
- Calculates the start and end dates of the purchase/cycle/usage events based on either CSR customization or pricing component details. If passed relative dates, calculates fixed dates. If BRM is configured for time stamp rounding, all start and end dates round to 00:00:00 hours. For more information, see "Managing Purchase, Cycle, and Usage Charges in Purchased Offers".
- If the discount offer purchase is backdated, validates that:
- The date to which the discount offer purchase is backdated is not prior to the G/L posting date.
- The date to which the discount offer purchase is backdated is not prior to the effective date of the account or service.
- The date to which the discount offer purchase is backdated is
not prior to the date of the last status change of the account or
service.
Note:
If you backdate the purchase of a discount offer on a cycle forward or cycle arrears event to a previous accounting cycle, the discount is applied only from the current accounting cycle.
- If a /config/provisioning_tag object is associated with the discount offer, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT runs the opcodes specified in that object to run at discount offer purchase time.
- If applying discount offer validity rules, sets the cycle and usage start and end
dates to one of the following:
- The first day of the next accounting cycle (no discount, valid from the middle of the cycle).
- The discount offer purchase date (prorated discount, valid from the middle of the cycle).
- The first day of the current accounting cycle (full discount, valid from the middle of the cycle).
- The purchase date of the discount offer (Prorated discount, valid only part of the cycle).
- Determines whether the discount offer instance is to be created. If the opcode is not deferring item discounts or if the opcode has no associated purchase fee, creates a /purchased_discount object with a pointer to the /account object. For some item discounts, an instance is created, but it is removed after the deferred date when the purchase fee is applied.
- If purchasing a discount offer in the middle of a cycle and the discount offer
contains discounts for any cycle forward event types, refunds the discounted portion
of the cycle forward fee as follows:
- Checks all the discounts to see whether they support any cycle forward monthly event types.
- For each cycle forward event type supported by a discount, checks the charges arrays of all /purchased_product objects for an array element of the cycle forward event type.
- Calculates the scale value for the portion of the cycle for which the discount is valid.
- Sends a request to rate normal prorated events, and calculates the resulting prorated balance impact.
- Sends the event with an inverted flag set for recording.
- Generates an audit log for the discount offer purchase to record an /event/billing/discount/action/purchase event.
- Prepares the return flist.
- Closes the transaction.
If the discount offer purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT returns a message confirming the success.
How Discount Offer Purchase, Cycle, and Usage Validity Is Modified
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO is called to change the start or end time of an account's discount offer purchase, cycle, or usage period. This opcode is called by PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS when the status of an account's discount offer is changed: for example, when you set a discount offer's status to Inactive when you purchase it and activate it at a later time.
After a discount offer is purchased and the start and end times are set, you can change the start and end times to specify only other fixed dates.
To change the discount offer's purchase, cycle, or usage validity period, specify the new start and end dates in purchase, cycle, and usage START_T and END_T fields in the PIN_FLD_DISCOUNTS array in the input flist. The cycle and usage start times must be on or later than the purchase start time, and the cycle and usage end times must be on or earlier than the purchase end time.
Note:
Do not change a discount offer's purchase, cycle, or usage start time after the discount offer has been applied to the account; otherwise, the discount is applied incorrectly.
If you change the purchase, cycle, or usage start time from first usage to a fixed date, the opcode generates an event that causes ECE to update the validity period.
The start and end times are stored in the account's /purchased_discount object.
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO performs the following tasks:
-
Resets the /purchased_discount object's purchase, cycle, and usage start and end times to the times specified in the input flist.
If discount offer validity rules are set, PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO sets the start and end times accordingly.
-
For backdating operations, validates and sets the discount offer's purchase, cycle, and usage end dates to a backdated date.
-
Applies cycle fees or refunds discounted cycle fee amounts.
Note:
When only the purchase period is changed and the cycle period starts on first usage, if the validity of the cycle period has not been initialized by a first-usage event, PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO does not apply cycle fees or refund discounted cycle fee amounts.
-
Generates an /event/billing/discount/action/modify event to record the modification.
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO returns the POID of the /event/billing/discount/action/modify event.
How BRM Changes Discount Offer Status
To set the status of a /purchased_discount object owned by an account, use PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS.
This opcode is called when the status of a discount offer is changed. This can occur in the following cases:
-
When the status of the account or service that owns the discount offer is changed. In this case, the discount offer's status is changed to the status of the account or service.
-
When the status of a discount offer is changed to inactive to active.
PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS performs the following tasks:
-
Validates and sets the new status. The new status cannot be the same as the old status.
-
Calls PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO to reset the /discount object's purchase, cycle, and usage start and end dates.
Note:
If the discount offer purchase, cycle, and usage start or end dates are already set to a later date, or the CM is configured to not reset dates, the dates are not reset.
-
If the status change of the discount offer is backdated, PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS validates that:
-
The date to which the discount offer status change is backdated is not prior to the general ledger (G/L) posting date.
-
The date to which the discount offer status change is backdated is not prior to the account or service effective date.
-
The date to which the discount offer status is backdated is not prior to the last status change of the account or service.
-
-
Generates an /event/billing/discount/action/modify/status event to record the status change.
If successful, PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS returns the POID of the /event/billing/discount/action/modify/status event.
How Discount Offers Are Canceled
To cancel a discount offer instance, use PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT.
PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT is called by:
- PCM_OP_SUBSCRIPTION_CANCEL_DEAL to cancel each discount offer associated with a specific bundle. Depending on how many discount offers are included in the bundle, PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT may be called more than once.
- PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT to cancel discount offers when they are purchased subsequent times as replacements. This happens when the PIN_FLD_MODE field for the discount offer is set to 3.
This opcode cancels the discount offers for the /account object or /service object specified in the input flist.
Note:
If you specify a NULL /service object, you cancel discount offers associated with the /account object. Otherwise, you cancel discount offers associated with the /service object.You identify discount offers to cancel in the PIN_FLD_OFFERING_OBJ (/purchased_discount POID) field in the input flist.
To cancel a discount offer instance, PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT performs the following tasks:
- Validates the discount offer quantity requested for cancellation. The quantity must
be less than or equal to the quantity owned by the account or service.
Note:
When the quantity to cancel is less than the quantity owned, the discount offer quantity in the instance is decreased; the discount offer is not canceled. - If the discount offer cancellation is backdated, validates that:
- The date to which the discount offer cancellation is backdated is not prior to the G/L posting date.
- The date to which the discount offer cancellation is backdated is not prior to the account or service's effective date.
- The date to which the discount offer cancellation is backdated
is not prior to the date of the last status change of the account or
service.
Note:
If you backdate the purchase of a discount offer on a cycle forward or cycle arrears event to a previous accounting cycle, the discount is applied only from the current accounting cycle.
- If a /config/provisioning_tag object is associated with the discount offer, PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT runs the opcodes specified in that object to run at discount offer cancellation time.
- Sets the purchase, cycle, and usage end dates for the /purchased_discount object to the cancellation date.
- If you set a discount offer validity rule, it sets the PIN_FLD_USAGE_END_T and
PIN_FLD_CYCLE_END_T fields to one of the following:
- The first day of the next accounting cycle.
- The discount offer cancellation date.
- Calls PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT and does one of the
following:
- Deletes the /purchased_discount object associated with the service or account.
- Sets the status of the /purchased_discount instance to Canceled without deleting it.
See "Customizing Discount Offer Cancellation".
Note:
If the account is the parent of a discount sharing group, it also deletes, or cancels without deleting, the /purchased_discount object from the list of discounts shared by the account. - Applies cycle fees or refunds discounted cycle fee amounts.
Note:
If the discount offer's validity period is configured to start on first usage and has not yet been set, the discount offer has not been activated. In this case, cycle fees and refunds on discounted cycle fees are not applied. - Generates an /event/billing/discount/action/cancel event to record the cancellation.
PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT returns the POID of the /event/billing/discount/action/cancel event.
Validating Discount Offer Dependencies
To validate discount offer dependencies, use PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY.
Configure mutually exclusive dependencies in the /dependency storable class.
PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY calls other opcodes to perform these operations:
-
Validate the purchase time or the billing time if specified by a flag in the input. If the opcode validates the purchase time, any purchase time discount offers are selected and validated against the /dependency object. If the opcode validates the billing time, any subscription, system, and shared discounts are selected and validated against the /dependency object.
-
Validate discount-to-discount exclusion rules.
-
Validate discount-to-package exclusion rules, if appropriate.
If one of the operations fails, that operation, and only that operation, cancels. PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY returns a validation error and partially creates an account.
PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY validates all the discount rules and returns the resulting discount values in the return flist if PIN_FLD_FLAGS does not get set to PIN_SUBS_FLG_RETURN_ON_FIRST_ERR in the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY input flist.
PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY returns an error message when the first error occurs if PIN_FLD_FLAGS is set to PIN_SUBS_FLG_RETURN_ON_FIRST_ERR in the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY input flist. If the validation fails, PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY returns a zero result, along with the POIDs of the discount offers or package and discount offer, whichever operation occurs first.
About Optional and Required Service Types
The PIN_FLD_TYPE value of a service determines whether the service is required or optional in an account. This value is dependent on the validate_deal_dependencies entry in BRM_home/sys/cm/pin.conf, the Connection Manager (CM) configuration file. (BRM_home is the directory in which the BRM server software is installed.) This entry determines whether the bundle associated with a service is required or optional.
-
If the bundle is required, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_REQUIRED.
-
If the bundle is optional, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_OPTIONAL.
When PCM_OP_CUST_CREATE_CUSTOMER creates the services in an account, it first validates whether the bundle dependency functionality is enabled in the CM pin.conf file. If so, it sets the service's PIN_FLD_TYPE value accordingly.
About Closing a Required Service
To set the status of a required service to Closed , use the PCM_OP_CUST_UPDATE_SERVICES opcode, which in turn calls PCM_OP_CUST_SET_STATUS. Set the PIN_FLD_STATUS_FLAGS value in the input flist to PIN_STATUS_FLAG_DUE_TO_REQ_SRVC. This closes all services in the package.
Note:
-
You cannot activate an optional service that has been closed if the required service is closed.
-
When you transition a bundle or package, the service associated with the old bundle is closed, and its status flag value is set to PIN_STATUS_FLAG_DUE_TO_TRANSITION. You cannot change the status of a service with this status flag value.
Customizing Snowball Discounts
Use PCM_OP_SUBSCRIPTION_POL_SNOWBALL_DISCOUNT to specify the distribution of group discounts to group members. You can modify this opcode code to specify an algorithm for distributing the total group discount grant to the individual group members. For example, you can specify distribution of the group discount based on group member contribution.
PCM_OP_SUBSCRIPTION_POL_SNOWBALL_DISCOUNT is not called by any opcode.
Customizing Discount Offer Cancellation
To customize how discount offers are canceled, use PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT.
By default, when you cancel a /purchased_discount object, you set its status to Canceled. In addition, you set the end date to the discount offer cancellation date. PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT allows you to specify whether to delete the /purchased_discount object or retain it with a status of Canceled.
Note:
When delayed usage events are expected to be loaded into BRM, BRM requires information stored in the /purchased_discount object to rate the delayed events. In this case, the /purchased_discount object should always be retained with a status of Canceled and should not be deleted.
You can customize the behavior of PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT by setting the PIN_FLD_ACTION field to one of these values:
-
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY, which sets the status of the /purchased_discount object to Canceled and does not delete it.
-
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE, which deletes the /purchased_discount object.
-
PIN_BILL_CANCEL_PRODUCT_ACTION_DONOT_CANCEL, which stops the cancellation of the discount offer.
Note:
All these strings are defined in the pin_bill.h include file.
Managing Bundles
To manage the bundles that you offer to customers, see the following:
How Bundles Are Purchased
To purchase a bundle, use PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. The charge offers and discount offers in the bundle are purchased for the account or service object specified in the input flist.
If the purchase originates in an external customer relationship management (CRM) application, the input flist contains a type-only bundle POID because no actual BRM bundle exists.
If the bundle was created in BRM, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY to validate bundle-to-bundle dependency rules. If charge offers and discount offers are created in an external CRM, this validation does not occur.
Note:
- If you specify a /service object, you purchase the bundle for that service as a service bundle. The /service object must belong to the account.
- If you specify a NULL /service object, you purchase the bundle for the /account object as an account bundle.
- If multiple bundles are purchased for the same service type, the value of the /service object's PIN_FLD_SERVICE_ID field identifies the service instance for the bundle.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode to validates any product specification attributes on the bundle. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL creates an identifier for each bundle purchase. This identifier is stored in the PIN_FLD_PACKAGE_ID field in the /purchased_product and /purchased_discount objects. The identifier distinguishes charge offers and discount offers bundled as part of a bundle or a package purchase.
Note:
PIN_FLD_PACKAGE_ID is unique for every bundle, except when bundles are purchased in the same package. In this case, all the offerings in the bundles in the package have the same PACKAGE_ID. To uniquely identify such a bundle (to cancel it, for example), you must provide the /service object along with the PACKAGE_ID. If the bundles share the same service, you must also provide the /deal object.PCM_OP_SUBSCRIPTION_PURCHASE_DEAL sets the purchase, cycle, and usage validity periods of the charge offers and discount offers in a bundle. For more information, see "Managing Purchase, Cycle, and Usage Charges in Purchased Offers".
If the bundle's charge offers or discount offers grant balances that start on first usage (when the subscriber impacts the balance for the first time), you can specify that the validity period of all balances in the bundle that start on first usage are set when one of those balances is impacted for the first time. To do this, set the PIN_FLD_GRANT_RESOURCES_AS_GROUP flag value in the PIN_FLD_FLAGS field.
If you set the bundle for on-purchase billing, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL helps to create the on-purchase bill for purchase fees for charge offers associated with the bundle.
Before you purchase a bundle, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY to validate bundle dependencies. If dependencies exist, the bundle purchase cancels.
In addition, if you set a validate_discount_dependency entry in the /config/business_params object, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL checks for a mutually exclusive relationship between any discount offers packaged in the bundle and any package the account already owns. The opcode retrieves the list of subscribed discount offers and price packages and it calls PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY to validate any mutual dependencies. If the opcode detects such a relationship, the bundle purchase cancels. If no mutually exclusive relationship exists, the bundle purchase continues.
Note:
- Dependencies are not checked if the bundle originated in an external customer relationship management (CRM) application. In that case, the input flist contains a type-only /deal object POID because no actual BRM bundle exists.
- The opcode requires no validation if PCM_OP_SUBSCRIPTION_CANCEL_DEAL was called from PCM_OP_CUST_COMMIT_CUSTOMER or PCM_OP_CUST_MODIFY_CUSTOMER.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL checks for the PIN_FLD_MODE field under the PIN_FLD_PRODUCTS array in the input flist. If the field does not exist, the opcode queries the database for the field and adds it to the flist. The PIN_FLD_MODE field determines what happens when a customer purchases the same charge offer more than once.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT to create /purchased_product objects for each charge offer in the bundle.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL uses the PIN_FLD_FEE_FLAG field to control whether PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies fees.
When the bundle and all charge offers and discount offers for the bundle have been purchased, the opcode records an /event/billing/deal/purchase event in the database for auditing purposes.
If you successfully purchase the bundle, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL returns the /account POID and the POID of the /event/billing/deal/purchase event.
You do not purchase the bundle in the following cases:
- If the /service object does not belong to the /account object.
- If the /account object or /service object is not valid.
- If status flags are not set for provisioning.
A closed account may purchase a bundle if the CM configuration file has this entry set to 1:
- cm deal_purchase_for_closed_account 1
Validating Changes to Bundles
To validate changes to bundles, use PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS. This opcode first attempts to add a service to an account. If successful, it then adds or removes bundles as needed.
Note:
To validate bundle-to-bundle transitions, use PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY. See "Validating Bundle Transitions".
PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS performs these operations:
-
Performs validation checks on all of the bundles.
-
Calls PCM_OP_SUBSCRIPTION_CANCEL_DEAL to remove any canceled bundles.
-
Removes the bundles to be canceled from an account's list of bundles.
-
Calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to add the new bundles to the account's list of bundles.
-
Applies proration rules to the charge offers. If any cancellation or purchasing fees are defined, they are charged.
-
If a bundle created by PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS requires a new service, calls PCM_OP_CUST_MODIFY_CUSTOMER to create that service.
-
Creates an /event/billing/product/action/cancel object for the canceled bundles.
How Bundles Are Modified
To modify a bundle owned by a customer, use PCM_OP_SUBSCRIPTION_CHANGE_DEAL. This opcode changes the subscription charge offers associated with a bundle for an account.
PCM_OP_SUBSCRIPTION_CHANGE_DEAL calls PCM_OP_SUBSCRIPTION_CANCEL_DEAL to cancel the subscription charge offers associated with a bundle and then calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase new subscription charge offers and associates them with the bundle.
PCM_OP_SUBSCRIPTION_CHANGE_DEAL generates two notification event objects:
-
The /event/notification/deal/change object signifies change progress. The information in the object indicates the canceled bundle.
-
The /event/notification/deal/change_complete object signifies change completion. The information in the object indicates the new purchased bundle.
PCM_OP_SUBSCRIPTION_CHANGE_DEAL returns the POIDs of the event objects created by PCM_OP_SUBSCRIPTION_DEAL and PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.
If cancellation or purchase transactions fail, PCM_OP_SUBSCRIPTION_CHANGE_DEAL rolls back any changes made. If any part of the transaction fails, the charge offers associated with the account are not changed.
How Bundles Are Transitioned
To transition a bundle from one account to another, use PCM_OP_SUBSCRIPTION_TRANSITION_DEAL.
PCM_OP_SUBSCRIPTION_TRANSITION_DEAL performs the following steps:
-
Calls PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL to perform any custom validation that you may have added. See "Customizing Bundle Transitions".
-
Checks the /dependency and /transition objects to make sure that the bundle transition does not violate any transition rules.
-
Checks the /deal object to make sure that the bundle being transitioned is not a required bundle in the associated package. If it is required, the transition is not performed.
-
Performs the transition.
-
Charges cancellation fees for the old bundle and purchase fees for the new bundle based on these flags in the /transition object:
-
0 charges fees.
-
1 waives purchase fees.
-
2 waives cancellation fees.
-
3 waives purchase and cancellation fees.
Note:
All cycle fees and noncurrency balances are always prorated regardless of the charge offer's cancellation proration setting.
Note:
PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION transitions valid services with a status of Inactive, but those services remain permanently inactive after the transition.
-
-
During the transition, calls PCM_OP_BILL_CYCLE_FORWARD and PCM_OP_BILL_CYCLE_ARREARS to prorate the cycle fees, if necessary. If the PIN_TRANS_PRO_NORMAL_ON_TRANSITION flag is set, any new charge offers prorate the last cycle fee and the first cycle fee. This flag overrides the user proration settings for charge offer purchases and cancellations.
Customizing Bundle Transitions
You can customize how to transition a bundle from one account to another:
-
To get a list of bundles and charge offers available for transition, use PCM_OP_CUST_POL_TRANSITION_DEALS. Use this opcode to perform any additional filtering of bundles before they are returned as available for transition. For example, use this opcode to limit certain bundles to customers in a specific city.
PCM_OP_CUST_POL_TRANSITION_DEALS to returns the list of bundles available for an account to transition to and the charge offers the bundles contain. This opcode takes a /deal object POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of bundles available for transition, including their charge offer names and descriptions.
Use PCM_OP_CUST_POL_TRANSITION_DEALS to perform any additional filtering of bundles before they are returned as available for transition. For example, use this opcode to limit certain bundles to customers in a specific city.
PCM_OP_CUST_POL_TRANSITION_DEALS is not called by any opcode.
-
To validate how bundles are transitioned, use PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN. This opcode enables customized validation based on account data during bundle-to-bundle transitions.
Use PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN to perform any additional filtering of packages before they are returned as available for transition. For example, you can use this opcode to limit certain packages to customers in a specific city.
For example, you may restrict a bundle transition to customers from a particular location or require that customers own the first bundle for a specific period of time before allowing the transition to a different bundle.
PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL is called by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL before it performs any validation checks. PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL is an empty hook. Usually, customization consists of transition rules based on account data.
Note:
To customize how to transition a package from one account to another, use PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN. See "Customizing Package Transitions without Configuring /transition Objects".
How Bundle Dependencies Are Validated
You use PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY to validate bundle dependencies.
This opcode is called by PCM_OP_CUST_SET_STATUS.
There are two ways to run PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY:
-
Pass in an account and a list of bundles.
PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY checks whether owning the bundles in the account and the bundles you send would violate any dependency rules. You can also send in an account and a package, and this opcode performs the validation checks for the bundles in the account and the bundles in the package.
-
Pass in a list of bundles to validate against another list of bundles.
PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates that owning both sets of bundles would not violate any dependency rules.
In the first case, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY accepts the POID for an account and validates that the bundles in that account do not violate any bundle dependency rules set in the /dependency object. You can also send in a /plan object, and PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY runs the validation checks between the bundles in the /account and the bundles in the package.
If any bundle violates a dependency relationship, the operation fails.
To validate two sets of bundles, send in /account -1 (without a POID); PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates the bundles. If any of the bundles violates a dependency relationship, the operation fails.
Validating Bundle Transitions
To validate bundle-to-bundle dependency rules, use PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY. This opcode is called by PCM_OP_CUST_SET_STATUS.
PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY performs the following steps:
-
Confirms that the validate_deal_dependencies entry in the CM pin.conf file exists and, if so, performs validations; if not, it does nothing.
-
Checks for a PIN_TRANS_NAME_DEAL_VALIDATION entry in the input flist. If this entry exists, the validation checks have already been performed in the current transaction.
-
Verifies that the input is a list of bundles. If PIN_FLD_DELETED_FLAG is set to 1, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY performs the validations required if those bundles were already deleted.
If the bundles pass all validation checks, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns a PIN_FLD_RESULT value of True. If any bundle violates any of the validation checks, this opcode fails and returns a PIN_FLD_RESULT value of False.
If the validation fails because the two bundles are mutually exclusive, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POIDs of the two bundles and a message indicating that the two bundles are mutually exclusive.
If the validation fails because a prerequisite bundle is missing, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POID of the bundle missing a prerequisite.
How Bundles Are Canceled
To cancel a bundle, use PCM_OP_SUBSCRIPTION_CANCEL_DEAL. This opcode cancels all charge offers and discount offers associated with the specific bundle and then cancels the bundle itself. If more than one instance of a bundle has been purchased for the account or service, each bundle instance must be canceled individually.
PCM_OP_SUBSCRIPTION_CANCEL_DEAL is called when a bundle is canceled. This opcode cancels all charge offers and discount offers associated with the specific bundle and then cancels the bundle itself.
To cancel a bundle, PCM_OP_SUBSCRIPTION_CANCEL_DEAL does the following:
-
Opens a transaction.
-
Checks if the bundle is required in the corresponding package. If so, the cancellation is not permitted.
-
From the input flist, retrieves the PIN_FLD_PACKAGE_ID, PIN_FLD_SERVICE_OBJ, name, and type of the charge offers and discount offers associated with the bundle.
If the bundle being canceled has the same PIN_FLD_PACKAGE_ID and PIN_FLD_SERVICE_OBJ as another bundle, then PIN_FLD_DEAL_OBJ is also required to uniquely identify the bundle.
-
Validates that the bundle is available for cancellation.
-
For each charge offer, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT to cancel the charge offer.
-
For each discount offer, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT to cancel the discount offer.
-
Creates an /event/billing/deal/cancel object for auditing purposes.
-
If the bundle cancel is successful, returns the /account POID and the POID of the /event/billing/deal/cancel event.
Overriding Deal Settings at Customer Level
When a customer purchases a deal, you can optionally customize one or more products in the deal. To customize a product in a deal, see the following:
Overriding Add-On Product Validity Dates in a Deal
By default, the validity dates for any add-on product in a deal are set during design time using loadpricelist, ImportExportPricing, PCM_OP_PRICE_SET_PRICE_LIST, or PDC. However, you can override this setting for a specific customer when they purchase a deal by using the following opcodes:
-
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL
-
PCM_OP_CUST_COMMIT_CUSTOMER
-
PCM_OP_CUST_MODIFY_CUSTOMER
To override an add-on product's validity dates, set the opcode's PIN_FLD_VALIDITY_ALIGN_MODE input flist field (under PIN_FLD_DEAL_INFO.PIN_FLD_PRODUCTS) to one of the following:
-
7: Aligns the validity dates with the specified base product. If set to 7, you must also set the PIN_FLD_BASE_PRODUCT_OBJ input flist field to the POID of the base product on which to align validity dates.
-
8: Aligns the validity dates with the active base charge offer that expires first.
-
9: Aligns the validity dates with the active base charge offer that expires last.
-
10: Aligns the validity dates with the active charge offer that expires first.
-
11: Aligns the validity dates with the active charge offer that expires last.
This shows a sample PCM_OP_SUBSCRIPTION_PURCHASE_DEAL input flist for aligning the validity date with a specified base product:
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 113516 0
0 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/ip 192312 8
0 PIN_FLD_PROGRAM_NAME STR [0] "Customer Center"
0 PIN_FLD_DEAL_INFO SUBSTRUCT [0] allocated 20, used 7
1 PIN_FLD_PRODUCTS ARRAY [0] allocated 26, used 26
2 PIN_FLD_CYCLE_START_T TSTAMP [0] (0) <null>
...
2 PIN_VALIDITY_ALIGN_MODE INT [0] 7
2 PIN_FLD_BASE_PRODUCT_OBJ POID [0] 0.0.0.1 /purchased_product 542334Overriding Bundle Proration Settings at Customer Level
By default, the proration setting for each product in a deal is set during the design time using loadpricelist, ImportExportPricing, PCM_OP_PRICE_SET_PRICE_LIST, or PDC. However, you can override this setting for a specific customer when they purchase a deal by using the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL or PCM_OP_CUST_COMMIT_CUSTOMER opcode.
To do so, set the opcode's PIN_FLD_FLAGS input flist field (under PIN_FLD_DEAL_INFO.PIN_FLD_PRODUCTS) to one of the following:
-
0: Prorated cycle fees are calculated according to the system-wide setting in your CM pin.conf file. See "Enabling 30-Day-Based Proration" in BRM Configuring and Running Billing.
-
1: Prorated cycle fees are calculated based on a 30-day month, regardless of the number of days in the billing cycle. For example, if a deal was owned for 6 days in a cycle, the prorated fee would be the cycle fee multiplied by 0.20 (6 ÷ 30).
-
2: Prorated cycle fees are calculated based on the actual number of days in a particular month, such as 28 days in February, 31 days in March, and 30 days in April. For example, if a deal was owned for 6 days in March, the prorated fee would be the cycle fee multiplied by 0.19 (6 ÷ 31).
This shows a sample PCM_OP_SUBSCRIPTION_PURCHASE_DEAL input flist for prorating a customer's product using a 30-day month:
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 101267 7
0 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/ip 98643 6
0 PIN_FLD_PROGRAM_NAME STR [0] "Customer Center"
0 PIN_FLD_DEAL_INFO SUBSTRUCT [0] allocated 20, used 7
1 PIN_FLD_PRODUCTS ARRAY [0] allocated 35, used 35
2 PIN_FLD_FLAGS INT [0] 1Managing Packages
See the following topics:
How BRM Transitions Accounts from Source Packages to Target Packages
BRM uses PCM_OP_SUBSCRIPTION_TRANSITION_PLAN to transition accounts from the current (source) package to a specified (target) package.
This opcode takes as input a source package that specifies the package currently owned by the account and a target package that specifies the package to transition to.
You provide the required transition type as the value of PIN_FLD_TRANSITION_TYPE in the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN input flist. The transition type can be defined as one of the following:
-
(0): Undefined
-
(1): Upgrade
-
(2): Downgrade
-
(3): Generation change
-
Custom transition type
PCM_OP_SUBSCRIPTION_TRANSITION_PLAN transitions accounts from source packages to target packages in the following way:
-
Calls PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN to perform any custom validations.
When PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN completes its actions, it passes the values provided by you to PCM_OP_SUBSCRIPTION_TRANSITION_PLAN.
-
For package transitions where there is a /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN checks the /dependency and /transition objects to make sure that the transition does not violate any transition rules.
For package transitions where there is no /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the value supplied by you in the output flist from PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN.
-
Validates the Primary Basic Service (PBS) that must be applied on the package transition. For package transitions that have no /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the value you specify in the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN output flist.
-
For a regular transition, the two transition packages share a primary service. If not, the transaction fails.
-
For a package transition that involves a generation change, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN skips this step because the two packages do not have to share the same primary service.
-
-
Handles the noncurrency grants in the source package based on the value of PIN_FLD_FLAGS input field. If the value of FLD_FLAGS is PIN_SUBS_TRANSITION_CONTROL_ROLLOVER, the opcode calls a rollover function to ensure, if necessary, that the source package retains noncurrency grants and they are valid to the end of the cycle.
To do so, the rollover function checks the package list for the source and target packages and takes the following action:
-
If the packages are in the same package list, the rollover function searches for all the sub-balances that are truncated because of the transition and extends the sub-balances to the original date before the truncation.
-
If the packages are not in the same package list, this function searches for all the sub-balance buckets that are impacted by the transition and truncates the bucket to the current time.
-
-
Acts on the services in the package-to-package transition. If any services in the packages are listed as inactive, the transition is canceled.
-
If PIN_FLD_FROM_SERVICE is NULL or not specified in the flist, the new service in PIN_FLD_TO_SERVICE is added to the account.
-
If PIN_FLD_TO_SERVICE is NULL or not specified, the service specified in PIN_FLD_FROM_SERVICE is closed.
-
If PIN_FLD_FROM_SERVICE and PIN_FLD_TO_SERVICE have non-null values, only the bundles are canceled and the bundles from PIN_FLD_TO_SERVICE are purchased. Any account bundles in FROM_PLAN are canceled. Any account bundles in TO_PLAN are purchased.
-
-
For the package being phased out due to a generation change in the transition, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN creates a /schedule object that closes the services associated with the package at 00:00:00 hours at the end of the day of transition.
Additionally, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN performs these steps:
-
Prepares the PCM_OP_CUST_UPDATE_SERVICES input flist by specifying the value of END_T as 00:00:00 hours on the following day. For example, if the transition is issued on January 15, 2004, at 12:30:00, the package being phased out ends at January 16, 2004, at 00:00:00 hours.
-
Calls PCM_OP_ACT_SCHEDULE_CREATE with the preceding input flist and the PCM_OP_CUST_MODIFY_CUSTOMER opcode number.
-
On the server side, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN
– Provides an option that customizes the end dates, enabling the end date to occur one day later.
– Enables a Product-End-Delay-for-Package-Transition delay configuration, which is used if the end dates are not passed. This delay configuration is then applied to the date and time of transition as an offset value.
Note:
ERA data is not transferred.
-
-
Charges any cancellation fees for the old bundle and purchase fees for the new bundle based on the PIN_FLD_FEE flag (in the /transition object or the custom value provided by you in the output flist from PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN).
Note:
All cycle fees and noncurrency balances are always prorated regardless of the charge offer's cancellation proration setting.
-
Creates /event/notification/plan/transition and event/notification/plan/transition_complete notification events. These events are not persistent.
BRM returns the following messages based on the success of failure of the transition:
-
If the transition is successful, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN returns a message confirming the success.
-
If the transition type is not a generation change and involves two packages that do not share a primary basic service, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN returns the message The PBS does not match from-plan and to-plan.
-
If the transition violates any transition rules, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN returns the message Plan is not transitionable.
Transition Type API Considerations
The default transition types and your custom transition types are stored in the /config/transition_type object in the PIN_FLD_TRANSITIONS array. For example:
0 PIN_FLD_TRANSITIONS ARRAY [1] 1 PIN_FLD_TYPE ENUM [0] 1 1 PIN_FLD_TYPE_STR STR [0] "Upgrade" 0 PIN_FLD_TRANSITIONS ARRAY [2] 1 PIN_FLD_TYPE ENUM [0] 2 1 PIN_FLD_TYPE_STR STR [0] "Downgrade" 0 PIN_FLD_TRANSITIONS ARRAY [3] 1 PIN_FLD_TYPE ENUM [0] 3 1 PIN_FLD_TYPE_STR STR [0] "Generation Change" 0 PIN_FLD_TRANSITIONS ARRAY [101] 1 PIN_FLD_TYPE ENUM [0] 101 1 PIN_FLD_TYPE_STR STR [0] "RED"
The example shows these transition types:
-
Upgrade - number 1
-
Downgrade - number 2
-
Generation Change - number 3
-
RED - number 101
Note:
The element ID of the array is the same as its PIN_FLD_TYPE.
You could customize a policy opcode to read this object for validation checks.
Customizing Package Transitions without Configuring /transition Objects
You can customize package transitions without configuring the /transition object by doing the following:
-
Obtain a list of packages available for transition: Use PCM_OP_CUST_POL_TRANSITION_PLANS.
This opcode takes a package POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of packages available for transition as output.
-
Customize the validation as necessary: This is optional. Use PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN to perform any additional validation checks or filters for transitioning packages.
For example, you can restrict a package transition to customers from a particular location or require that customers own the first package for a specific period of time before allowing the transition to a different package.
-
Provide custom values for service and fees: This action is required if you package to customize package transitions without configuring the /transition object.
Modify the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN output flist to specify the service that must be associated with the packages and whether to waive purchase and cancellation fees associated with the packages. To do so:
-
Add the PIN_FLD_RESULTS array to the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN output flist:
0 array RESULTS 1 int FEE_FLAG 1 str PERMITTED
-
Set the PIN_FLD_FEE_FLAG field in PIN_FLD_RESULTS to one of the values in Table 21-3:
Table 21-3 PIN_FLD_FEE_FLAG Values
Value Description 0
Charge cancellation fees for the old charge offer and purchase fees for the new charge offer.
1
Waive purchase fees.
2
Waive cancellation fees.
3
Waive purchase fees and cancellation fees.
-
Set the PIN_FLD_PERMITTED field of this array to the Primary Basic Service (PBS) that must apply to the package transition.
For example,
0 PIN_FLD_RESULTS ARRAY [0] allocated 20, used 3 1 PIN_FLD_FEE_FLAG INT [0] 3 1 PIN_FLD_PERMITTED STR [0] "/service/telco/gsm/telephony"
-
PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN is called by PCM_OP_SUBSCRIPTION_TRANSITION_PLAN.
About Providing Transition Rules Using Policy Opcodes
You use PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN to automatically enable package transitions to any package without /transition objects.
Note:
Customize PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN for the package transitions for which a /transition object is not defined in PDC or Pricing Center.
When BRM attempts to transition an account and the package transition rule does not have a /transition object, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the following information you provide in the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN output flist:
-
Your specification on whether to charge any cancellation fees associated with the source package for the account and purchase fees for the new charge offer for this transition.
-
The Primary Basic Service (PBS) that must apply to the package transition.
Note:
If you do not provide these values, the opcode searches for a /transition object. If no /transition object exists for the transition rule, the transition fails.
You can provide these values to handle some package transitions and configure package transition rules in PDC or Pricing Center for others.
Note:
-
You can customize package transitions in this way if the transition does not involve a generation change.
-
You cannot customize bundle transitions in this manner. PDC or Pricing Center must be used to set up transition rules to transition bundles.
-
You cannot transition packages under certain conditions. For example, you cannot transition a package when add-on bundles that are not part of the original package are active and owned by the account.
Customizing Account Bundles during Package Transitions
You can customize account bundles during package transitions. To do so, provide the associated charge offer information in the PIN_FLD_PRODUCTS input field for PCM_OP_SUBSCRIPTION_TRANSITION_PLAN. PIN_FLD_PRODUCTS is located in the PIN_FLD_DEAL_INFO substructure of the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN input flist.
Managing Contracts
See the following topics:
Creating Contracts
To create a contract for a customer, use the PCM_OP_CONTRACT_CREATE_CONTRACT opcode. This opcode creates a /subscriber_contract object and generates a contract creation event. This opcode is called by Billing Care.
You can customize how contracts are created by using these Contract FM policy opcodes:
-
PCM_OP_CONTRACT_POL_POST_CREATE_CONTRACT. By default, this opcode does nothing.
-
PCM_OP_CONTRACT_POL_PREP_CONTRACT. By default, this opcode does nothing.
-
PCM_OP_CONTRACT_POL_VALID_CONTRACT. By default, this policy opcode validates a customer's contract for valid start and end dates, pricing objects, account objects, and contract objects (during modification).
Modifying Contracts
To modify a contract owned by a customer, use PCM_OP_CONTRACT_MODIFY_CONTRACT. This opcode validates the contract input, updates the existing contract, and generates a contract modification event. This opcode is called by Billing Care.
Note:
You cannot modify future-dated and backdated contracts.
You can customize how contracts are modified by using the PCM_OP_CONTRACT_POL_VALID_CONTRACT policy opcode.
Canceling Contracts
To cancel a customer's contract, use PCM_OP_CONTRACT_CANCEL_CONTRACT. This opcode cancels an existing contract, cancels all pricing objects associated objects, generates a contract cancellation event, and applies an early termination fee, if required by the terms.
This opcode is called by the pin_contracts utility. See "pin_contracts" in BRM Managing Customers.
Renewing Contracts
To renew a customer's contract, use PCM_OP_CONTRACT_RENEW_CONTRACT. This opcode renews customer contracts that expire today.
This opcode is called by the pin_contracts utility.
PCM_OP_CONTRACT_RENEW_CONTRACT does the following:
-
Validates that the contract for the specified account has auto-renewal enabled, expires tomorrow, and renews the same package to new or different terms. If validation fails, renewal is not permitted.
-
If purchasing a new package, calls PCM_OP_SUBSCRIPTION_TRANSITION_PLAN to transition the specified account from the source package to the target package.
-
If purchasing a new bundle, calls PCM_OP_SUBSCRIPTION_TRANSITION_DEAL to transition the specified account from the source bundle to the target bundle.
-
Calls the general ledger module to calculate the standalone selling price. See "About the Standalone Selling Price" in BRM Collecting General Ledger Data for more information.
-
Returns the POIDs of the account and new package terms.
You can customize how contracts are renewed by using the PCM_OP_CONTRACT_POL_VALID_CONTRACT policy opcode.
Managing Purchase, Cycle, and Usage Charges in Purchased Offers
Purchase, cycle, and usage validity periods define when charge offers and discount offers are valid and when charge offer fees are charged and discounted.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT and PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT, which set the purchase, cycle, and usage validity periods of the bundle's charge offers and discount offers, respectively.
If the system is configured for time-stamp rounding, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT and PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT round the start and end times to 00:00:00 hours. However, when a charge offer's purchase, cycle, and usage start and end units are set to 1 (seconds), 2 (minutes), or 3 (hours), and the validity period is less than 24 hours, time stamps are not rounded, regardless of your system configuration. If the validity period is greater than 24 hours, the cycle end time stamp is rounded when calculating the scale to determine the cycle fee amount to charge.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL uses the purchase, cycle, and usage validity dates that are specified in the /deal object by default. If you specify alternative validity periods for charge offers and discount offers, those validity dates permanently override the dates specified in the /deal object.
To set the purchase, cycle, and usage start and end times, pass the following values in opcode input flists in the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays. In the following fields, the asterisk (*) indicates either PURCHASE, CYCLE, or USAGE.
Note:
The cycle and usage validity periods must fall entirely within the purchase validity period.
- Specify the start time as follows:
- To start immediately (when the charge offer or discount offer is purchased), set the value of PIN_FLD_*_START_T and PIN_FLD_*_START_UNIT to 0. The opcode sets the start time to the purchase time.
- To start on first usage (when the subscriber uses the charge offer or discount offer for the first time) set the PIN_FLD_*_START_UNIT field to -1 and the PIN_FLD_*_START_OFFSET field to 0.
- To start relative to the purchase time, set the relative unit (for example, days or cycles) in PIN_FLD_*_START_UNIT and set the number of relative units in PIN_FLD_*_START_OFFSET. The relative start time is calculated by adding the relative offset period to the purchase time.
- Specify the end time as follows:
- To never end, set the value of PIN_FLD_*_END_T and PIN_FLD_*_END_UNIT to 0.
- To end relative to the start time, set the relative unit (for example, days or cycles) in PIN_FLD_*_END_UNIT and set the number of relative units in PIN_FLD_*_END_OFFSET. The relative end time is calculated by adding the relative offset period to the start time.
When the charge offer or discount offer is purchased, the start and end times are calculated based on the purchase time. The validity period is set in the PIN_FLD_*_START_T and PIN_FLD_*_END_T fields of the account's /purchased_product and /purchased_discount objects.
If the validity period has a relative start or end time, the details about the relative offset are stored in the PIN_FLD_*_START_DETAILS and PIN_FLD_*_END_DETAILS fields of the purchased charge offer or purchased discount offer. The details fields store three values: the mode of the validity period, the relative offset unit, and the number of offset units in the relative period. For more information, see "Storing Relative Start and End Times for an Account's Charge Offers and Discount Offers".
Changing the Purchase, Usage, and Cycle Start and End Times
- PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS when the status of an account's charge offer is changed.
- PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT when the same charge offer is purchased multiple times and the charge offer's PIN_FLD_MODE field is set to 1 or 2.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_SUBSCRIPTION_SET_PRODINFO returns the entire event flist for the events created as a result of the modification. If the flag is not set, the opcode returns the event POIDs of all event objects created as a result of the modification.
After a charge offer is purchased and its start and end dates have been set, you can change the start time to specify only another fixed date, and you can change the end time to specify only another fixed date or to end never.
To change the purchase, cycle, or usage validity period, specify the new start and end dates in their respective START_T and END_T fields in the PIN_FLD_PRODUCTS array in the input flist.
If you change the purchase, cycle, or usage start time from first usage to a fixed date, PCM_OP_SUBSCRIPTION_SET_PRODINFO generates an event that causes the validity period to be updated in ECE.
The start and end dates are stored in the account's /purchased_product object.
If your system is configured to round time stamps, and if you modify the purchase, usage, or cycle start and end times, PCM_OP_SUBSCRIPTION_SET_PRODINFO rounds the new times to 00:00:00 hours. However, if the purchase, cycle, and usage start and end units are set to 1 (seconds), 2 (minutes), or 3 (hours), and the validity period is less than 24 hours, time stamps are not rounded, regardless of your system configuration.
BRM does not allow you to change a charge offer's purchase, usage, and cycle start and end dates as follows:
- The charge offer purchase start date if the purchase start date has elapsed.
For example, on January 1, a charge offer is purchased with the purchase start date set to January 15. On January 10, you can backdate the purchase start date to January 5. But, you cannot backdate the purchase start date on January 16; that is, you cannot backdate the purchase date when the January 15 date has passed.
- The charge offer cycle start date if the cycle fees have been applied.
- The charge offer purchase, usage, and cycle end date prior to the respective purchase start date.
- The charge offer purchase, usage, cycle start or end dates prior to the G/L posting date.
Overriding Charges and Discounts for a Period of Time
Use PCM_OP_SUBSCRIPTION_CRUD_OFFER_OVERRIDE to specify when and how to override charges and discounts during specified time periods. It creates, reads, updates, or deletes a specified /offering_override_value object based on the value of an input flag.
For more information, see "Dynamically Changing One-Time and Recurring Fees Based on Date" in BRM Configuring Pipeline Rating and Discounting.
When calling the opcode, pass in the following input data:
-
The POID of the /offering_override_values object.
-
The POID of the /purchased_product or /purchased_discount object.
-
The operation to perform on the /offering_override_values object.
To specify the operation to perform on the /offering_override_values object, set the PIN_FLD_FLAG field in the PIN_FLD_OVERRIDE_PRODUCTS or PIN_FLD_OVERRIDE_DISCOUNTS array to one of the following:
-
1: Adds a date range and pricing tag combination for the specified event type. That is, it adds a PIN_FLD_OVERRIDE_DATE_RANGE buffer to each matching PIN_FLD_USAGE_MAP array.
-
2: Adds or updates the pricing tag name, amount, or percentage for the specified date ranges.
-
3: Deletes the specified /offering_override_values object.
-
4: Deletes all expired date range and pricing tag combinations from the /offering_override_values object. That is, it deletes from the PIN_FLD_USAGE_MAP array all PIN_FLD_DATE_RANGES buffers with expired date ranges.
-
5: Deletes the specified pricing tag from the /offering_override_values object's PIN_FLD_DATE_RANGES buffer.
-
6: Reads the /offering_override_values object.
-
8: Deletes all usage maps for the specified event type. For example, it deletes all PIN_FLD_USAGE_MAPS arrays associated with the /event/billing/product/fee/cycle/cycle_forward_monthly event.
-
PCM_OP_SUBSCRIPTION_SET_PRODINFO when the PIN_FLD_OVERRIDE_PRODUCTS array is passed in the PIN_FLD_PRODUCTS array.
-
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO when the PIN_FLD_OVERRIDE_DISCOUNTS array is passed in the PIN_FLD_DISCOUNTS array.
Your third-party client applications can also call PCM_OP_SUBSCRIPTION_CRUD_OFFER_OVERRIDE directly.
Specifying Purchase, Cycle, and Usage Start and End Times
When the purchase, cycle, or usage period has a fixed start time (starts and ends on a specific date and time), the start and end times are passed in opcode flists in time stamp fields:
-
PIN_FLD_PURCHASE_START_T
-
PIN_FLD_PURCHASE_END_T
-
PIN_FLD_CYCLE_START_T
-
PIN_FLD_CYCLE_END_T
-
PIN_FLD_USAGE_START_T
-
PIN_FLD_USAGE_END_T
When the purchase, cycle, or usage period has a relative start or end time, the details about the relative period are passed in opcode flists in unit and offset fields:
-
These unit fields specify the type of relative unit:
-
PIN_FLD_PURCHASE_START_UNIT
-
PIN_FLD_PURCHASE_END_UNIT
-
PIN_FLD_CYCLE_START_UNIT
-
PIN_FLD_CYCLE_END_UNIT
-
PIN_FLD_USAGE_START_UNIT
-
PIN_FLD_USAGE_END_UNIT
The unit can be one of these values:
-
Seconds = 1
-
Minutes = 2
-
Hours = 3
-
Days = 4
-
Accounting cycles = 8
-
-
These offset fields specify the number of units in the relative period:
-
PIN_FLD_PURCHASE_START_OFFSET
-
PIN_FLD_PURCHASE_END_OFFSET
-
PIN_FLD_CYCLE_START_OFFSET
-
PIN_FLD_CYCLE_END_OFFSET
-
PIN_FLD_USAGE_START_OFFSET
-
PIN_FLD_USAGE_END_OFFSET
-
The unit and offset fields are used in combination to determine the relative offset of the purchase, cycle, and usage periods. For example:
-
If a charge offer's PIN_FLD_CYCLE_START_UNIT has a value of 8 (accounting cycles) and PIN_FLD_CYCLE_START_OFFSET has a value of 3, the cycle fee starts three accounting cycles after the charge offer is purchased.
-
If a discount offer's PIN_FLD_PURCHASE_END_UNIT has a value of 8 (accounting cycles) and PIN_FLD_PURCHASE_END_OFFSET has a value of 3, the discount offer expires three accounting cycles after it is activated.
You can specify any number of units in the offset fields, up to 1048576. This is equivalent to approximately 12 days in seconds, 728 days in minutes, and 119 years in hours.
The relative offset information in the unit and offset fields is stored in the BRM database in details fields. For more information, see "Storing Relative Start and End Times for an Account's Charge Offers and Discount Offers".
Calculating the Cycle Forward Fee
If you modify the cycle start time or cycle end time for the charge offer in the middle of a cycle, PCM_OP_SUBSCRIPTION_SET_PRODINFO calculates the cycle forward fee or cycle arrears fee for the charge offer.
If the charge offer has a cycle forward fee, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD is called to perform the following actions:
-
If you change the cycle start time from a future time to the current time, applies the cycle forward fee for the current time through the end of the current cycle.
-
If you change the cycle end time to an earlier time and the cycle forward fee is already applied for that cycle, refunds the cycle forward fee for the unused portion of the cycle.
-
If you change the cycle end time to a later time and the cycle forward fee is already applied for that cycle, applies the cycle forward fee for the end of the old cycle end time through the end of the new cycle.
Calculating the Cycle Arrears Fee
If you modify the cycle start time or cycle end time for the charge offer in the middle of a cycle, PCM_OP_SUBSCRIPTION_SET_PRODINFO calculates the cycle forward fee or cycle arrears fee for the charge offer.
Note:
-
Refunds for cycle arrears fees are not supported. Use caution when changing cycle end times.
-
Changing the cycle end time for a cycle arrears fee has some limitations. See "Cycle Arrears Charge Offer Limitations".
If the charge offer has a cycle arrears fee, PCM_OP_SUBSCRIPTION_CYCLE_ARREARS is called to perform the following actions:
-
If you change the cycle end time from a future time to the current time, the cycle arrears fee is applied for the cycle.
-
If you change the cycle end time from a future time to an earlier time, but later than the current time, the cycle arrears fee is not applied. However, the cycle arrears fee is applied during the next billing run.
Cycle Arrears Charge Offer Limitations
If you change the cycle end time only once in a cycle, the cycle fee is applied either the day of the change or the next billing day, depending on the new cycle end value. If the new PIN_FLD_CYCLE_END_T value is the same as the event time, the cycle arrears fee is charged at the same time; otherwise, it is charged at the next billing time.
Note:
If you use time stamp rounding, the cycle end time is compared to the event date. Otherwise, the cycle end time is compared to the event time (the current time).
If you change the cycle end date more than once in a cycle:
-
If the cycle arrears fee from the first change has not yet been applied, it will not apply after the second change is made.
-
If the new cycle end date is changed to 0 (never) or to a date later than the end of the current accounting cycle, cycle fees apply accordingly, depending on which of the following cancellation settings you specified when setting up proration for your pricing package:
-
Charge full: Applies no cycle fees for the whole cycle.
-
Based on usage and is proratable: Applies cycle fees from the new cycle end date to the end of the cycle.
-
No Charge and proratable: Applies cycle fees from the new cycle end date to the end of the cycle.
-
No Charge and is not proratable: Applies full cycle fees.
-
About Backdated Purchase, Usage, or Cycle End Dates
Setting a charge offer purchase, usage, or cycle start dates to a backdated date is different from backdating a purchase itself. When the charge offer purchase, usage, or cycle start dates are set to a backdated date, though the cycle charges are applied from the backdated date, the change is effective only from the current time.
For example, you purchase a charge offer on February 1, and set the PURCHASE_ START_T, USAGE_START_T, and CYCLE_START_T fields of the charge offer to a backdated date of January 15. In this case, the charges are applied from January 15, but the creation time of the charge offer remains February 1 (current time). Thus, if usage events during the period of January 15 to February 1 are rerated, they are not rated with this charge offer.
Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the charge offer becomes effective from January 15 (the creation time of the charge offer is set to January 15), and the charges are also applied from the backdated date of January 15.
Oracle recommends that you use the latter procedure for backdating a purchase.
Note:
You cannot set the discount offer PURCHASE_ START_T, USAGE_START_T, and CYCLE_START_T to a backdated date.
Similarly, backdating a charge offer or discount offer's purchase, usage, or cycle end dates is different from backdating the cancellation. When the charge offer or discount offer's purchase, usage, or cycle end dates are set to backdated date, though the cycle charges are refunded from the backdated date, the change is effective only from the current time.
For example, on February 1, you set the PURCHASE_ END_T, USAGE_END_T, or CYCLE_END_T fields of a charge offer to the backdated date of January 15. In this case, the charges are refunded from January 15, but the change in the END_T to January 15 is effective only from the current time (February 1). Thus, if usage events during the period of January 15 to February 1 are rerated, they are rated with this charge offer.
Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the charge offer is available for rating from January 15, and the charges are also refunded from the backdated date of January 15.
BRM does not allow you to backdate the following:
-
The charge offer purchase start date if the purchase start date has elapsed.
For example, on January 1, a charge offer is purchased with the purchase start date set to January 15. On January 10, you can backdate the purchase start date to January 5. But, you cannot backdate the purchase start date on January 16; that is, you cannot backdate the purchase date when the January 15 date has passed.
-
The charge offer cycle start date if the cycle start date has elapsed.
-
The usage and cycle end date of a charge offer prior to its purchase start date.
-
The purchase, usage, and cycle end date of a discount offer prior to its purchase start date.
-
The purchase, usage, or cycle start and end dates of a charge offer prior to the G/L posting date.
-
The purchase, usage, and cycle end dates of a discount offer prior to the G/L posting date.
Example of Backdated Purchase, Usage, and Cycle Start and End Dates
On April 1, consider that you create an account that owns a charge offer with $9.95 as a cycle forward fee, 3600 as Anytime Minutes, and the start date set to June 20. On May 2, you change the start date to April 16. The charges are as follows:
-
$4.98 monthly charges and 1800 Anytime Minutes for the period from April 16 to May 1.
-
$9.95 monthly charges and 3600 Anytime Minutes for the period from May 1 to June 1.
Backdating Purchase, Usage, or Cycle Start and End Dates
To backdate the purchase, usage, or cycle start or end dates of a charge offer or purchase, usage, or cycle end date of a discount offer during purchase, enter the backdated date in the respective date fields.
After a charge offer is purchased, use PCM_OP_SUBSCRIPTION_SET_PRODINFO to backdate the purchase, usage, or cycle start and end dates. Similarly, use PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO to backdate the purchase, usage, or cycle end dates of the discount offer.
Note:
If you set the end date of a discount offer on a cycle forward or cycle arrears event to a previous accounting cycle, the discount offer is refunded only for the current accounting cycle.
Storing Relative Start and End Times for an Account's Charge Offers and Discount Offers
Relative validity information in the PIN_FLD_*_UNIT and PIN_FLD_*_OFFSET fields that are passed in opcode flists are stored in the database in details fields:
-
PIN_FLD_PURCHASE_START_DETAILS
-
PIN_FLD_PURCHASE_END_DETAILS
-
PIN_FLD_CYCLE_START_DETAILS
-
PIN_FLD_CYCLE_END_DETAILS
-
PIN_FLD_USAGE_START_DETAILS
-
PIN_FLD_USAGE_END_DETAILS
When charge offers and discount offers are purchased, the details fields are stored in /purchased_product and /purchased_discount objects.
The start-details and end-details fields are 32-bit integer fields that store the mode of the validity period, the relative offset unit, and the number of offset units in the relative period:
-
Mode: The mode specifies generally when the validity period starts or ends. The mode is stored in the lower 8th bit.
When a charge offer or discount offer is purchased, its start and end dates are set and the mode value in the start-details field is set to PIN_VALIDITY_ABSOLUTE (a value of 0).
The end-details field can have a value of PIN_VALIDITY_ABSOLUTE if the end date is specified or a value of PIN_VALIDITY_NEVER (a value of 2) if the validity period never ends.
Note:
Before the charge offer or discount offer is purchased, the mode in the details field of the charge offer or discount offer in the /deal object can also specify other values such as immediate and relative. The mode helps to determine how the start and end times are set when the charge offer or discount offer is purchased.
-
Relative offset unit: This value specifies the type of offset unit and corresponds to the value of PIN_FLD_*_START_UNIT or PIN_FLD_*_END_UNIT that is passed in opcode flists. The relative offset unit is stored in the next four bits of the details field and can have one of these values:
-
Seconds = 1
-
Minutes = 2
-
Hours = 3
-
Days = 4
-
Accounting cycles = 8
-
-
Number of offset units: This value specifies how many offset units are in the relative period and corresponds to the value of PIN_FLD_*_START_OFFSET or PIN_FLD_*_END_OFFSET that is passed in opcode flists. The number of offset units is stored in the remaining 20 bits of the details field.
How Cycle Fees Are Calculated for Backdated Cancellation or Inactivation
When you backdate a cancellation or inactivation, the refunds for the events that occurred during the backdated period are prorated and applied accordingly.
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD determines the scale values that are used by for prorating the cycle fee amount to be refunded. This opcode prorates and applies the cycle fee amount to be refunded when a charge offer or discount offer is canceled or inactivated.
When you backdate the cancellation of a charge offer with cycle forward events, cycle forward fees are prorated and refunded from the backdated cancellation date.
Example of backdated charge offer cancellation
When you backdate the cancellation of a charge offer with cycle forward events, cycle forward fees are prorated and refunded from the backdated cancellation date.
For example, consider that you create an account on September 1 with the DOM set to 1. On November 5, you backdate the cancellation of the charge offer with the following details to September 15:
-
Cycle forward fee $3.00.
-
Proration set to Charge based on amount used.
The three cycles including the current cycle are refunded as follows:
-
$1.50 for the period of September 15 to October 1 (for 15 days).
-
$3.00 for the period of October 1 to November 1.
-
$3.00 for the period of November 1 to December 1.
These refunds are included in the next bill that gets generated during the bill run on December 1.
Example of backdated discount offer cancellation
On April 1, consider that you create an account that owns a charge offer with $50 as a cycle forward fee and a discount of 10% on the monthly cycle fees. A cycle fee of $50 and a discount of $5 is applied for the period of April 1 to May 1, making the balance $45.
On April 28, you cancel the discount offer backdated to April 16. The discount of $2.50 applied for the period of April 16 to May 1 is refunded, making the balance as $47.50.
How Earned and Unearned Revenue Is Set for Backdated Period
In the case of cycle forward events, the charges for the backdated period have the EARNED_START_T (billing_cycle_start) and EARNED_END_T (billing_cycle_ end) set to the backdated period.
For example, on February 15, a charge offer with cycle forward events for an account with the DOM set to 1 is purchased, backdated to January 15. The EARNED_ START_T and EARNED_END_T for the backdated period (January 15 through February 1) are January 15 and February 1 respectively, while the EARNED_START_T and EARNED_END_T for the current cycle are February 1 and March 1 respectively.
Applying Recurring Charges
The main opcodes used for applying recurring charges are:
-
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD. See "Applying Cycle Forward Fees" for more information.
-
PCM_OP_SUBSCRIPTION_CYCLE_ARREARS. See "Applying Cycle Arrears Fees" for more information.
Applying Cycle Forward Fees
To apply a cycle forward fee to a balance group, use PCM_OP_SUBSCRIPTION_CYCLE_FORWARD.
This opcode is called to charge or refund cycle forward fees (for example, when a charge offer or discount offer is purchased, canceled, activated, or inactivated).
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD performs these operations:
-
When a charge offer or discount offer is purchased or activated during the cycle, determines scale values that are used for prorating the cycle forward fee amount to be charged.
-
When a charge offer or discount offer is canceled or inactivated during the cycle, determines scale values that are used for prorating the cycle forward fee amount to be refunded.
-
Uses customized charge offers when valid to calculate fees or refunds. If a customized charge offer is valid for only part of a cycle, it contributes toward the total charge or refund based on the length of its validity.
-
When there is a pricing change scheduled for the next or current cycle, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD gets a list of prices and the period in which they are applicable and calculates the correct charges.
-
When the ApplyRolloverBeforeCycleFees business parameter is enabled, calls PCM_OP_SUBSCRIPTION_CYCLE_ROLLOVER to roll over unused resources from one cycle to succeeding cycles.
-
Calculates and sets CYCLE_FEE_START_T and CYCLE_FEE_END_T to the next period, if applicable.
-
After all the charge offers, discount offers, and their cycle forward fees are determined, it sends the information to PCM_OP_ACT_USAGE to rate and apply the charges.
Note:
If the charge offer or discount offer starts on first usage (when the customer first uses the charge offer or discount offer) and its validity period has not yet been set, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD does not call PCM_OP_ACT_USAGE and cycle fees are not applied.
-
For auditing purposes, it creates /event/billing/product/fee/cycle/cycle_forward_type objects, where type is the frequency of the cycle forward charge (for example, daily, weekly, monthly, bimonthly, quarterly, semiannual, or annual).
-
If successful, it returns the POIDs of the /account object and the /event/billing/product/fee/cycle/cycle_forward_type event.
Applying Cycle Arrears Fees
To apply a cycle arrears fee, use PCM_OP_SUBSCRIPTION_CYCLE_ARREARS.
Note:
Cycle arrears fees are applied only for a single month.
PCM_OP_SUBSCRIPTION_CYCLE_ARREARS performs these operations:
-
When charge offers or discount offers with cycle fees are canceled or inactivated during a cycle, calculates the scale to prorate the cycle arrears fee amount to be charged.
-
When there is a pricing change in the previous or next cycle, gets a list of prices and the period in which they are applicable and calculates the correct charges.
-
Uses customized charge offers when valid to calculate fees or refunds. If a customized charge offer is valid for only part of a cycle, it contributes a portion of the total charge or refund based on the length of its validity.
-
After all the cycle arrears fees are determined, sends the information to PCM_OP_ACT_USAGE to rate and apply the charges.
Note:
If the charge offer or discount offer starts on first usage and its validity period has not yet been set, PCM_OP_SUBSCRIPTION_CYCLE_ARREARS does not call PCM_OP_ACT_USAGE and cycle fees are not applied.
-
Creates the /event/billing/product/fee/cycle/cycle_arrears event for auditing purposes.
-
If successful, returns the POIDs of the /account object and the /event/billing/product/fee/cycle/cycle_arrears event.
Applying Folds
Use PCM_OP_SUBSCRIPTION_CYCLE_FOLD to apply balance impacts for fold events.
PCM_OP_SUBSCRIPTION_CYCLE_FOLD performs these operations:
-
Calls PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD to get the order in which to fold the account's balances. By default, folds are applied in ascending order of the balance element IDs.
-
Checks the value of the balance's PIN_FLD_APPLY_MODE field in the /config/beid object to see whether the balance is specified to be rolled over. For more information, see "Specifying Which Balances to Fold".
-
Applies folds for all of the account's balance groups and also for each balance in the balance group that is specified to be rolled over. However, if a balance element ID is specified in the input flist, only that balance is folded.
-
After applying the balance impacts, creates /event/billing/cycle/fold event for auditing purposes.
-
If successful, returns the POIDs of the /account object and the /event/billing/product/fee/cycle/fold event.
Customizing How Folds Are Applied
To customize how folds are applied, use PCM_OP_SUBSCRIPTION_POL_PRE_FOLD.
For example, when billing is run, this opcode is called to verify that the pin_cycle_fees utility has applied cycle fees to an account.
This opcode is called by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT and PCM_OP_BILL_MAKE_BILL.
This opcode is an empty hook.
Customizing the Order to Apply Folds
To customize the order in which folds are applied, use PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD.
By default, balances are folded in ascending order based on the balance element ID. This opcode enables you to change the order in which balances are folded.
For example, you can fold balances in descending order of the balance element IDs. To do this, sort the PIN_FLD_BALANCES array and return the sorted array.
This example shows the PIN_FLIST_SORT statement for sorting the balances array in descending order:
*out_flistp = PIN_FLIST_COPY(i_flistp, ebufp); s_flistp = PIN_FLIST_CREATE(ebufp); PIN_FLIST_ELEM_SET(s_flistp, (void *)NULL, PIN_FLD_BALANCES, PIN_ELEMID_ANY, ebufp); PIN_FLIST_SORT(*out_flistp, s_flistp, 1, ebufp);
PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD returns the contents of the input flist including the POID of the /balance_group object and the balance array sorted in ascending order.
PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD is called by PCM_OP_SUBSCRIPTION_CYCLE_FOLD.
Specifying Which Balances to Fold
You can specify which balances are impacted by fold events. This enables you to exclude folding balances that do not need to be folded.
To specify the balances to fold, use PDC or Pricing Center.
Customizing Which Balances to Fold When Charge Offers Are Canceled
PCM_OP_SUBSCRIPTION_POL_PREP_FOLD prepares the list of balances that must be folded when a charge offer is canceled.
This opcode is called when a charge offer is canceled and it performs the following functions:
-
Checks the canceled charge offer.
-
Creates a list of balances affected by the cancellation that must be folded.
-
Calls PCM_OP_SUBSCRIPTION_CYCLE_FOLD and passes the list of balances as the input.
If you do not want to fold balances after a charge offer is canceled, customize PCM_OP_SUBSCRIPTION_POL_PREP_FOLD by removing or commenting out the code in the fm_subscription_pol_prep_fold.c file.
PCM_OP_SUBSCRIPTION_POL_PREP_FOLD is called by PCM_OP_SUBSCRIPTION_CYCLE_FORWARD and PCM_OP_SUBSCRIPTION_CYCLE_ARREARS.
Getting Data about Bundles, Charge Offers, Discount Offers, and Services
See the following topics:
Getting Purchased Offers
PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS retrieves the purchased charge offers and discount offers associated with an account. Because charge offers and discount offers were part of the account object, reading the account object would fetch all the purchased charge offers and discount offers.
The opcode requires a scope object in the PIN_FLD_SCOPE_OBJ of the input flist. The scope object can be an account, bill unit (/billinfo object), or service object. The meanings of passing these different scope objects are as follows:
-
/account object: Fetches all charge offers and discount offers for the account and its services.
-
/billinfo object: Fetches charge offers and discount offers that contribute to the specified bill unit.
-
/service object: Fetches charge offers and discount offers that belong to the specified service.
The opcode logic performs a main search based on the input flist passed in the input. The search is repeated if there are more result sets to be fetched. For example, if a service object is passed as the scope object, the input flist would look like this:
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 618010 0 0 PIN_FLD_SCOPE_OBJ POID [0] 0.0.0.1 /service/ip 615706 3 0 PIN_FLD_STATUS_FLAGS INT [0] 3 0 PIN_FLD_VALIDITY_FLAGS INT [0] 3 0 PIN_FLD_INCLUSION_FLAGSINT [0] 2 0 PIN_FLD_OVERRIDE_FLAGS INT [0] 2 0 PIN_FLD_END_T TSTAMP [0] (1154415600) Tue Aug 1 00:00:00 2006 0 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.1 /deal 615702 3 0 PIN_FLD_OVERRIDDEN_OBJ POID [0] 0.0.0.1 /purchased_product 324706 0 0 PIN_FLD_PACKAGE_ID INT [0] 23 0 PIN_FLD_PRODUCTS ARRAY [*] NULL array ptr 0 PIN_FLD_DISCOUNTS ARRAY [*] NULL array ptr
The input for the opcode also contains qualifiers to fetch the correct set of offerings:
-
To specify whether to fetch only charge offers or only discount offers use the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays.
-
To specify only a limited number of fields to fetch, use the fields under the PRODUCTS and DISCOUNTS arrays.
-
To fetch charge offers/discounts valid as of a given time, the PIN_FLD_END_T field can be passed in the input. Additional qualifiers such as cycle, usage, or purchase can be passed in as PIN_FLD_VALIDITY_FLAGS.
-
PIN_FLD_STATUS_FLAGS:
-
PIN_SUBS_FLG_OFFERING_STATUS_ACTIVE: Get only active offerings.
-
PIN_SUBS_FLG_OFFERING_STATUS_INACTIVE: Get only inactive offerings.
-
PIN_SUBS_FLG_OFFERING_STATUS_CLOSED: Get only closed offerings.
Note:
Use of multiple values implies the target object should satisfy any of the above.
-
-
PIN_FLD_VALIDITY_FLAGS:
-
PIN_SUBS_FLG_OFFERING_VALIDITY_CYCLE: Compare the END_T value with the CYCLE_END_T value.
-
PIN_SUBS_FLG_OFFERING_VALIDITY_PURCHASE: Compare the END_T value with the PURCHASE_END_T value.
-
PIN_SUBS_FLG_OFFERING_VALIDITY_USAGE: Compare the END_T value with the USAGE_END_T value.
Note:
Use of multiple flags implies the target object must satisfy all of the above.
-
-
PIN_FLD_INCLUSION_FLAGS:
-
PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_PRODS: Include all eligible charge offers, including account and subscription charge offers.
-
PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_DISCS: Include all eligible discount offers, including account and subscription discount offers.
Note:
When this field is missing, only eligible offerings from a specified scope are returned.
-
-
PIN_FLD_OVERRIDE_FLAGS:
-
PIN_SUBS_FLG_OFFERING_ACCT_LEVEL_ONLY: Filter out only account level offerings. Valid for /account objects only.
-
PIN_SUBS_FLG_OFFERING_OVERRIDE_PRODS_ONLY: Must be used with the OVERRIDDEN _OBJ field. When a valid offering POID is sent, this flag returns all the offerings that override the input offering. When a NULL offering POID is sent, only the base charge offers are returned. Valid for any scope.
Note:
When none of these are present (or this field is missing), all charge offers are returned.
-
-
PIN_FLD_PACKAGE_ID: Limits a search to the package ID, which translates to a single package. This can be used with any scope.
-
PIN_FLD_DEAL_OBJ: Limits a search to objects that are part of the same bundle by entering the bundle object POID.
Getting Packages, Bundles, and Charge Offers for Purchase
Use the following opcodes to get packages, bundles, and charge offers for customer purchase:
-
To get a list of packages for customer purchase, use PCM_OP_CUST_POL_GET_PLANS. This opcode chooses the packages to return based on the Automatic Account Creation (AAC) fields in the input flist, enabling the opcode to qualify different packages depending on the values of the fields returned by each customer.
You must customize PCM_OP_CUST_POL_GET_PLANS to search for and display the package list by customer type. By default, if you pass in a type-only POID, the opcode retrieves new packages; otherwise, it retrieves addon packages.
You can customize PCM_OP_CUST_POL_GET_PLANS to search the /group/plan_list object by customer type and display the correct package lists based on the customer type.
PCM_OP_CUST_POL_GET_PLANS is not called by any opcode.
-
To get a list of bundles for customer purchase, use PCM_OP_CUST_POL_GET_DEALS. This opcode searches for all /deal objects that are valid (bundle END_T = 0 is valid). Each bundle in the list is then read and checked to see whether the bundle's permitteds array allows the object type to purchase it.
PCM_OP_CUST_POL_GET_DEALS is not called by any opcode.
-
To get a list of charge offers for customer purchase, use PCM_OP_CUST_POL_GET_PRODUCTS. The charge offer's PIN_FLD_PERMITTEDS array is checked for valid object types purchasing the charge offer.
PCM_OP_CUST_POL_GET_PRODUCTS is not called by any opcode.
-
Use PCM_OP_CUST_POL_READ_PLAN to customize bundles during account creation. For a given package, this opcode constructs a tree of services, bundles, and charge offers associated with that package. This opcode retrieves account packages in addition to packages related to services.
PCM_OP_CUST_POL_READ_PLAN is not called by any opcode.
Getting a List of Bundles, Charge Offers, Discount Offers, and Services
To get the hierarchical relationships of bundles, charge offers, discount offers, and services associated with an account, use PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS.
By default, PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS does not return “item" or “canceled and deleted" charge offers and discount offers. Set PIN_FLD_FLAGS in the input flist to get item, canceled, and deleted charge offer and discount offer instances. For these records, the information about the charge offer and discount offer instances are retrieved from the /purchased_product and /purchased_discount purchase and cancellation event objects.
Note:
Item, canceled, and deleted charge offer and discount offer instances are not returned if the charge offer's or discount offer's event objects are not recorded or if they are purged. For example, if BRM is configured to not record events with no balance impacts, records for these events are not returned.
PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS gets the purchase, cycle, and usage validity periods for charge offers and discount offers from the account's /purchased_product and /purchased_discount objects. It returns this information in the purchase, cycle, and usage START_T and END_T fields located in the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays in the output flist. If a charge offer or discount offer is set to start on first usage and its validity period has not yet been initialized, additional information about the purchase, cycle, and usage start and end times is returned in START_DETAILS and END_DETAILS fields.
Getting a List of Packages and Bundles That an Account Owns
To get a list of the packages that an account owns, use PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS. This opcode retrieves a list of packages, bundles, or both that an account owns.
Note:
The opcode returns packages or bundles that an account owns. It does not return a package if the package has only optional bundles. The package must have at least one purchased bundle.
PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS takes an account POID from the input flist and returns a list of all packages, including balance group information and bundles the account owns.
If the account contains optional bundles that it does not own, those bundles are returned with the list as eligible to purchase (PIN_FLD_BOOLEAN value of 0).
PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS can perform additional filtering of packages or bundles before they are returned. For example, add filtering logic to this opcode to return only inactive optional bundles.
Packages and bundles that were closed during a transition are not added to the output flist.
Note:
An account owning more than one instance of a package is not supported. In this case, PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS returns bundles for one of the packages selected at random.
PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS returns bundles in a PIN_FLD_DEALS array, even if it found them listed in the account in the older PIN_FLD_DEAL_OBJ field.
PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS is not called by any opcode.
Reading Data for All Valid Purchased Charge Offers and Discount Offers
To get the purchased charge offers and discount offers data for accounts and services, use PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS.
The value of the PIN_FLD_SCOPE_OBJ field in the input flist restricts the results to an account, bill unit (/billinfo object), or service. This field is required and can specify one of these values:
-
An /account object: The opcode gets all the charge offers and discount offers for the account as well as its services.
-
A /billinfo object: The opcode gets the purchased charge offers and discount offers that contribute to the given bill unit.
-
A /service object: The opcode gets the purchased charge offers and discount offers that belong to the given service.
The opcode logic performs a search based on the scope object passed in the input flist. Most of the other parameters are filters that work on a particular scope. The input flist would look like this:
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 618010 0 0 PIN_FLD_SCOPE_OBJ POID [0] 0.0.0.1 /service/ip 615706 3 0 PIN_FLD_STATUS_FLAGS INT [0] 3 0 PIN_FLD_VALIDITY_FLAGS INT [0] 3 0 PIN_FLD_INCLUSION_FLAGSINT [0] 2 0 PIN_FLD_OVERRIDE_FLAGS INT [0] 2 0 PIN_FLD_END_T TSTAMP [0] (1154415600) Tue Aug 1 00:00:00 2006 0 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.1 /deal 615702 3 0 PIN_FLD_OVERRIDDEN_OBJ POID [0] 0.0.0.1 /purchased_product 324706 0 0 PIN_FLD_PACKAGE_ID INT [0] 23 0 PIN_FLD_PRODUCTS ARRAY [*] NULL array ptr 0 PIN_FLD_DISCOUNTS ARRAY [*] NULL array ptr
The opcode can accept filters to limit the search further. The input for the opcode contains parameters to retrieve the correct set of offerings:
-
To retrieve only charge offers or only discount offers, use the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays.
-
To retrieve only specific fields from the /purchased_product objects, specify the fields in the PRODUCTS and DISCOUNTS arrays.
-
To retrieve charge offers and discount offers with a specific status, pass the PIN_FLD_STATUS_FLAGS field and specify one of these values:
-
PIN_SUBS_FLG_OFFERING_STATUS_ACTIVE: This flag retrieves only active offerings.
-
PIN_SUBS_FLG_OFFERING_STATUS_INACTIVE: This flag retrieves only inactive offerings.
-
PIN_SUBS_FLG_OFFERING_STATUS_CLOSED: This flag retrieves only closed offerings.
Note:
Use of multiple values implies the target object should satisfy any of the above.
-
-
To retrieve charge offers or discount offers valid as of a given time, pass the PIN_FLD_END_T field in the input flist. You can base the end time on only the purchase, cycle, or usage period by including the PIN_FLD_VALIDITY_FLAGS field in the input flist with one or more of these values.
-
PIN_SUBS_FLG_OFFERING_VALIDITY_CYCLE: This flag tells the opcode to compare the END_T value passed to the CYCLE_END_T value.
-
PIN_SUBS_FLG_OFFERING_VALIDITY_PURCHASE: This flag tells the opcode to compare the END_T value passed with PURCHASE_END_T.
-
PIN_SUBS_FLG_OFFERING_VALIDITY_USAGE: This flag tells the opcode to compare the END_T value passed with USAGE_END_T.
Note:
Use of multiple flags implies the target object must satisfy all of the above conditions.
-
-
To retrieve all eligible offerings, which include account and subscription offerings, pass the PIN_FLD_INCLUSION_FLAGS field on the input flist with one or more of these values:
-
PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_PRODS: This flag retrieves all eligible charge offers.
-
PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_DISCS: This flag retrieves all eligible discount offers.
Note:
When this field is missing, only eligible offerings from a given scope are returned.
-
-
To retrieve only account charge offers and discount offers, pass the PIN_FLD_OVERRIDE_FLAGS field set to PIN_SUBS_FLG_OFFERING_ACCT_LEVEL_ONLY. This flag is valid for /account objects only.
-
To retrieve charge offers and discount offers for only a single package, pass the PIN_FLD_PACKAGE_ID field set to the package ID. This field can be used with any scope.
-
To retrieve charge offers and discount offers for a specific bundle, pass the PIN_FLD_DEAL_OBJ field set to the /deal object's POID.
PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS returns all purchased charge offers and discount offers, including canceled charge offers and discount offers, within the parameters used.
Finding Events Associated with Bundles, Charge Offers, Discount Offers, and Services
Use PCM_OP_SUBSCRIPTION_GET_HISTORY to retrieve the event history for a bundle, charge offer, discount offer, or service instance associated with an account.
This opcode retrieves events for a bundle, charge offer, discount offer, or service instance in a specified date range. Which events are returned depends on the category specified in the input flist:
-
If a bundle is specified, a history of all events associated with the specific bundle instance is returned for the account. The bundle is identified by the PIN_FLD_PACKAGE_ID field in the input flist.
-
If a charge offer is specified, a history of all events associated with the specific charge offer instance is returned for the account. The charge offer instance is identified by the PIN_FLD_OFFERING_OBJ field in the input flist.
-
If a discount offer is specified, a history of all events associated with the specific discount offer instance is returned for the account. The discount offer instance is identified by the PIN_FLD_OFFERING_OBJ field in the input flist.
-
If a service is specified, all events associated with that service object are returned for the account.
If you do not specify a date range, PCM_OP_SUBSCRIPTION_GET_HISTORY uses the account's creation time.
If a RESULTS array is passed in the input flist, PCM_OP_SUBSCRIPTION_GET_HISTORY returns only fields from the events that are passed in the RESULTS array.
Getting a Life-Cycle State
By default, after a balance is adjusted for a service that uses a custom life cycle, PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE triggers service state changes and then updates state expiration dates as follows:
-
Checks the SubscriberLifeCycle business parameter associated with a service's bill unit (/billinfo object):
-
If the parameter is set to disabled, returns the flow to the calling opcode.
-
If the parameter is set to enabled, continues the triggering process.
-
-
Gets the current life cycle state of the service from the PIN_FLD_LIFECYCLE_STATE field in the /service object.
If the service POID is not in the opcode's input flist, calls PCM_OP_SEARCH to find all the services associated with the balance group and the /account object. If any of the retrieved services are in the Recharge Only or Credit Expired state, changes their state to Active.
-
Calls PCM_OP_BAL_GET_BALANCES to get the sum of the balances in the service balance group.
-
Calls PCM_OP_CUST_UPDATE_SERVICES to do the following:
-
If the service state is Active and the balance group has reached its credit limit, change the state to Recharge Only.
-
If the service state is Recharge Only and the balance is replenished, change the state to Active.
-
If the service state is Credit Expired and the balance is replenished, change the state to Active and update the PIN_FLD_SERVICE_STATE_EXPIRATION_T value in the /service object as follows:
-
If a voucher is applied to the balance, compare the voucher's validity period with the Active state's expiration period (PIN_FLD_SERVICE_STATE_EXPIRATION_T field in the /config/lifecycle_states object associated with the service), and update the expiration time based on the greater of the two periods.
-
If a voucher is not applied, update the expiration time based on the Active state's expiration period.
-
-
If the service state is Preactive or Active and a voucher is used to increase the balance, compare the voucher's validity period with the current state's expiration period, and update the expiration time based on the greater of the two periods.
Note:
Oracle recommends that top-ups not be performed in the Preactive state.
-
By default, PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE supports the sample prepaid service life cycle. You can customize it to support other custom service life cycles.
PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE is called by PCM_OP_BAL_APPLY_MULTI_BAL_IMPACTS.
Applying Promotions for Special Dates, Events, or Actions
Use the PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT opcode to apply promotions to accounts based on special dates, specific events, or specific actions. For example, you could grant 100 free minutes to customers on their birthday or every time they successfully top up their account balance.
This opcode is called by the following:
-
The pin_apply_promotion utility to apply promotions to accounts based on special dates. See "pin_apply_promotion" in BRM Configuring Pipeline Rating and Discounting.
-
The event notification system when a triggering event occurs, such as when a customer purchases a new product. For information about the event notification system, see "Using Event Notification" in BRM Developer's Guide.
PCM_OP_SUBSCRIPTION_HANDLE_PROMO_EVENT performs these operations:
-
Checks the /config/event_promo_tag_map object to see whether the promotion tag (PIN_FLD_PROMO_TAG) is mapped to a promotion event (PIN_FLD_PROMO_EVENT_TYPE).
-
Checks the /config/event_promo_map object to see whether the event type (PIN_FLD_EVENT_TYPE) is mapped to a promotion event (PIN_FLD_PROMO_EVENT_TYPE).
-
Adds information about the promotion event to the input flist of the PCM_OP_ACT_USAGE opcode.
-
Calls the PCM_OP_SUBSCRIPTION_POL_PRE_PROMO_EVENT policy opcode to customize the input flist for the PCM_OP_ACT_USAGE opcode. By default, the policy opcode does nothing.
-
Calls the PCM_OP_ACT_USAGE opcode to rate the promotion event. To do so, it calls the following opcodes:
-
PCM_OP_RATE_POL_PRE_RATING. See "Modifying Rated Events".
-
PCM_OP_RATE_EVENT. See "Subscription Rating Opcodes".
-
PCM_OP_RATE_POL_POST_RATING. See "Modifying Rated Events".
-
-
Calls the PCM_OP_SUBSCRIPTION_POL_POST_PROMO_EVENT policy opcode to customize the output flist from the PCM_OP_ACT_USAGE opcode. By default, the policy opcode does nothing.
Customizing Special Date, Event, or Action Promotions
To customize how promotions are applied, use the following policy opcodes:
-
PCM_OP_SUBSCRIPTION_POL_PRE_PROMO_EVENT: Customizes the input flist to PCM_OP_ACT_USAGE.
By default, this opcode is an empty hook, but you can customize it to add or remove input flist fields.
-
PCM_OP_SUBSCRIPTION_POL_POST_PROMO_EVENT: Customizes the output flist from PCM_OP_ACT_USAGE.
By default, this opcode is an empty hook, but you can customize it to add or remove output flist fields.
Managing Promotions with Siebel CRM
To add, modify, inactivate, or cancel promotions, you must customize Siebel CRM to accept the following information and pass it to PCM_OP_SUBSCRIPTION_SET_BUNDLE:
-
Promotion name
-
Promotion description
-
Charge offers and discount offers bundled with the promotion
-
Promotion creation date
-
Promotion validity dates
-
Promotion status: active, inactive, or canceled
In an AIA system, you pass this information from Siebel CRM to BRM through the J2EE Connector Architecture (JCA) Resource Adapter, which exposes the BRM API through a JCA common client interface (CCI) as an Interaction. Data required for sending data to PCM_OP_SUBSCRIPTION_SET_BUNDLE is detailed in the Subscription Web service.
To implement the ability to display Siebel CRM promotions on invoices, add the following functionality to Siebel CRM by using PCM_OP_SUBSCRIPTION_SET_BUNDLE:
-
Create /purchased_bundle objects. See "Adding a promotion to an account".
-
Modify /purchased_bundle objects. See "Modifying an account's promotion".
-
Inactivate /purchased_bundle objects. See "Inactivating an account's promotion".
-
Cancel /purchased_bundle objects. See "Canceling an account's promotion".
Adding a promotion to an account
To add a promotion to a customer's account, pass in details about the promotion to PCM_OP_SUBSCRIPTION_SET_BUNDLE. You must also set the following fields in the opcode's input flist:
-
In the PIN_FLD_BUNDLE_INFO array:
-
Set the PIN_FLD_POID field to a type-only POID for /purchased_bundle.
-
Set the PIN_FLD_STATUS field to 1 to set the promotion's status to Active.
Note:
If PIN_FLD_STATUS is not passed in, the promotion's status is set to active by default.
-
-
In the PIN_FLD_OFFERINGS array, specify the charge offers and discount offers associated with the promotion. You must create a separate array for each charge offer and discount offer in the promotion. In the PIN_FLD_OFFERINGS array:
-
Set the PIN_FLD_POID field to the POID of the /purchased_product or /purchased_discount object.
-
Set the PIN_FLD_BUNDLE_OBJ field to NULL.
-
Set the PIN_FLD_BUNDLE_INFO array to the rec_id of the PIN_FLD_BUNDLE_INFO array at the 0th level of the flist. This specifies to associate the newly created /purchased_bundle object with the specified charge offer or discount offer during account creation.
-
Modifying an account's promotion
To modify an account's existing promotion, pass in the promotion details that changed to PCM_OP_SUBSCRIPTION_SET_BUNDLE:
-
To change a promotion's attributes: In the PIN_FLD_BUNDLE_INFO array, set the PIN_FLD_POID field to the existing /purchased_bundle POID and then pass in only the fields that have changed.
-
To transfer a promotion from one account to another: In the PIN_FLD_BUNDLE_INFO array, set the PIN_FLD_POID field to the existing /purchased_bundle POID and set the PIN_FLD_ACCOUNT_OBJ field to the new /account POID.
-
To add charge offers and discount offers to a promotion: In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the charge offer or discount offer being added to the promotion, and set the PIN_FLD_BUNDLE_OBJ field to the complete POID of the /purchased_bundle object.
-
To remove an existing charge offer or discount offer from a promotion: In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the charge offer or discount offer being removed from the promotion, and set the PIN_FLD_BUNDLE_OBJ field to NULL.
When a promotion is modified, the opcode does the following:
-
Changes the specified /purchased_bundle object.
-
Changes the PIN_FLD_PLAN_OBJ field of the /purchased_product or /purchased_discount object, if a charge offer or discount offer changed.
-
Generates an /event/billing/bundle/modify object for auditing purposes, if a promotion's attributes changed.
Inactivating an account's promotion
When you inactivate an account's promotion, PCM_OP_SUBSCRIPTION_SET_BUNDLE sets the promotion's status to Inactive. It does not update the associated charge offer or discount offer's PIN_FLD_PLAN_OBJ field. Also, unlike the canceled status, a promotion's details can be modified after it has been inactivated.
To inactivate a promotion, pass in details about the promotion to PCM_OP_SUBSCRIPTION_SET_BUNDLE and set the PIN_FLD_STATUS field in the PIN_FLD_BUNDLE_INFO array to 2.
Canceling an account's promotion
You can no longer make changes to an account's promotion after it has been canceled. When you cancel an account's promotion, PCM_OP_SUBSCRIPTION_SET_BUNDLE:
-
Sets the promotion's validity end date to the current date.
-
Sets the promotion's status to canceled.
Optionally, the opcode can disassociate the charge offers and discount offers from the promotion by changing the PIN_FLD_PLAN_OBJ field of the /purchased_product object and the /purchased_discount object to NULL.
To cancel an account's promotion, call PCM_OP_SUBSCRIPTION_SET_BUNDLE and set the PIN_FLD_STATUS field in the PIN_FLD_BUNDLE_INFO array to 3.
To configure the opcode to disassociate the charge offers and discount offers from the promotion, perform one of the following tasks:
-
Set the PIN_FLD_FLAGS field to 1. When set, the opcode searches for and disassociates the account's charge offers and discount offers from the promotion. This option decreases processing performance.
-
In the PIN_FLD_OFFERINGS array, set the PIN_FLD_POID field to the complete POID of the charge offer or discount offer being canceled, and set the PIN_FLD_BUNDLE_OBJ field to NULL. When set, the opcode disassociates the specified charge offers and discount offers from the promotion.
Note:
To improve processing performance, pass in all charge offers and discount offers associated with the canceled promotion.
Managing Provisioning
See the following topics:
-
Customizing Provisioning When Canceling a Charge Offer
Note:
The BRM provisioning tag framework is the preferred method of customizing provisioning when a charge offer is purchased or canceled.
When defining a configuration for the provisioning tag framework, you specify one or more opcodes to perform an action, such as creating an ERA. You can specify that an opcode run when a charge offer or discount is purchased, canceled, or both. You can use an existing opcode or design a custom opcode.
If the provisioning tag is designed to create an ERA, you can specify that PCM_OP_SUBSCRIPTION_PROVISION_ERA run at both purchase and cancellation time. This opcode creates, modifies, or deletes a profile (/profile object). ERAs are stored in profiles.
PCM_OP_SUBSCRIPTION_PROVISION_ERA creates, modifies, or deletes /profile objects. When specified in a /config/provisioning_tag object, this opcode runs when a charge offer or discount offer containing the provisioning tag is purchased or canceled. Profiles can store extended rating attributes (ERAs) and other custom attributes.
PCM_OP_SUBSCRIPTION_PROVISION_ERA calls PCM_OP_CUST_CREATE_PROFILE, PCM_OP_CUST_MODIFY_PROFILE, or PCM_OP_CUST_DELETE_PROFILE, depending on the action it must take.
When creating a profile, PCM_OP_SUBSCRIPTION_PROVISION_ERA creates a /profile/acct_extrating object for an account profile and a /profile/serv_extrating object for a service profile.
Customizing Provisioning When a Charge Offer Is Purchased
To set fields in a /service object at the time of purchase, use PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING.
This opcode is called by PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT when a charge offer is purchased.
Note:
Do not call PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING directly.
-
If a /service object is associated with a provisioning tag in the input flist, provisioning is invoked.
-
If provisioning is invoked, it checks the tag table for the corresponding provisioning tag and runs the corresponding function call that modifies the appropriate fields in the /service object.
You can customize the provisioning functionality as follows:
-
Change the services, tags, and functions in the provisioning_tags array.
-
Add to or modify the provisioning subfunctions in the fm_subscription_pol_provisioning.c file.
-
Use PDC or Pricing Center to modify charge offers associated with services by including the applicable provisioning tag.
The BRM provisioning tag framework is the preferred method of customizing provisioning when a charge offer is purchased.
Getting a List of Provisioning Tags
To customize charge offer provisioning, use PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS. This opcode retrieves data for provisioning from the provisioning_tags array.
This opcode is called by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT when a charge offer is canceled.
Note:
Do not call PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS directly.
Each service in the provisioning_tags array is associated with a provisioning tag and a function. The provisioning tag specifies the type of service, and the function determines what is to be done with that service.
You can customize the provisioning functionality as follows:
-
Change the services, tags, and functions in the provisioning_tags array.
-
Add to or modify the provisioning subfunctions in the fm_subscription_pol_provisioning.c file.
-
Use PDC or Pricing Center to modify charge offers associated with services by including the applicable provisioning tag.
Customizing Provisioning When Canceling a Charge Offer
To customize provisioning when canceling a charge offer, use PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING. This opcode clears fields in a /service object at the time of cancellation.
The BRM provisioning tag framework is the preferred method of customizing provisioning when a charge offer is canceled.
PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING is called by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT when a charge offer is canceled.
Note:
Do not call PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING directly.
-
If a /service object is associated with a provisioning tag in the input flist, provisioning is invoked.
-
If provisioning is invoked, it checks the tag table for the corresponding provisioning tag and runs the corresponding function call that clears the appropriate fields in the /service object.
Managing GSM Service Provisioning
Use the following opcodes to manage provisioning:
-
To publish a service order, use PCM_OP_PROV_PUBLISH_SVC_ORDER. This opcode sends an /event/provisioning/service_order/eventtype event to the Provisioning Data Manager (DM), where eventtype is the type of event.
PCM_OP_PROV_PUBLISH_SVC_ORDER takes as input the POID of the service order event and a substruct containing the service order information that should be sent to the Provisioning DM.
-
To update a service order, use PCM_OP_PROV_UPDATE_SVC_ORDER. This opcode updates the status of an /event/provisioning/service_order/* event.
The /event/provisioning/service_order/* event stores the service order and information such as the status, service order type, and actions required.
The PCM_OP_PROV_UPDATE_SVC_ORDER input flist includes the complete response from the provisioning applications, including the POID of the service order, the service order status, and other service order information. Based on the type of the service order, you can modify or validate the response flist.
When a response is received from a provisioning platform, PCM_OP_PROV_UPDATE_SVC_ORDER uses information in the input flist to update the status of an /event/provisioning/service_order/* event.
-
To validate and modify parameters for updating service orders, use PCM_OP_PROV_POL_UPDATE_SVC_ORDER.
This opcode is called by PCM_OP_PROV_UPDATE_SVC_ORDER when a response is received from a provisioning system.
By default, PCM_OP_PROV_POL_UPDATE_SVC_ORDER validates and transforms a global system for mobile communications (GSM) service order. When a response is received from a provisioning system, this opcode maps the response parameters to corresponding fields in the /event/provisioning/service_order/telco/gsm object.
The input flist to PCM_OP_PROV_POL_UPDATE_SVC_ORDER includes the complete response from the provisioning applications. Based on the type of the service order, you can modify or validate the response flist.
By default, PCM_OP_PROV_POL_UPDATE_SVC_ORDER returns the input flist without any change, except in the case of GSM services where the input flist is validated and the format is modified to map the fields in the event/provisioning/service_order/telco/gsm object.
Validating Product Specification Attributes for Pricing Components
To validate product specification attributes defined on pricing components, use PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING.
By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes.
PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING is called by the following opcodes:
- PCM_OP_SUBSCRIPTION_PURCHASE_DEAL
- PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT
- PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT
- PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE
- PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY
See BRM Developer's Guide for information about customizing opcodes.