11 Managing Customers' Services and Products

This chapter describes how to manage customers' services and products; for example, adding Oracle Communications Billing and Revenue Management (BRM) services, giving discounts, and transitioning deals and plans.

For more information on creating products, deals, and plans, see "About Creating a Price List" in BRM Setting Up Pricing and Rating.

For more information on creating services, see "Adding Support for a New Service" in BRM Developer's Guide.

Displaying Deal, Product, and Service Information

You can display status, discounts, purchase dates, and a history of events such as balance impacts.

You use Customer Center to display deal, product, and service information.

Managing Services

A service is a capability that you provide to customers, such as telephony, Internet access, or email.

You add services to an account by purchasing plans and deals.

You can also change the service status and change how the services are provisioned; for example, add mail boxes to an email account.

About BRM Service Names

BRM supports your services by using service subclasses. The service names that appear in Customer Center and Pricing Center use the names of the service subclasses; for example, /service/ip as show in Figure 11-1.

Figure 11-1 Service Subclass Name Example

Description of ''Figure 11-1 Service Subclass Name Example''

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 you installed the BRM software.) This entry determines whether the deal associated with a service is required or optional.

• If the deal is required, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_REQUIRED.

• If the deal is optional, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_OPTIONAL.

When the PCM_OP_CUST_CREATE_CUSTOMER opcode creates the services in an account, it first validates whether the deal 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

You cannot set the status of a required service to Closed by using Customer Center. Instead, you must call the PCM_OP_CUST_UPDATE_SERVICES opcode, which in turn calls PCM_OP_CUST_SET_STATUS opcode. 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 plan.

Note:

• You cannot activate an optional service that has been closed if the required service is closed.

• When you transition a deal or plan in Customer Center, the service associated with the old deal 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.

For more information, see "Defining Deal Dependencies".

Adding Services to an Account

To add services, customers must purchase a deal or a plan. Purchasing a deal adds the deal to an existing service in the account, whereas purchasing a plan adds the plan and a new service to the account.

Plans are typically in the default-addon plan list.

Customer service representatives (CSRs) can add services to customer accounts by using Customer Center.

Also, customers can add services themselves by using your customized Web pages.

Activating and Inactivating Services

You change the customer's service status by using the Service tab in Customer Center. You can backdate service status changes to a date earlier than the current date. You can specify a date in the future on which the service status will change.

The status can be active, inactive, or closed.

• When a service is active, the customer can use the service.

• When a service is closed or inactive, the customer cannot use the service.

You can specify a date in the future on which the service status will change.

For more information on changing account and service status, see "Changing Account and Service Status".

You can edit the list of reasons why a service was activated or inactivated. See "Customizing the List of Reasons for Account Changes".

Changing How Services Function

You use the service tabs in Customer Center to change how a service works. For example:

• Specify an IP address for a customer.

• Enter IP telephony speed-dial settings.

You use Customer Center to change service details.

Controlling Service Usage

You control service usage in the following ways:

• Specifying how to authorize service usage. By default, a customer is not authorized to use a service if a credit limit has been reached.

• Inactivating services. When a service is inactivated, the customer cannot use it.

• Inactivating accounts. When an account is inactivated, no services in the customer's account can be used by the customer.

• Canceling products. When an account's product is canceled, the associated service cannot be used.

For more information on setting the account status, see "Changing Account and Service Status".

In addition to capturing usage information, BRM can also send information to the system that controls the service. For example, BRM can notify an IP gateway that a customer's credit limit has been reached and the call should be terminated.

Managing GSM Service Provisioning

Use the following opcodes to manage provisioning:

• To publish a service order, use the PCM_OP_PROV_PUBLISH_SVC_ORDER opcode. This opcode sends an /event/provisioning/service_order/eventtype event to the Provisioning Data Manager (DM), where eventtype is the type of event.

  This opcode takes as input the Portal object ID (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 the PCM_OP_PROV_UPDATE_SVC_ORDER opcode. This opcode updates the status of an /event/provisioning/service_order/* event.

  An /event/provisioning/service_order/* event stores the service order and information such as the status, service order type, and actions required.

  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.

  PCM_OP_PROV_UPDATE_SVC_ORDER receives as input the POID of the service order, the service order status, and other service order information.

• To validate and modify parameters for updating service orders, use the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode.

  This policy opcode is called by PCM_OP_PROV_UPDATE_SVC_ORDER when a response is received from a provisioning system.

  By default, the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode validates and transforms a global system for mobile communications (GSM) service order. When a response is received from a provisioning system, this policy opcode maps the response parameters to corresponding fields in the /event/provisioning/service_order/telco/gsm object.

  The input flist to the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode 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, the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode 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.

Managing Products

A product is a pricing object that defines how to charge your customer for goods and services. A product consists of one or more rate plans that specify the cost of each billable event that affects a customer's account.

You use Customer Center to display each product that the account owns and the basic information about each product, including the product's service, purchase date, and status.

Purchasing Products

Although you can manage products individually, you do not purchase individual products for a customer; instead, you purchase a deal in Customer Center that contains the product. See "Purchasing Deals".

Functionally speaking, the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode calls the PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT opcode to purchase the products a deal contains.

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 absolute 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 more information on setting purchase, cycle, and usage start and end times, see "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts".

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.

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 product 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 product to start relative to the purchase date, and you set the relative period in the pricing plan to one accounting cycle. If the account creation day is January 5, the billing day of month is 5, and the deal 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.

  Note:

  If the purchase, cycle, or usage start and end time is modified in Customer Center while purchasing the deal or creating the account, any delay specified in Pricing Center is ignored.

Applying Purchase and Cycle Fees to the Balance

PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT handles the purchase and cycle fees for the product 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 Product Purchase Fees".

• If the product 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 product are stored in /event/billing/product/fee/purchase object.

• If the product 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 product is purchased as part of a deal transition, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT can waive the purchase fees based on the PIN_FLD_FLAGS value passed in by the PCM_OP_SUBSCRIPTION_TRANSITION_DEAL opcode. For more information, see "How Deals Are Transitioned".

• When PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT is called during product customization, the value of PIN_FLD_FEE_FLAG in the input flist determines whether cycle and purchase fees are applied:

  • Cycle and purchase fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_FALSE, cycle and purchase fees are not applied.

  • Purchase fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_TRUE, the opcode applies purchase fees. The opcode uses the purchase fee of the product (base or customized) that is valid at purchase time. Purchase fees are not applied for customized products created after the initial product purchase.

  • Cycle fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_TRUE, the opcode calls the appropriate opcode to calculate and apply cycle fees. Cycle fees are applied based on the validity of the base and customized products. See "Validity Periods and Cycle Fees for Customized Products".

  PCM_OP_SUBSCRIPTION_PURCHASE_DEAL sets the value of PIN_FLD_FEE_FLAG during deal purchase. See "How Deals Are Purchased".

Applying Deferred Product Purchase Fees

To apply deferred purchase fees, use the PCM_OP_SUBSCRIPTION_PURCHASE_FEES opcode.

By default, purchase fees are applied at the time of product purchase. However, you can defer the purchase fees to a later date. For example, a customer can sign up for a product that is not available until a later date. The product's purchase fees are deferred and applied when the product 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 products with an expired purchase start time.

Note:

For item products, 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.

Enabling Product Purchases from Closed or Inactive Accounts

By default, closed and inactive accounts cannot purchase products. You may, however, want to make such purchases possible.

For example, you may want CSRs to create accounts that are closed, then purchase products for the account. This allows the customer to verify that the product is correct before charging the account. When the account is made active, the customer is charged.

When you purchase a product for inactive or closed accounts, the product's status also needs to be inactive. If the product's status is active, rating modules rate and apply charges for the product. If you do not want charges to be applied, change the product's status to inactive at the time of purchase or use Pricing Center to set the product's status to inactive in the deal. When the account is activated, change the product's status to active for charges to be applied.

To enable product purchases from closed or inactive accounts:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

2. In the fm_bill section, add the following entry:

   fm_bill deal_purchase_for_closed_account

3. Set the value of the entry to 1.

4. Save and close the file.

5. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

How Products Are Purchased

To purchase a product, use PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT.

Important:

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 products for the account or service object specified in the input flist.

Note:

• If a /service object is specified, the product is purchased for that service and is a service-level product. The /service object must belong to the account.

• If the /service object is NULL, the product is purchased for the /account object and is an account-level deal.

PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT performs these operations:

1. If billing is due, triggers billing.

2. Opens a transaction.

3. Retrieves the product's package ID, name, and type, which are passed in the input flist, and opens a deal instance. For more information on how a deal is generated, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.

4. Validates that the product is available for purchase. A product is not available for purchase when any of the following apply:

   • The product's validity period has not yet started (the PURCHASE_START_T value is greater than the current time).

   • The product'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 product 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 price list.

   • The purchase quantity is greater than the maximum purchase quantity set in your price list.

   • An attempt is made to purchase a partial quantity.

   • The total quantity purchased for this product exceeds the maximum ownership quantity in your price list for this account or service. This applies only to subscription products that have a maximum ownership quantity specified.

   • The total quantity purchased for this product is less than the minimum ownership quantity in your price list for this account or service. This applies only to subscription products that have a minimum ownership quantity specified.

5. If the product purchase is backdated, validates that:

   • The date to which the product purchase is backdated is not prior to the G/L posting date.

   • The date to which the product purchase is backdated is not prior to the effective date of the account or service.

   • The date to which the product purchase is backdated is not prior to the date of the last status change of the account or service.

   See "About Backdated Product, Discount, Deal, or Plan Purchase".

6. If the purchase product provisioning tag is set for the product, calls the PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING opcode. See "Customizing Provisioning When a Product Is Purchased".

   If a /config/provisioning_tag object is associated with the product, this opcode runs the opcodes specified in that object to run at product purchase time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.

7. If the product is sponsored, sets PIN_FLD_SPONSOR_OBJ accordingly.

8. If the opcode is called for a customized product, adds the POID of the base product's /purchased_product object to the PIN_FLD_OVERRIDDEN_OBJ field.

9. Determines the various start and end dates for the product. See "Handling Purchase, Cycle, and Usage Start and End Times".

10. If called during advanced customization, verifies that the validity period of the customized product falls within the validity period of the base product:

    • The purchase start and end times of the customized product must fall within the purchase start and end times of the base product.

    • The purchase start and end times must not overlap with the purchase start and end times of any other customized product for the same base product.

    • The usage start and end times of the customized product must fall within the usage start and end times of the base product.

    • The cycle start and end times of the customized product must fall within the cycle start and end times of the base product.

11. Verifies the product purchase with the specified account.

12. Applies the product to the account:

    • If it is a subscription product, generates a /purchased_product object with a pointer to the /account object.

    • If it is an item product, creates an audit record for the /au_purchased_product object.

      Note:

      Item products cannot be deferred. The audit object is used for rerating events.

13. Sets the purchase, cycle, and usage discounts, if applicable.

14. Sets the product status in /purchased_product.

15. Checks the PIN_FLD_FLAGS value set by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL to determine whether the product purchase is due to a deal or plan transition. If so, sets the value to PIN_TRANS_WAIVE_PURCHASE_FEES.

16. Applies the appropriate purchase and cycle fees to the balance. See "Applying Purchase and Cycle Fees to the Balance".

17. Updates the product flags for applying purchase and cycle fees.

18. Creates the audit log event object (/event/billing/product/action/purchase) after the product is added to the account and all applicable fees are applied.

19. Closes the transaction.

If the product purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT returns a confirmation message.

During a deal or plan transition, additional validations are performed that may prevent a successful purchase:

• If the service contains at least one required deal, the service flag is set to Required. If all deals 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 deals are mutually exclusive before PCM_OP_SUBSCRIPTION_PURCHASE_DEAL is called.

• If the permitted field in the plan is service_type, the flag is set to PBS.

Improving Product Purchase Performance

During product purchase, BRM retrieves product details from the rating cache by reading rate plans. However, reading a large number of rate plans for retrieving product details can consume a lot of time. This slows down product purchase.

You can improve the product purchase performance by enabling the retrieval of product details from the BRM database. For more information, see "Improving Performance in Retrieving Purchased Offerings for a Bill Unit" in BRM System Administrator's Guide.

Modifying Products

You use Customer Center to modify products in the following ways:

• Delay purchase fees.

• Add a comment.

• Change the quantity.

You can also customize the pricing of a product. See "Customizing Product Pricing".

You can modify products at the following times:

• During account creation.

• When adding a deal.

• During account maintenance.

Changing Product Status

When creating an account or adding a deal, you can change the status of each product. For example, if using the product requires hardware setup, you can inactivate the product until setup is complete. You can then activate the product by using Customer Center. The customer is not billed for the product while it is inactivated.

Note:

You cannot inactivate a product after it has been purchased. However, you can inactivate a service. See "Activating and Inactivating Services".

Changing Product Quantity

You can change the quantity of a product, most often when it represents a one-time purchase and has no usage fees; for example, a product that gives five free hours as a sign-up bonus.

If the product's minimum quantity allows it, you can also decrease a product's quantity.

Applying discounts when you change product quantity

If you increase the quantity of a product that has a discount on purchase fees, that discount is applied to the entire purchase rather than to each unit of the product that is added to the account. For example, if you increase the quantity of a product in an account from one to five and the discount on purchase fees is $5, the customer receives a discount of $5, not $20.

Setting Start and End Dates

You can set the start and end dates for the purchase, cycle forward fees, and usage rates. The start date sets the date when the customer's balance begins to be affected by the rate. The end date is the first date when the rate is no longer valid. In Figure 11-2, the last day that the rate is valid is November 3, 2006.

Figure 11-2 Setting Start and End Dates

Description of ''Figure 11-2 Setting Start and End Dates''

You might want to delay a product purchase if the product depends on additional software or hardware setup that the customer has to wait for.

Changing the Purchase, Usage, and Cycle Start and End Times

The PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode is called to change the purchase, cycle, or usage start and end times of an account's purchased product. This opcode is called by the PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS opcode when the status of an account's product is changed.

After a product is purchased and its start and end dates have been set, you can change the start time to specify only another absolute date, and you can change the end time to specify only another absolute date or to end never.

Note:

If a product has been tailored to include one or more advanced customizations, be sure to consider the validity periods of the base product and all customized products when changing a validity period: The validity period of customized products must fall within the validity period of the base product, and customized products in the same deal cannot have overlapping validity periods. If these rules are not followed, PCM_OP_SUBSCRIPTION_SET_PRODINFO will not commit the product to the database.

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 an absolute date, PCM_OP_SUBSCRIPTION_SET_PRODINFO generates an event that causes Pipeline Manager to update the validity period in the pipeline database.

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.

BRM does not allow you to change a product's purchase, usage, and cycle start and end dates as follows:

• The product purchase start date if the purchase start date has elapsed.

  For example, on January 1, a product 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 product cycle start date if the cycle fees have been applied.

• The product purchase, usage, and cycle end date prior to the respective purchase start date.

• The product purchase, usage, cycle start or end dates prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".

See "About Backdated Purchase, Usage, or Cycle End Dates".

Calculating the Cycle Forward Fee

If you modify the cycle start time or cycle end time for the product in the middle of a cycle, PCM_OP_SUBSCRIPTION_SET_PRODINFO calculates the cycle forward fee or cycle arrears fee for the product.

If the product has a cycle forward fee, the PCM_OP_SUBSCRIPTION_CYCLE_FORWARD opcode 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 product in the middle of a cycle, PCM_OP_SUBSCRIPTION_SET_PRODINFO calculates the cycle forward fee or cycle arrears fee for the product.

Caution:

• 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 Product Limitations".

If the product has a cycle arrears fee, the PCM_OP_SUBSCRIPTION_CYCLE_ARREARS opcode 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 Product 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 plan:

    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.

How Products Are Modified

To modify a product owned by a customer, use PCM_OP_SUBSCRIPTION_SET_PRODINFO.

PCM_OP_SUBSCRIPTION_SET_PRODINFO performs these operations:

1. If billing is due, triggers billing.

2. Opens a transaction.

3. Verifies the validity periods of customized products. See "About Customized Product Validity".

4. For backdating operations, validates and sets the product's purchase, cycle, or usage start and end dates to a backdated date. See "About Backdated Purchase, Usage, or Cycle End Dates".

5. Modifies the product information as specified. For more information on how PCM_OP_SUBSCRIPTION_SET_PRODINFO handles start and end dates, see "Changing the Purchase, Usage, and Cycle Start and End Times".

6. Creates an audit record object (/au_purchased_product) used for rerating events.

7. Applies the product changes to the product object (/purchased_product) owned by the account.

8. 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".

9. Creates the /event/billing/product/action/modify event objects.

10. 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.

Managing Product Provisioning

To manage product provisioning, use the following provisioning policy opcodes:

• PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING. See "Customizing Provisioning When a Product Is Purchased".

• PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS. See "Getting a List of Provisioning Tags".

• PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING. See "Customizing Provisioning When Canceling a Product".

  Note:

  The BRM provisioning tag framework is the preferred method of customizing provisioning when a product is purchased or canceled. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.

Customizing Provisioning When a Product Is Purchased

To set fields in a /service object at the time of purchase, use the PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING policy opcode.

This policy opcode is called by PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT when a product is purchased.

Important:

Do not call this opcode 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 executes the corresponding function call that modifies the appropriate fields in the /service object.

You can customize the provisioning functionality by:

• Changing the services, tags, and functions in the provisioning_tags array.

• Adding to or modifying the provisioning sub-functions in the fm_subscription_pol_provisioning.c file.

• Using Pricing Center to modify products associated with services by including the applicable provisioning tag.

Getting a List of Provisioning Tags

To customize product provisioning, use the PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS policy opcode. This policy opcode retrieves data for provisioning from the provisioning_tags array.

This policy opcode is called by the PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT opcode when a product is canceled.

Important:

Do not call this opcode 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. For example, the PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS policy opcode is called by Pricing Center to access the tag table and display the list of service types and their corresponding provisioning tags.

You can customize the provisioning functionality by:

• Changing the services, tags, and functions in the provisioning_tags array.

• Adding to or modifying the provisioning sub-functions in the fm_subscription_pol_provisioning.c file.

• Using Pricing Center to modify products associated with services by including the applicable provisioning tag.

Customizing Provisioning When Canceling a Product

To customize provisioning when canceling a product, use the PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING policy opcode. This policy opcode clears fields in a /service object at the time of cancellation.

This policy opcode is called by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT when a product is canceled.

Important:

Do not call this opcode 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 executes the corresponding function call that clears the appropriate fields in the /service object.

Upgrading Products

You can upgrade a customer's product by canceling the existing product and adding the upgraded product. For example, a customer can upgrade from a limited number of hours of Internet access to unlimited access.

Tip:

If your price list includes an upgrade path from limited hours to unlimited hours, you should include a rate plan in the upgrade product that removes free hours. That way, when a customer upgrades from limited hours to unlimited hours, the balance no longer includes free hours.

You can also upgrade products by including them in deals that you transition. For more information, see "Transitioning Deals".

Canceling Products

You can cancel a customer's products by using the Plans tab Actions menu in Customer Center. You can cancel individual products or cancel all products in a deal at one time by canceling the deal; for example, to upgrade a customer to a new plan or service. See "Canceling Deals".

You can cancel a product immediately or backdate the cancellation to a date earlier than the current date. You can also set the cancellation to a future date. See "Setting Start and End Dates".

You can charge for product cancellations by creating a cancel rate for the product.

See "How BRM Cancels Base and Customized Products" for more information on canceling products that have been customized.

Note:

• In Customer Center, canceled products do not show up in the Product table by default. To display them, choose Actions - Customize Product Table on the Product tab.

• In the case of deferred product cancellation, the cancellation is applied when the pin_bill_day billing script is run.

• If the product is contained in a required deal, you must either transition the plan containing the required deal or close the service to cancel the product. See "About Plan Transitions in BRM".

About Cycle Forward Fees and Product Cancellation

If a product's cycle forward fee allows proration, the customer is credited for any cycle forward fees that have been charged for but not used. BRM makes refunds based on the price list in effect at the time the product was purchased.

About Free Resources and Product Cancellation

Typically, canceling a product does not remove free hours or minutes from a customer's balance. Upgrading a product typically does not remove them either. If a customer uses up more than the allowed free resources before canceling a product in the middle of a billing cycle, you can charge for the overuse of free resources. For more information, see "Charging for Overuse of Free Resources during Product Cancellation".

Canceling Products by Closing the Account

When you close an account, all of the products it owns are canceled. See "About Activating, Inactivating, and Closing Accounts".

Canceling Products without Charging a Cancel Fee

You can specify the amount of time after a purchase that a product can be canceled without charging the customer. For example, you might want to specify a product cancel tolerance of 30 minutes in case a CSR assigns the wrong product to an account and needs to cancel it without charging the customer.

To specify a cancellation tolerance:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

2. Change the value of the cancel_tolerance entry.

   • 0 (Default) to always charge.

   • Any other value entered in cancel_tolerance is in minutes.

   For example (15 minutes):

   - fm_bill cancel_tolerance 15
     
   

3. Save and close the file.

4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Canceling a Product

You can cancel a product immediately or backdate the cancellation to a date earlier than the current date. You can also cancel a product in the future by modifying the product end times. You use Customer Center to cancel products.

Note:

Deferred cancellation is available only for the entire quantity of the product in the account.

Including Event Adjustments in Product Cancellation Refunds

By default, when a product is canceled, BRM does not apply event adjustments when calculating the refund amount.

Note:

You must install BRM 7.5 Patch Set 1 or later to use this business parameter.

To configure BRM to include event adjustments in product cancellation refunds, modify the EventAdjustmentsDuringCancellation parameter in the subscription instance of the /config/business_params object:

• When this parameter is enabled (1), BRM searches for any event adjustments associated with the product cycle fee and applies them to the refund amount.

• When this parameter is disabled (0), BRM does not include event adjustments when calculating product cancellation refunds.

To include event adjustments in product cancellation refunds:

1. Use the following command to create an editable XML file from the subscription instance of the /config/business_params object:

   pin_bus_params -r BusParamsSubscription bus_params_subscription.xml 
     
   

   This command creates the XML file named bus_params_subscription.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

2. Search the XML file for following line:

   <EventAdjustmentsDuringCancellation>0</EventAdjustmentsDuringCancellation>
     
   

3. Change 0 to 1.

   Caution:

   BRM uses the XML in this file to overwrite the existing subscription instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM billing configuration.

4. Save and close the file.

5. Use the following command to load the change into the /config/business_params object:

   pin_bus_params bus_params_subscription.xml 
     
   

   Execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

6. Read the object with the testnap utility or Object Browser to verify that all fields are correct.

   See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for more information on how to use Object Browser.

7. Stop and restart the CM.

8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Charging for Overuse of Free Resources during Product Cancellation

When a customer cancels a product in the middle of a billing cycle, you can prorate free resources and charge for overuse. To prorate free resources, you set up the cycle grant rate plan and prorate the grant on cancellation. Then, you convert the non-currency resource balance to a currency resource balance by configuring a fold rate plan.

For more information on rate plans, proration, and fold events, see the following topics:

• "About Real-Time Rate Plans" in BRM Setting Up Pricing and Rating

• "About Proration" in BRM Configuring and Running Billing

• "About Fold Events" in BRM Setting Up Pricing and Rating

For example, consider a product that grants 400 free minutes for a cycle starting on January 1 and ending on January 30. Each free minute equals one currency resource unit. On January 15, if the customer cancels the product after using 300 free minutes, the free minutes grant is prorated to 200 and the overuse of 100 free minutes is charged to the customer's account by folding 100 free minutes to 100 currency resource units.

Important:

You can prorate free resources by using folds only if the relationship between the currency resource and the free resource is fixed. For example, one free minute equals one currency unit. It does not work if the conversion between the resources is based on tiered rates; for example, different rates for peak time and non-peak time.

Setting up products to charge for overuse of free resources

Use Pricing Center to perform these tasks:

1. Create a product for the free resource you want to offer to your customers. For example, free minutes.

2. Define a cycle forward rate plan that adds free resources to the product in every cycle.

   Important:

   To rate overuse of the free resource, make sure the credit limit of the free resource is unlimited.

3. Specify that the free resource is prorated based on usage when a customer cancels a product.

4. Define a cycle fold rate plan to fold the free resource.

5. Configure a fold to convert the free resource to the currency resource when there is overuse.

Rating Delayed Events for Canceled Products

By default, BRM does not delete /purchased_product objects (product instances) when you cancel them. When BRM is set up to use delayed billing, BRM requires information about the canceled products to rate the delayed events that were generated before the product was canceled. To rate events for canceled products, the canceled product instances must persist as /purchased_product objects, which is the default behavior. To check your settings, see "Customizing Product Cancellation".

You can also choose to rate fold events for canceled products, including products in canceled deals. By default, fold events associated with canceled (inactive) products are not rated.

Calculating Conditional Discounts When Canceling a Product

When canceling a product, discounts that are based on conditions cannot be reliably calculated. When a product is canceled, the discount calculated during monthly charges is recalculated because the condition values applied during the monthly charge may be different from the values applied at the time of product cancellation.

For example, suppose a customer receives a 5% discount when the total monthly charge is less than $100, but receives a 10% discount when the total monthly charge is greater than $100. At product purchase time, the total monthly charge is just the purchase amount, which is likely to be less than $100, so a 5% discount is applied. If the product is canceled in the same month or in a subsequent month, but the total monthly charge is greater than $100, a 10% discount is applied as a prorated charge (if the discount is set to be prorated). This occurs because the product cancellation occurs before the end of the month.

Note:

Conditional discounts are rarely used for purchase and cancellation events.

To ensure that conditional discounts are reliably calculated when canceling a product, do one of the following:

• When you define a discount, select options to prorate the balance impact for the amount to ensure there is no refund at the time of product cancellation.

• If the discount calculated at product cancellation is not correct and the customer calls to get a resolution, the CSR can manually calculate the correct discount and the prorated refund amount.

Specifying to Delete Canceled Products

You might want to delete canceled products from your database (for example, to improve performance by reducing the amount of data stored in the database).

Important:

• Do not delete canceled products if you use delayed billing. See "Rating Delayed Events for Canceled Products".

• Do not delete canceled products if you rerate events. Events that use deleted products cannot be rerated.

• You cannot delete a product if provisioning tags are defined for that product. Products with provisioning tags are updated by the provisioning system and therefore must remain in the BRM database.

• Oracle recommends that you not delete canceled products and discounts because other external systems might also use them.

To automatically delete /purchased_product objects when a product is canceled:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

2. Change the value of the keep_cancelled_products_or_discounts entry.

   • 0 deletes the canceled /purchased_product objects.

   • 1 (default) keeps the deleted products in the /purchased_product objects.

3. Save and close the file.

4. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

How Products Are Canceled

To cancel a product, use PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT. This opcode cancels the products associated with the /account object specified in the input flist.

PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT is called by the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode to cancel each product associated with a specific deal. Depending on how many products are included in the deal, PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT may be called more than once.

The input flist identifies the products to cancel in the PIN_FLD_OFFERING_OBJ (/purchased_product POID) field. For more information on offering objects, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.

PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT performs the following tasks:

1. Closes billing if the account balance is affected.

2. Opens a transaction.

3. Verifies that the product is valid for cancellation.

4. Checks if the corresponding deal is a required deal. If so, does not perform the cancellation.

5. Calls the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode to determine whether to cancel and delete the product, to cancel without deleting the product, or to not allow the cancellation. If the corresponding deal has any dependencies, the product cannot be deleted.

   Note:

   By default, BRM retains canceled products. You can change this behavior by customizing the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode. See "Customizing Product Cancellation".

6. If the cancel product provisioning tag is set for the product, PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT calls the PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING policy opcode to clear fields in the service object. See "Customizing Provisioning When Canceling a Product".

   If a /config/provisioning_tag object is associated with the product, this opcode runs the opcodes specified in that object to run at product cancellation time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.

7. Validates the product 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 that the quantity owned, the product quantity is modified; the product is not canceled.

8. If the product cancellation is backdated, validates that:·

   • The date to which the product cancellation is backdated is not prior to the G/L posting date·

   • The date to which the product cancellation is backdated is not prior to the effective date of the account or service.·

   • The date to which the product cancellation is backdated is not prior to the last status change date of the account or service.

   See "About Backdated Product, Discount, or Deal Cancellation".

9. Sets the product's purchase, usage, and cycle end dates to the cancellation date.

10. Reads the PIN_FLD_FLAGS value passed in from PCM_OP_SUBSCRIPTION_TRANSITION_DEAL to determine if cancellation fees should be waived.

11. Cancels any customized products associated with the product.

12. For products that have not been customized, applies the following fees, if applicable:

    • If the product is active and has any cycle forward fee associated with it, and if the product 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 product is active and has a cycle arrears fee associated with it, and if the product 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 product has a cancellation fee, the cancellation fee is applied and an /event/billing/product/fee/cancel event object is generated.

      Note:

      If the product's validity period is configured to start on first usage and has not yet been set, the product has not been activated. In this case, cycle fees are not charged.

13. For products that have been customized, applies cancellation fees based on whether a customized product is currently valid:

    • If a customized product is currently valid, the cancellation fees in the customized product are applied.

    • If no customized product is currently valid, the cancellation fees in the base product are applied.

    See "How BRM Cancels Base and Customized Products".

14. For customized products, refunds the customized product's cycle fees. Also refunds the cycle fees of the base product, then reapplies them based on the new validities. See "How BRM Cancels Base and Customized Products".

15. Creates the audit log /event/billing/product/action/cancel object to record the cancellation of the product.

16. Returns the POIDs of all event objects created as a result of the modification. For detailed information, see the output flist specification.

PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT fails in the following cases:

• If the specified product 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 product pricing quantity is less than the cancellation quantity specified in the input flist.

Customizing Product Cancellation

To customize product cancellation, use the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode.

By default, when a product 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 product cancellation date. The PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode allows you to specify whether the /purchased_product object is deleted or remains with a status of Canceled.

Important:

BRM requires information stored in the product to rate events when you use delayed billing and when events are rerated. In these cases, products should not be deleted.

Note:

You can also delete canceled products by setting a configuration parameter. See "Specifying to Delete Canceled Products".

You can customize the behavior of the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode 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 product cancellation.

  Note:

  The pin_bill.h header file defines all action strings.

By default, the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode reads the provisioning tag of the product object. If a provisioning tag is configured for the product, 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 Product Pricing

You can customize the pricing of a customer's products in three ways:

• Override the price for purchase and cycle events. See "Overriding a Product Price".

• Provide a fixed-amount or percentage discount that applies to the product as a whole. See "Providing Product Discounts".

• Modify rates or price models in the product by specifying positive or negative changes to resource balance impacts. See "Modifying Rates and Price Models in a Product".

Price overrides and product discounts are collectively called basic customizations. Modifications to rates and price models in a product are called advanced customizations.

Overriding a Product Price

You can override a product's purchase and cycle forward rates by entering a fixed price. This differs from a product discount, which is relative to an established price.

To override a product price, the CSR selects the product in the customer's account and enters an override price for the appropriate type of fee. Figure 11-3 shows Customer Center defining an override price of $15 for the purchase fee:

Figure 11-3 Defining an Override

Description of ''Figure 11-3 Defining an Override''

Note:

• To make purchase or cycle events free, enter 0 as the override price.

• If you specify both a discount and an override price, the override price is discounted.

• To override a price when the account uses two currencies, make sure the display currency is the account's primary currency. Enter the override price in the primary currency.

Important:

• If a product has more than one cycle forward rate, do not enter an override price in the Cycle Info group. The override price substitutes for all cycle forward rates that affect the balance of a currency resource.

• Overriding the price applies only to scaled balance impacts. If the product includes a fixed balance impact, the override price is added to the price, it does not replace it.

Providing Product Discounts

You can provide percentage and fixed-amount discounts for a product's purchase and cycle forward rates and percentage discounts for usage rates. These types of discounts apply to the product as a whole.

Note:

Product discounts are not the same as the separate, purchasable discounts that you can add to an account. See "About Discounts" in BRM Configuring Pipeline Rating and Discounting.

To discount a product, the CSR selects the product in the customer's account and enters the discount for the appropriate type of fee. Figure 11-4 shows Customer Center defining a discount of $5 for the purchase fee:

Figure 11-4 Specifying a Discount

Description of ''Figure 11-4 Specifying a Discount''

Note:

To give discounts when the account has two currencies, make sure the display currency is the account's primary currency. If you are giving a fixed-amount discount, enter the amount in the primary currency.

• You can use Pricing Center to specify if products are discountable. See "Providing Discounts with Deals" in BRM Setting Up Pricing and Rating.

• You can provide fractional discounts up to two decimal places; for example, 10.25%, but not 10.255%.

• You can configure the way discount results are calculated. See "Providing Discounts with Deals" in BRM Setting Up Pricing and Rating.

Modifying Rates and Price Models in a Product

You can modify pricing for individual real-time rates and pipeline price models in a product. You can specify positive or negative percentage changes to resource balance impacts in the product's rates and price models. These types of modifications are called advanced customizations.

For example, you can increase the peak usage rate for a GSM customer by 10%, decrease the holiday usage rate by 50%, and increase the free minutes grant by 15%.

Advanced customization enables you to provide products that are configured specifically for a customer, without having to create new products in the product catalog.

When you modify a product in this way, BRM creates a customized products. Customized products do not appear in Pricing Center, but they are used during rating in place of the base product. See "How BRM Stores Customized Product Data".

You set validity periods for customized products that determine the time periods during which they will be used. You can create multiple customizations of the same product with non-overlapping validity periods. See "About Customized Product Validity".

During rating, BRM checks for the existence and validity of customized versions of the product that apply to the rated event. If it finds a valid customized product, it uses the rates in that product rather than those in the base product. See "How BRM Rates Events with Customized Products".

You use the Advanced Customization dialog box in Customer Center to create customized products and to view their details after creation. The dialog box displays the hierarchy of real-time and pipeline pricing objects in a base product and enables you to view details about those objects. When you create a customized product, you specify its validity dates and percentage changes to resource impacts in rates and price models as shown below in Figure 11-5.

Figure 11-5 Customizing Products

Description of ''Figure 11-5 Customizing Products''

If you do not use Customer Center as your customer relations management (CRM) tool, you can call opcodes from another CRM tool to customize products. You can modify existing customizations with opcode calls. See "Using Opcodes to Customize Products" in BRM Setting Up Pricing and Rating.

You must grant permissions to Customer Center users to allow them to customize a product. You use the accounttool/product/override to control the ability to customize a product. This permission is not granted by default. You can define minimum and maximum customization limits.

A product can be customized only if the deal that contains it was created with the Deal customization setting at Optional or Required.

How BRM Stores Customized Product Data

When you create an advanced customization of a product, BRM creates a unique /product object in the database specifically for that customization. This object stores not only the customized rates and validity periods but also uncustomized data from the base product. Both pipeline and real-time data is stored in the customized /product object. (BRM also creates customized data in the pipeline database and updates data modules in the pipeline. See "How BRM Stores and Updates Customized Pipeline Data").

BRM creates a separate /product object for each customization of the product. For example, if you customize a product to include a 25% discount for the month of June and later create a separate customization of the same product with a 10% discount for the month of August, BRM creates two separate customized /product objects.

When BRM creates a customized /product object, it calculates the new rates based on the percentage changes you entered. These new rates are stored in modified pricing components, such as price model steps for pipeline rate plans and balance impacts for real-time rate plans. Other pricing components included in the base product are copied in unmodified form to the customized product object.

A customized /product object includes all the pricing data from the base product:

• For real-time rate plans, customized objects include event maps, rate plans, rate plan selectors, rate tiers, day and date ranges, time ranges, rates, and balance impacts.

• For pipeline rate plans, customized objects include rate plans, rate plan versions, rate plan configurations, price model selectors, price models, and price model steps.

Because each customized /product object includes a copy of the uncustomized data in the original base product, the customized product is isolated from changes to the base product. For example, suppose you customize one rate in a product but leave all the other rates at their original values. BRM uses the rates in the customized product, including the ones you did not change, as long as the customized product is valid. Even if the base product changes during the customized product's validity period, BRM uses the original, unmodified rates along with the rate that you customized.

If you want changes to a base product to be reflected in a customized product, you must cancel the customized product and create a new customization based on the modified base product.

In some cases, a customized /product object may include multiple copies of a pipeline pricing component. This situation occurs because it is possible for multiple rate plan configurations and model selector rule sets to point to or customize the same price model. In this case, BRM includes a copy of the unmodified price model as well as a modified version of the same price model. For example, RatePlanConfigurationA might point to PriceModel1 in its original form whereas RatePlanConfigurationB modifies PriceModel1. The customized /product object would include a copy of the unmodified PriceModel1 as well as a copy that includes the modifications.

To distinguish them from other /product objects, customized /product objects include the field PIN_FLD_TAILORMADE with a value of 1. BRM filters by this field to prevent customized products from appearing in Pricing Center. A customized /product object also includes the POID of the base product on which it is based, stored in the PIN_FLD_BASE_PRODUCT_OBJ field.

BRM stores customized real-time rates in the PIN_FLD_TAILORMADE_DATA field of the /rate object. This field stores resources and the percentage change to them as semicolon-delimited, comma-separated pairs. For example, reductions of 10% to the euro and US dollar resources would be stored in PIN_FLD_TAILORMADE_DATA as EURO, -10;USD, -10.

How BRM Stores and Updates Customized Pipeline Data

If a customized product includes changes to a pipeline rate plan, BRM stores customized pricing data in the pipeline database as well as in the /product object. In addition, when you create or modify a customized product with a pipeline rate plan, BRM generates a notification event that causes pipeline modules to refresh their data caches.

When you customize a pipeline rate plan in a product, BRM creates copies of the relevant pipeline pricing components and stores them in the pipeline database. These customized pricing components are given a unique code based on the original component code. See "About Customized Product and Pipeline Pricing Component Names".

Pipeline Manager uses the data stored in the pipeline database to initialize pipeline modules if the pipeline is restarted after the product customization occurs. When customization occurs while the pipeline is active, modules use the event notification mechanism to update their data. See "Updating Pipeline Modules with Customized Data".

Table 11-1 lists the pipeline pricing components that can be customized and the database tables in which they are stored:

Table 11-1 Pipeline Components That Can Be Customized

Pricing Component	Database Table
Rate Plan	IFW_RATEPLAN
Rate Plan Version	IFW_RATEPLAN_VER
Rate Plan Configuration	IFW_RATEPLAN_CNF
Price Model	IFW_PRICEMODEL
Model Selector	IFW_MODEL_SELECTOR
Model Selector Rule Set	IFW_SELECTOR_RULESET
Selector Rule	IFW_SELECTOR_RULE
Selector Rule Link	IFW_SELECTOR_RULE_LINK
Selector Detail	IFW_SELECTOR_DETAIL

The database table for price models (IFW_PRICEMODEL) includes the TAILORMADE_DATA column, which stores customized resources and the percentage change to them as comma-separated pairs. For example, reductions of 10% to the euro and US dollar resources would be stored as EURO, -10;USD, -10.

The TAILORMADE column in the IFW_PRICEMODEL, IFW_MODEL_SELECTOR, IFW_SELECTOR_RULE, IFW_SELECTOR_DETAIL, and IFW_SELECTOR_RULESET tables indicates whether an object is customized. A value of 1 in the column indicates a customized object.

Updating Pipeline Modules with Customized Data

When you create or modify a customized product, BRM generates a notification event: /event/notification/price/tailormade_products/create or /event/notification/price/tailormade_products/modify. These events include full customized product information, including pipeline rate plans, rate plan configurations, price models, and price model selectors.

The DAT_PriceModel, DAT_Rateplan, and DAT_ModelSelector modules respond to these events through their connection to the DAT_Listener module. They update their caches to include the customized data so that it can be used during rating.

About Customized Product and Pipeline Pricing Component Names

BRM automatically creates the name of the customized /product object based on the name of the base product and the creation time. BRM prepends a hexadecimal version of the creation time, in seconds, to the base product name. For example, if the base product name is GSMTelephony, a customized product name could be AE9C6890_ GSMTelephony. The original product name is truncated if necessary to maintain a size limit of 255 characters.

BRM also renames the copies it creates of pipeline pricing components. The code of each component is changed to include a two-letter abbreviation that indicates the component type, the hexadecimal creation time in milliseconds, and a unique five-digit integer value.

These are the abbreviations for the various component types:

• PR: pipeline rate plan

• PM: pipeline price model

• MS: pipeline model selector

• RS: pipeline model selector rule set

• SR: pipeline model selector rule

• SD: pipeline model selector detail

About Customized Product Validity

When you customize a product, you specify validity periods for the customization. You specify separate validity periods for changes to purchase, cycle, and usage fees. The purchase start and end times define the overall validity of the customization.

The validity periods of the customized and base products determine whether the base or customized product is used to rate usage events, apply purchase fees, and apply cycle fees. For example, suppose a product is valid starting January 1, 2006, with no ending date. You later customize the product to provide a 10% reduction on usage and cycle fees with validity from March 1, 2006, to April 30, 2006. The base product's cycle fees and usage rates apply in January and February. The 10% reduction on usage and cycle fees applies during March and April. The normal fees of the base product resume on May 1 and are valid until another customization takes effect as shown in Figure 11-6.

Figure 11-6 Example Time-line for Product Fees

Description of ''Figure 11-6 Example Time-line for Product Fees''

You can create multiple customizations of a base product as long as their validities do not overlap. Figure 11-7 shows how you can customize a product to provide the subscriber with a 25% reduction on usage for March and a 10% reduction for April.

Figure 11-7 Multiple Discounts Defined for a Product

Description of ''Figure 11-7 Multiple Discounts Defined for a Product''

Note:

You can create only one customized product for a base product under these circumstances:

• The base product validity is configured to start on first usage. The validity of the customized product must also start on first usage.

• The base product validity begins on a specific date and you set the customized product to start on first usage.

After the validity start date has been reached, you can create additional customizations for the base product.

You customize during product purchase and set the starting validity periods of the base and customized products to be the same.

The validity periods of a customized product must fall within the validity periods of its base product and cannot overlap with the validity periods of another customization of the same base product. Validity periods can fall in the middle of billing cycles and can be backdated as long as the dates fall within the validity of the base product.

Note:

Backdating validity periods is allowed only when you first create a customization. You cannot backdate a customization after it has been created.

See "Validity Periods and Purchase Fees for Customized Products" and "Validity Periods and Usage Fees for Customized Products".

You can modify the validity periods of a customized product after its creation. For example, you can extend the length of a customization for an additional month.

Note:

You cannot modify a customized product's validity period in such a way that it no longer falls within the validity of the base product or overlaps the validity of another customized product. Similarly, you cannot modify the validity of a base product in such a way that a customized product's validity no longer falls within the validity of the base product.

See the following for more information on how validity periods are used to calculate purchase, usage, and cycle fees:

• Validity Periods and Purchase Fees for Customized Products

• Validity Periods and Usage Fees for Customized Products

• Validity Periods and Cycle Fees for Customized Products

Validity Periods and Purchase Fees for Customized Products

The purchase validity periods of the base and customized products at the time of purchase determine which is used to apply purchase fees.

If you customize a product at the time of the initial product purchase and set its purchase validity to begin at the same time as the base product, the purchase fee in the customized product is applied. If the purchase validity of the customized product begins after the initial product purchase, the base product's purchase fees are applied.

If you customize a product after the initial product purchase, the purchase fee of the customized product is not applied because the base product's purchase fee has already been applied. If you want to apply the customized product's purchase fee, you must trigger rerating for the purchase event. See "About Rerating" in BRM Setting Up Pricing and Rating.

Validity Periods and Usage Fees for Customized Products

The usage validity of the base and customized products at the time of a usage event determine which product is used to rate the event. For example, if a customization has usage validity periods from August 1 to September 1, the usage rates defined in the customized product are used to rate events that occur during that month. Usage rates in the base product are used to rate all other events.

You may need to trigger rerating after customization to ensure that events that fall in the customized product's validity periods are rated properly. For example, suppose that the GSM_Basic product rates peak calls at $0.10 per minute. A subscriber makes a 20-minute peak call on January 3, generating a usage event with a $2 balance impact.

If a CSR customizes this product on January 5 to reduce the peak usage rate by 25% with validity starting on January 1, you must rerate the January 3 call to ensure that the subscriber is charged correctly. After rerating, the balance impact will be $1.50, so an adjustment event of –$0.50 will be applied to the subscriber's balance. See "About Rerating" in BRM Setting Up Pricing and Rating for more information on rerating.

Validity Periods and Cycle Fees for Customized Products

The cycle validity periods of the customized and base products determine which product is used to apply cycle fees.

If a customized product exists at the beginning of the cycle and is valid throughout the cycle, its cycle fees are applied normally. This is also true in cases where a product is customized at purchase time with the customization's validity set to begin at the same time as the base product's. The cycle fees of the customized product are used until they are no longer valid.

If a customized product is valid for only part of a cycle, it contributes toward the total charge or refund based on the length of its validity. For example, suppose you discount the $10 monthly cycle fee of GSM_Basic by 15% with a validity period of March 1 to April 16. The cycle fee for March will be $8.50, reflecting the 15% discount for the whole month. The cycle fee for April will be $9.25: The cycle fee for the first half of the month is reduced by 15% to $4.25 and the full $5.00 fee is charged for the second half of the month.

If you customize a product's cycle forward fees in mid cycle, the already charged fees are refunded and new fees are calculated on the validities of the base and customized product. For example, suppose that on April 11 you customize a $10 monthly cycle forward fee by 10%, with validity from April 11 to May 1. BRM refunds the $10 cycle fee that was already paid. It then applies fees separately for the portion of the cycle covered by the base product ($3.33, or 10/30 of $10) and for the portion covered by the customized product ($6.00, or 20/30 of $10 minus 10%). The total cycle fee is therefore $9.33.

When the base product and one or more customized products are valid during a cycle, BRM creates separate cycle events to cover the validities of each product. Each event is rated separately based on the rates in the applicable product.

How BRM Cancels Base and Customized Products

You cancel a base product with customized products the same way you cancel a product that has not been customized. See "Canceling Products". When you cancel a base product, any customized products associated with it are also canceled.

You cancel a customized product by using the Advanced Customization menu in the Plans - Product Details tab in Customer Center. Canceling a customized product does not cancel its base product.

Note:

You cannot cancel a customized product after the expiration of its validity.

Cancellation Fees

When you cancel a base product, BRM applies cancellation fees based on whether a customized product is valid or not:

• If a customized product is currently valid, the cancellation fees in the customized product are applied.

• If no customized product is currently valid, the cancellation fees in the base product are applied.

For example, suppose that the GSM_Basic product has a cancellation fee of $10. You create a customized version of the product with a 50% reduction of the cancellation fee, valid from January 1 to February 1. If the subscriber cancels on January 31, the cancellation results in a $5 balance impact (assuming that cancellation proration is set to Charge for the entire cycle). If the subscriber cancels on February 2, the balance impact is $10.

When you cancel a customized product without canceling its base product, no cancellation fees are applied.

Cycle fees

If you cancel a base product that has cancel proration set to Calculate the charge based on the amount used, the way cycle fees are prorated depends on whether a customized product is valid:

• If no customized product is valid, proration is based on the cycle fees in the base product.

• If a customized product is valid, proration is based on the cycle fees in the customized product.

• If you cancel a product during a cycle in which both base and customized products are valid, proration is based on the cycle fees and validity of both products. See "Calculating Prorated Cycle Fees and Refunds for Customized Products" in BRM Configuring and Running Billing.

If you cancel a customized product in mid cycle without canceling its base product, the cycle fees for the remainder of the cycle are first refunded based on the fees in the customized product. Cycle fees for the remainder of the cycle are then applied based on the base product's fees.

For example, suppose that the product GSM_Basic has a cycle forward fee of $10 and cancel proration is set to Calculate the charge based on the amount used. A CSR subsequently customizes this product for a subscriber to reduce the cycle forward fee by 20% with a validity period of January 1 to February 1.

If the customized product is canceled on January 16, BRM refunds $4. This amount is the customized product's prorated cycle fee for the unused period of January 16 to February 1. Because the base product is now valid, BRM then applies its prorated cycle fee of $5 for the same period. The total cycle fee is $9.

How BRM Rates Events with Customized Products

BRM uses a customized product for rating instead of the base product from which it was derived, as long as the customized product is valid. For both real-time and pipeline rating, BRM checks to see whether a product has a customized version and then checks the validity of any customized products it finds. If a valid customized version is found, it is used for rating. For more information on validity, see "About Customized Product Validity".

There are some specific differences between the real-time and pipeline cases.

• In real-time rating, when BRM rates an event, it finds a list of products that apply to the event, filtering by parameters such as service and event time. It sorts the list of qualified products by priority and uses them in that order. BRM checks if any of the qualified products have customizations and, if they do, whether the customizations are still valid. If a customized product is valid, it replaces its base product in the list of qualified products and it is used for rating. Customized products have the same priority as their base products.

  You can control whether customized products are cached for use by the real-time rating engine. You enable and disable product caching in a /config/business_params entry. See "Enabling and Disabling the Caching of Customized Products" in BRM System Administrator's Guide.

• In pipeline rating, the FCT_Account module populates the CUSTOMER_ DATA.PURCHASED_PRODUCT field of an event data record (EDR) with the account's purchased products that are valid for the time of the event. This list can include both base products and customized products. FCT_Account also populates the DETAIL.CUST_A.INTERN_RATING_PRODUCTS field with products to be used for rating, along with the priority of each product. The DAT_AccountBatch module then checks the base products in DETAIL.CUST_A.INTERN_RATING_PRODUCTS to determine whether customized versions exist. If DAT_AccountBatch finds a customized product for a base product and both products are valid, the base product is removed from DETAIL.CUST_ A.INTERNAL_RATING_PRODUCTS. The customized product is therefore used for rating.

Because advanced customizations modify rates and price models, these changes are applied before charges are reduced by discounting. Charges that you reduce by customization can be further reduced by discounts. For example, suppose the GSM_Basic product charges $0.10 per minute for peak usage. A 20-minute peak call would result in a $2 balance impact. If you customize the product to reduce the peak usage rate by 25%, that same call results in a balance impact of $1.50. If the subscriber also owns a 10% discount on GSM usage, the balance impact would be further reduced by $0.15, resulting in a final balance impact of $1.35 for the call.

Managing Discounts

Discounts are pricing objects similar to products; customers purchase discounts bundled in a deal.

Purchasing Discounts

When purchasing a discount, you specify the following attributes:

• Purchase quantity

  The discount purchase quantity must be within the minimum and maximum allowed. See "Changing Discount Quantity".

• Status

  The discount status can be active or inactive. See "Setting Discount Status".

• Start and end dates

  The start and end dates specify when the discount begins and ends. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.

About Purchasing Discounts in Mid Cycle

When a discount is purchased, BRM charges prorated and discounted cycle forward fees for the period during which the discount is valid. For more information, see "Prorating Cycle Fees after a Discount Purchase or Cancellation" in BRM Configuring and Running Billing.

How Discounts Are Purchased

To purchase a discount, use the PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT opcode.

Important:

Do not call PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT directly. This opcode is always called by the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode.

PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT performs these operations:

1. Closes the bill.

2. If billing is due, triggers billing.

3. Opens a transaction.

4. Reads the discount object information.

5. Performs the following validations:

   • Date validation, to make sure that the product is available for purchase.

   • Status validation, to check whether the discount is active or inactive.

   • Ownership quantity validation, to make sure that the discount 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.

6. Calculates the start and end dates of the purchase/cycle/usage events based on either CSR customization or pricing object details. If passed relative dates, calculates absolute dates. If Content Manager 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 Validity Periods of Products and Discounts".

7. If the discount purchase is backdated, validates that:

   • The date to which the discount purchase is backdated is not prior to the G/L posting date.

   • The date to which the discount purchase is backdated is not prior to the effective date of the account or service.

   • The date to which the discount purchase is backdated is not prior to the date of the last status change of the account or service.

     Important:

     If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.

   See "About Backdated Product, Discount, Deal, or Plan Purchase".

8. If a /config/provisioning_tag object is associated with the discount, this opcode runs the opcodes specified in that object to run at discount purchase time. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.

9. If applying discount 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 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 (Prorated discount, valid only part of the cycle).

10. Determines whether the discount 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.

11. If purchasing discounts in the middle of a cycle and the discount usage map is configured to support any cycle forward event types, refunds the discounted portion of the cycle forward fee as follows:

    1. Checks all discount usage maps to see whether the discount supports any cycle forward monthly event types.

    2. For each cycle forward event type supported by the discount, checks the charges arrays of all product instances for an array element of the cycle forward event type.

    3. Calculates the scale value for the portion of the cycle for which the discount is valid.

    4. Sends a request to rate normal prorated events and calculates the resulting prorated balance impact.

    5. Sends the event with an inverted flag set for recording.

12. Generates an audit log for the discount purchase, which sends a request to the PCM_OP_ACT_USAGE opcode to record an /event/billing/discount/action/purchase event.

13. Prepares the return flist.

14. Closes the transaction.

If the discount purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT returns a message confirming the success.

Validating Discount Dependencies

To validate discount dependencies, use the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY opcode.

Configure mutually exclusive dependencies in the /dependency storable class.

PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY calls other standard 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 discounts 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-price-plan 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.

This opcode 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.

This opcode 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, this opcode returns a zero result, along with the POIDs of the discounts or plan and discount, whichever operation occurs first.

Canceling Discounts

You typically cancel a discount instance when you cancel the deal in which it is bundled or when you close the account or service that owns the discount instance. You can also cancel a discount instance immediately or backdate the cancellation to a date earlier than the current date. A discount instance gets canceled automatically when the discount's purchase end date has been reached.

To cancel a discount instance, you must specify the quantity to cancel:

• If the quantity is the same as the quantity purchased by the account or service, the opcode cancels the discount instance.

• If the quantity is less than the quantity purchased by the account or service, the opcode does not cancel the discount; it subtracts that quantity from the internal count variable within the /purchased_discount object that represents the discount instance.

By default, when you cancel a discount instance, BRM retains the /purchased_discount object that describes the discount instance with a status of Canceled. You can specify whether to delete /purchased_discount objects or retain them with a status of Canceled. See "Specifying to Delete Canceled Discounts".

Changing the status of a discount instance to canceled sets the purchase, usage, and cycle end times to the cancellation time. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.

Canceling Resource Sharing Group Owner Discounts

When you cancel a discount instance for an account or service that also owns a resource sharing group, you also cancel the discount instance from each resource sharing group that the account or service owns.

For more information on resource sharing groups, see "About Resource Sharing Groups" in BRM Managing Accounts Receivable.

Rating Delayed Events for a Canceled Discount

By default, when you cancel a discount instance, you set the /purchased_discount object's status to Canceled. When you set up BRM to use delayed billing, BRM requires information about the canceled discount instances. BRM uses this information to rate the delayed events that were generated before the discount was canceled. To rate events for canceled discounts, the canceled discount instances must not be deleted.

BRM does not delete canceled discounts by default. To ensure that canceled discount objects are not deleted, do the following:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

2. If necessary, set the value of the keep_cancelled_products_or_discounts entry to 1.

3. Save and close the file.

4. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

5. Edit the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode. By default, this policy opcode keeps /purchased_discount objects when they are canceled. Verify that you set the opcode to cancel, not delete, the discount.

When you change the status of a discount to Canceled, you also set its purchase, usage, and cycle end dates to the cancellation date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

About Canceling a Discount in Mid Cycle

When you cancel a discount, you also prorate and charge cycle forward fees that may have been discounted for the period during which the discount is no longer valid. For more information, see "Prorating Cycle Fees after a Discount Purchase or Cancellation" in BRM Configuring and Running Billing.

Specifying to Delete Canceled Discounts

You might want to delete canceled discounts from you database (for example, to improve performance by reducing the amount of data stored in the database).

Important:

• Do not delete canceled products if you use delayed billing. See "Rating Delayed Events for Canceled Products".

• Do not delete canceled products if you rerate events. Events that use deleted products cannot be rerated.

To delete /purchased_discount objects when you cancel a discount:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

2. Change the value of the keep_cancelled_products_or_discounts entry.

   • 0 deletes /purchased_discount objects when you cancel the discount.

   • 1 (default) keeps the canceled discounts in /purchased_discount objects.

3. Save and close the file.

4. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

How Discounts Are Canceled

To cancel a discount instance, use the PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT opcode.

This opcode cancels the discounts for the /account object or /service object specified in the input flist.

Note:

If you specify a NULL /service object, you cancel discounts associated with the /account object. Otherwise, you cancel discounts associated with the /service object.

You identify discounts to cancel in the PIN_FLD_OFFERING_OBJ (/purchased_discount POID) field in the input flist. For more information on offering objects, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL.

To cancel a discount instance, PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT performs the following tasks:

1. Validates the discount quantity requested for cancellation. The quantity must be less than or equal to the quantity owned by the account or service. See "Changing Discount Quantity".

   Note:

   When the quantity to cancel is less than the quantity owned, the discount quantity within the instance is decreased; the discount is not canceled.

2. If the discount cancellation is backdated, validates that:

   • The date to which the discount cancellation is backdated is not prior to the G/L posting date.

   • The date to which the discount cancellation is backdated is not prior to the account or service's effective date.

   • The date to which the discount cancellation is backdated is not prior to the date of the last status change of the account or service.

     Important:

     If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.

   See "About Backdated Product, Discount, or Deal Cancellation".

3. If a /config/provisioning_tag object is associated with the discount, this opcode runs the opcodes specified in that object to run at discount cancellation time. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.

4. Sets the purchase, cycle, and usage end dates for the /purchased_discount object to the cancellation date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

5. If you set a discount 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 cancellation date.

   For more information on discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.

6. Calls the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode 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 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.

7. Applies cycle fees or refunds discounted cycle fee amounts. See "Prorating Cycle Fees after a Discount Purchase or Cancellation" in BRM Configuring and Running Billing.

   Note:

   If the discount's validity period is configured to start on first usage and has not yet been set, the discount has not been activated. In this case, cycle fees and refunds on discounted cycle fees are not applied.

8. 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.

Customizing Discount Cancellation

To customize how discounts are canceled, use the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode.

Note:

You can also keep or delete canceled discounts by setting a configuration parameter. See "Specifying to Delete Canceled Discounts".

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 cancellation date. The PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode 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 this policy opcode 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.

  Note:

  All these strings are defined in the pin_bill.h include file.

Modifying Discount Attributes

You can modify the following discount attributes:

• Discount quantity. See "Changing Discount Quantity".

• Discount status. See "Setting Discount Status".

• Discount purchase, usage, and cycle start and end times. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

You use Customer Center to modify these discount attributes. See "Managing Discounts".

For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.

Changing Discount Quantity

You can change the quantity of a discount when you purchase or cancel it or when you purchase additional quantities of the same discount. Discounts can have minimum and maximum purchase and ownership quantity limits. The discount quantity purchased must be within these limits. For example, if a discount has a maximum quantity of 10, a subscriber can purchase 10 instances of the same discount. If a discount has a maximum quantity of 5, a subscriber can purchase 5 instances of the same discount.

For more information on setting up discounts, see "About Implementing Discounts" in BRM Configuring Pipeline Rating and Discounting.

Setting Discount Status

The status of a discount can be Active, Inactive or Canceled. A discount is not valid when it is inactive. The discount does not apply to any user events generated while it is inactive.

When you change the status of a discount, you specify the new status and the reason for the status change.

Discount status can change in the following cases:

• When you purchase a discount: you can set the status to Active or Inactive in the case of deferred purchase.

• When you purchase an inactive discount: you can later reactivate it by setting its status to Active.

• When you cancel a discount: you set the discount status to Canceled. See "Canceling Discounts".

• When you change the status of an account or service that owns a discount: you change the status of the discount to the same status; when you close an account, you cancel any discounts it owns.

Setting Discount Purchase, Cycle, and Usage Start and End Times

You specify a discount's validity period for the account that purchases the discount by setting the purchase start and end times. The cycle and usage start and end times specify when to start and stop charging cycle forward fees and rating usage events by using the discount rate. For more information, see "About Product and Discount Validity Periods" in BRM Setting Up Pricing and Rating.

You can modify a discount's purchase, usage, and cycle start and end times at the following times:

• When purchasing a discount.

• When canceling a discount. By default, the discount's purchase, cycle, and usage end times are set to the cancellation time. You can change the date the discount expires by modifying the discount's end time.

• When changing the status of a discount.

  Important:

  Do not change a discount's purchase, cycle, or usage start time after the discount has been applied to the account; otherwise, the discount will be applied incorrectly.

BRM does not allow you to backdate the discount's purchase, usage, or cycle end date prior to the discount's purchase start date or prior to the G/L posting date.

See "About Backdated Purchase, Usage, or Cycle End Dates".

The cycle and usage periods must start after the purchase period start time and end before the purchase period end time.

If you configure BRM for time stamp rounding, BRM rounds all start and end times to 00:00:00 hours.

When setting the validity period during discount purchase, Customer Center calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. See "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts".

When changing the validity periods of a purchased discount, Customer Center calls the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode. See "How Purchase, Cycle, and Usage Validity Is Modified".

How 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 purchase, cycle, or usage period. This opcode is called by the PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS opcode when the status of an account's discount is changed: for example, when you set a discount's status to Inactive when you purchase it and activate it at a later time.

After a discount is purchased and the start and end times are set, you can change the start and end times to specify only other absolute dates.

To change the discount'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.

Important:

Do not change a discount's purchase, cycle, or usage start time after the discount has been applied to the account; otherwise, the discount will be applied incorrectly.

If you change the purchase, cycle, or usage start time from first usage to an absolute date, the opcode generates an event that causes Pipeline Manager to update the validity period in the pipeline database.

The start and end times are stored in the account's /purchased_discount object.

PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO performs the following tasks:

1. Resets the /purchased_discount object's purchase, cycle, and usage start and end times to the times specified in the input flist.

   If discount validity rules are set, PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO sets the start and end times accordingly. See "Implementing Discount Validity Rules" in BRM Configuring Pipeline Rating and Discounting.

2. For backdating operations, validates and sets the discount's purchase, cycle, and usage end dates to a backdated date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".

3. Applies cycle fees or refunds discounted cycle fee amounts. See "Prorating Cycle Fees When a Discount's Cycle Start or End Date Is Changed" in BRM Configuring Pipeline Rating and Discounting.

   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, this opcode does not apply cycle fees or refund discounted cycle fee amounts.

4. 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.

For general information about modifying a discount in a deal, see "Modifying Discount Attributes".

Customizing Snowball Discounts

A snowball discount distributes group discounts to the members of a discount sharing group.

You can customize how group discounts are distributed to members by using the PCM_OP_SUBSCRIPTION_POL_SNOWBALL_DISCOUNT policy opcode. You call this policy opcode when you run billing and have discounts configured for billing-time discounting.

You can modify the PCM_OP_SUBSCRIPTION_POL_SNOWBALL_DISCOUNT policy opcode to specify an algorithm for distributing the total group discount grant to the individual group members. For instance, you can specify distribution of the group discount based on group member contribution.

Managing Deals

A deal consists of one or more products and discount objects. By bundling products into a deal, you can provide discounts for those products. For example, you can create a deal that waives the sign-up fee if the customer registers before a certain date.

You can add or upgrade a customer's products by purchasing deals after you create the account. Customers can purchase a deal only if they have already purchased a plan that includes the service that the deal offers. For example, if a customer has already purchased a product that uses the email service, the customer can purchase another email deal. To purchase a deal that has a different service, you add the deal to another plan and then add the plan with the new service. See "Purchasing Deals".

You can associate a deal with a particular service or with any service owned by an account.

You can set up deal transitions that determine which deals can be purchased subsequently to another deal. See "Transitioning Deals".

You can set up deal dependencies that determine which deals you allow a customer to own. See "Defining Deal Dependencies".

You can customize account-level deals during plan transitions. See "Customizing Account-Level Deals during Plan Transitions" for more information.

Purchasing Deals

You can add or upgrade products for customers by purchasing deals after you create the account. Customers can purchase a deal only if they have already purchased a plan that includes the service that the deal offers. For example, if a customer has already purchased a product that uses the email service, the customer can purchase another email deal. You can also backdate deal purchases.

You purchase deals for customers from the Plans tab of Customer Center. For more information on how deals are purchased, see "How Deals Are Purchased".

Note:

• If the customer upgrades to a deal that includes more free hours, cancel the old deal before purchasing the new deal. See "Canceling Products".

• When you purchase a deal, you can customize it by modifying one or more products in the deal. See "Modifying Products" and "Customizing Product Pricing".

• When you purchase a deal, you can backdate the purchase date for all of the products it contains by using the purchase wizard.

• You need the proper permissions to purchase or modify a deal. To modify a deal, the deal must be defined as customizable. You define this property in your price list.

You can set up dependencies between deals to specify:

• Deals that must be owned before another can be purchased.

• Deals that are required in a plan.

• Deals that cannot be owned at the same time.

• Deals that you can upgrade or downgrade to.

See "About Deal Dependencies" in BRM Setting Up Pricing and Rating.

How Deals Are Purchased

To purchase a deal, use the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode. The products and discounts in the deal are purchased for the account or service object specified in the input flist.

Note:

• If you specify a /service object, you purchase the deal for that service as a service-level deal. The /service object must belong to the account.

• If you specify a NULL /service object, you purchase the deal for the /account object as an account-level deal.

• If multiple deals 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 deal.

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL creates an identifier for each deal purchase. This identifier is stored in the PIN_FLD_PACKAGE_ID field in the /purchased_product and /purchased_discount objects. The identifier distinguishes products and discounts bundled as part of a deal or a plan purchase.

Note:

PIN_FLD_PACKAGE_ID is unique for every deal, except when deals are purchased in the same plan. In this case, all the offerings in the deals within the plan will have the same PACKAGE_ID. If you need to uniquely identify such a deal: to cancel it, for example, you need to provide the /service object along with the PACKAGE_ID. If the deals 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 products and discounts in a deal. For more information, see "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts".

If the deal's products or discounts grant resources that start on first usage (when the subscriber impacts the resource balance for the first time), you can specify that the validity period of all resources in the deal that start on first usage are set when one of those resources 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 deal for on-demand billing, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL helps to create the on-demand bill for purchase fees for products associated with the deal. You set up on-demand billing for deals and plans by using Pricing Center.

Before you purchase a deal, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls the PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY opcode to validate deal dependencies. If dependencies exist, the deal 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 discounts packaged in the deal and any plan the account already owns. The opcode retrieves the list of subscribed discounts and price plans and it calls the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY opcode to validate any mutual dependencies. If the opcode detects such a relationship, the deal purchase cancels. If no mutually exclusive relationship exists, the deal purchase continues. For more information, see "About Discount Exclusion Rules" in BRM Configuring Pipeline Rating and Discounting.

Note:

• Dependencies are not checked if the deal originated in an external customer relationship management (CRM) application. In that case, the input flist contains a type-only deal POID because no actual BRM deal exists.

• The opcode requires no validation if the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode was called from the PCM_OP_CUST_COMMIT_CUSTOMER opcode or the PCM_OP_CUST_MODIFY_CUSTOMER opcode.

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls the PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT opcode to create /purchased_product objects for each product in the deal. If a product is customized at the same time as it is created, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT is called multiple times to create the base product and its customized products.

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL uses the PIN_FLD_FEE_FLAG field to control whether PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies fees. See "Applying Purchase and Cycle Fees to the Balance".

When the deal and all products and discounts for the deal have been purchased, the opcode records an /event/billing/deal/purchase event in the database for auditing purposes.

If you successfully purchase the deal, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL returns the /account POID and the POID of the /event/billing/deal/purchase event.

You do not purchase the deal 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 deal if the CM configuration file has this entry set to 1:

- cm deal_purchase_for_closed_account 1 

Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts

Purchase, cycle, and usage validity periods define when products and discounts are valid and when product fees are charged and discounted. For more information, see "About Product and Discount Validity Periods" in BRM Setting Up Pricing and Rating.

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT and the PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT opcode, which set the purchase, cycle, and usage validity periods of the deal's products and discounts, 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.

When called by Customer Center, 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 products and discounts, those validity dates permanently override the dates specified in the /deal object.

Note:

Dates for advanced customizations do not permanently override the dates of the base product. When advanced customizations are not valid, the base product is selected for rating the customer's usage. For more information, see "Customizing Product Pricing".

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 product or discount 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 product or discount 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.

For more information on the unit and offset values, see "Specifying Purchase, Cycle, and Usage Start and End Times".

When the product or discount 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 product or purchased discount. 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 Products and Discounts".

Specifying Purchase, Cycle, and Usage Start and End Times

When the purchase, cycle, or usage period has an absolute 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 product'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 product is purchased.

• If a discount'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 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 Products and Discounts".

About Backdated Purchase, Usage, or Cycle End Dates

Setting a product purchase, usage, or cycle start dates to a backdated date is different from backdating a purchase itself. When the product 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 product on February 1, and set the PURCHASE_ START_T, USAGE_START_T, and CYCLE_START_T fields of the product to a backdated date of January 15. In this case, the charges are applied from January 15, but the creation time of the product 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 product.

Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the product becomes effective from January 15 (the creation time of the product 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 PURCHASE_ START_T, USAGE_START_T, and CYCLE_START_T to a backdated date.

Similarly, backdating a product or discount's purchase, usage, or cycle end dates is different from backdating the cancellation. When the product or discount'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 product 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 product.

Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the product 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 product purchase start date if the purchase start date has elapsed.

  For example, on January 1, a product 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 product cycle start date if the cycle start date has elapsed.

• The usage and cycle end date of a product prior to its purchase start date.

• The purchase, usage, and cycle end date of a discount prior to its purchase start date.

• The purchase, usage, or cycle start and end dates of a product prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".

• The purchase, usage, and cycle end dates of a discount prior to the G/L posting date. See "About Backdating Beyond 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 product 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 will be 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 product or purchase, usage, or cycle end date of a discount during purchase, enter the backdated date in the respective date fields.

After a product is purchased, use the PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode to backdate the purchase, usage, or cycle start and end dates. Similarly, use the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode to backdate the purchase, usage, or cycle end dates of the discount.

Important:

If you set the end date of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be refunded only for the current accounting cycle.

Storing Relative Start and End Times for an Account's Products and Discounts

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 products and discounts 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 product or discount 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 product or discount is purchased, the mode in the details field of the product or discount 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 product or discount is purchased. For more information, see "Storing Start and End Times for Products and Discounts in a Deal" in BRM Setting Up Pricing and Rating.

• 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.

Modifying Deals

You use Pricing Center to modify deals in the BRM database. Changes you make to deals in the database do not affect the deals already owned by customer accounts.

You can change the valid deal period or the products associated with the deal, and you can define prerequisites, mutually exclusive relationships, or transitions for deals. See the Pricing Center Help for more information.

You use Customer Center to modify deals owned by customer accounts; for example, to transition to a new deal.

Validating Changes to Deals

To validate changes to deals, use the PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS opcode.

Note:

To validate deal-to-deal transitions, use the PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY opcode. See "Validating Deal Transitions".

PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS performs these operations:

1. Performs validation checks on all of the deals.

2. Calls the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode to remove any canceled deals.

3. Removes the deals to be canceled from an account's list of deals.

4. Calls the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode to add the new deals to the account's list of deals.

5. Applies proration rules to the products. If any cancellation or purchasing fees are defined, they are charged.

6. If a deal created by PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS requires a new service, calls the PCM_OP_CUST_MODIFY_CUSTOMER opcode to create that service.

7. Creates an /event/billing/product/action/cancel object for the canceled deals.

How Deals Are Modified

To modify a deal owned by a customer, use the PCM_OP_SUBSCRIPTION_CHANGE_DEAL opcode. This opcode changes the subscription products associated with a deal for an account.

PCM_OP_SUBSCRIPTION_CHANGE_DEAL calls PCM_OP_SUBSCRIPTION_CANCEL_DEAL to cancel the subscription products associated with a deal and then calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase new subscription products and associates them with the deal.

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 deal.

• The /event/notification/deal/change_complete object signifies change completion. The information in the object indicates the new purchased deal.

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 products associated with the account are not changed.

Transitioning Deals

To transition deals, you use Pricing Center to set up transition rules, which are applied when you upgrade or downgrade a deal for a customer. This enables you to limit the deals that customers can switch to and still remain fully provisioned.

A deal cannot be transitioned under the following circumstances:

• The new deal is mutually exclusive to a deal currently in the account.

• The account is missing a necessary prerequisite deal.

• The deal is associated with an inactive service.

• The service being transitioned from and the service being transitioned to are not the same service.

• The deal is required in the associated plan.

Validating Deal Transitions

To validate deal-to-deal dependency rules, use the PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY opcode.

Customer Center and the PCM_OP_CUST_SET_STATUS opcode call PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY.

PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY performs the following steps:

1. Confirms that the validate_deal_dependencies entry in the CM pin.conf file exists and, if so, performs validations; if not, it does nothing. See "Enabling Deal Dependencies Validation".

2. Checks for a PIN_TRANS_NAME_DEAL_VALIDATION entry in the input flist. If this entry exists, the validation checks have already been performed within the current transaction.

3. Verifies that the input is a list of deals. If PIN_FLD_DELETED_FLAG is set to 1, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY performs the validations required if those deals were already deleted.

If the deals pass all validation checks, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns a PIN_FLD_RESULT value of True. If any deal 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 deals are mutually exclusive, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POIDs of the two deals and a message indicating that the two deals are mutually exclusive.

If the validation fails because a prerequisite deal is missing, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POID of the deal missing a prerequisite.

How Deals Are Transitioned

To transition a deal from one account to another, use the PCM_OP_SUBSCRIPTION_TRANSITION_DEAL opcode.

Customer Center calls this opcode to transition one deal to another in an account.

PCM_OP_SUBSCRIPTION_TRANSITION_DEAL performs the following steps:

1. Calls the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL policy opcode to perform any custom validation that you may have added. See "Customizing Deal Transitions".

2. Checks the /dependency and /transition objects to make sure that the deal transition does not violate any transition rules.

3. Checks the /deal object to make sure that the deal being transitioned is not a required deal in the associated plan. If it is required, the transition is not performed.

4. Performs the transition.

5. Charges cancellation fees for the old deal and purchase fees for the new deal 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 non currency resources are always prorated regardless of the product's cancellation proration setting.

     Important:

     The PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION opcode transitions valid services with a status of Inactive, but those services remain permanently inactive after the transition.

6. During the transition, calls the PCM_OP_BILL_CYCLE_FORWARD opcode and the PCM_OP_BILL_CYCLE_ARREARS opcode to prorate the cycle fees, if necessary. If the PIN_TRANS_PRO_NORMAL_ON_TRANSITION flag is set, any new products prorate the last cycle fee and the first cycle fee. This flag overrides the user proration settings for product purchases and cancellations.

Customizing Deal Transitions

You can customize how to transition a deal from one account to another:

• To get a list of deals and products available for transition, use the PCM_OP_CUST_POL_TRANSITION_DEALS policy opcode.

  Customer Center calls this policy opcode to return the list of deals available for an account to transition to and the products the deals contain. This policy opcode takes a deal POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of deals available for transition, including their product names and descriptions.

  Use the PCM_OP_CUST_POL_TRANSITION_DEALS policy opcode to perform any additional filtering of deals before they are returned as available for transition. For example, use this policy opcode to limit certain deals to customers in a specific city.

• To validate how deals are transitioned, use the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode. This policy opcode allows customized validation based on account data during deal-to-deal transitions.

  For example, you may restrict a deal transition to customers from a particular location or require that customers own the first deal for a specific period of time before allowing the transition to a different deal.

  The PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL policy opcode is called by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL before it performs any validation checks. By default, the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL policy opcode is an empty hook provided to facilitate customization. Usually, customization consists of transition rules based on account data.

  Note:

  To customize how to transition a plan from one account to another, use the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode. See "Customizing Plan Transitions without Configuring /transition Objects".

Defining Deal Dependencies

Important:

Product Dependencies is an optional feature that requires a separate license.

About Deal Dependencies

If you plan to support product dependency validations, you need to enable the deal dependencies validation to be able to check that no deal violates the prerequisites and mutual exclusivity rules. See "Enabling Deal Dependencies Validation" for more information.

You can define dependencies between deals in Pricing Center that set up the following relationships:

• Prerequisites. Specifies that an account must own a particular deal to be able to purchase an additional deal.

  Note:

  A prerequisite can contain deals of different services. For example, to own a GPRS deal, an account must own a GSM deal.

  Note:

  A prerequisite deal cannot contain item products. When you create a plan with alternate deals, and if the base deal contains an item product, the purchase fails.

• Required deal. Specifies whether deals are optional or required for plans. Required deals must be purchased when a plan is purchased, whereas optional deals can be added to an account at any time.

• Mutual exclusivity. Sets up a mutually exclusive relationship between two deals, so if an account owns one deal, it cannot own the other.

• Allowed transitions. Specifies which deals or plans can serve as replacements for others.

  Transitions specify the deals that customers can switch to and remain fully provisioned. While transitioning from one deal to another, your customers retain their devices, such as phone numbers and services.

  Customers owning deals associated with a primary service may transition to other deals associated with that primary service. The list of deals displayed as available for transition are all associated with a specific primary service.

Enabling Deal Dependencies Validation

To enable the deal dependencies validation.

1. Open the CM configuration file BRM_Home/sys/cm/pin.conf.

2. Uncomment the validate_deal_dependencies entry to enable the deal dependencies validation:

   - fm_utils validate_deal_dependencies 1
   

3. Save and close the file.

4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

See "How Deal Dependencies Are Validated" for more information.

How Deal Dependencies Are Validated

You use PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY to validate deal dependencies. There are two ways to run PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY:

• Pass in an account and a list of deals.

  PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY checks whether owning the deals in the account and the deals you send would violate any dependency rules. You can also send in an account and a plan, and this opcode performs the validation checks for the deals in the account and the deals in the plan.

• Pass in a list of deals to validate against another list of deals.

  PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates that owning both sets of deals 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 deals in that account do not violate any deal 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 deals in the /account and the deals in the plan.

If any deal violates a dependency relationship, the operation fails.

To validate two sets of deals, send in /account -1 (without a POID); PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates the deals. If any of the deals violates a dependency relationship, the operation fails.

Deal Dependency Validations Involving Inactive or Canceled Products or Discounts

By default, BRM does not perform deal dependency validations for inactive or canceled products or discounts.

To enforce deal dependency validations for inactive or canceled products or discounts, you need to configure BRM to do the following:

• Maintain any deleted products in the /purchased_product objects to allow product-level and discount-level validations.

  To do so, set the value of the keep_cancelled_products_or_discounts entry to 1 in the pin.conf configuration file for Connection Manager. See "Specifying to Delete Canceled Products" for more information.

• Perform prerequisite and mutual exclusivity rule dependency validation.

  To do so, verify that the validate_deal_dependencies entry is uncommented in the pin.conf configuration file for Connection Manager. See "Enabling Deal Dependencies Validation" for more information.

• Perform deal dependency validations on inactive or canceled products and discounts.

  To do so, enable the ProductLevelValidation business parameter in the /config/business_params object in the BRM_Home/sys/data/config/bus_params_subscription.xml file.

  By default, ProductLevelValidation is set to disabled. See "Enabling Deal Dependency Validations for Inactive or Canceled Products and Discounts" for more information.

Note:

BRM performs the purchase time dependency validations between deals irrespective of the value of the ProductLevelValidation parameter.

How BRM Acts on Deal Dependencies for Inactive or Canceled Products and Discounts

When BRM is appropriately configured to enforce deal dependency validations for inactive or canceled products or discounts and a deal A is the prerequisite of deal B:

• If deal B is owned by the account, BRM will not allow cancellation or inactivation of any products or discounts of deal A unless all the products or discounts of deal B are in canceled or inactive state.

• If any product or discount of deal A is in the canceled state, deal B cannot be purchased.

• If any product or discount of deal A is in the inactive state, deal B can be purchased only in an inactive state; that is, all products and discounts of deal B have to be purchased as inactive. All the products or discounts in prerequisite deal A should be first activated before activating the products or discounts in deal B.

Note:

BRM does not perform validations between the validity dates of the prerequisite and dependent deals.

Enabling Deal Dependency Validations for Inactive or Canceled Products and Discounts

Use the pin_bus_params utility to configure the ProductLevelValidation business parameter to enable deal dependency validations for inactive or canceled products and discounts. To do so:

1. Create an editable XML file from the subscription instance of the /config/business_params object by using the following command:

   pin_bus_params -r BusParamsSubscription bus_params_subscription.xml

   BRM places the XML file named bus_params_subscription.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

2. Locate the ProductLevelValidation entry in bus_params_subscription.xml.out.

3. Set the value of ProductLevelValidation as required. Your entry should be one of the following:

   • <ProductLevelValidation>enabled</ProductLevelValidation>

   • <ProductLevelValidation>disabled</ProductLevelValidation>

4. Save this updated file as bus_params_subscription.xml.

5. Load the modified XML file containing the business parameters for subscription into the appropriate /config/business_params object in the BRM database.

   pin_bus_params bus_params_subscription.xml

   You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see the description for pin_bus_params in BRM Developer's Guide.

6. Read the object with the testnap utility or Object Browser to verify that all fields are correct.

   For more information on reading objects by using the Object Browser, see BRM Managing Customers. For instructions on using the testnap utility, see BRM Developer's Guide.

7. Stop and restart Connection Manager. See the description for starting and stopping the BRM system in BRM System Administrator's Guide.

8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Canceling Deals

You can cancel all the products in a deal in one operation, or you can cancel individual products. Canceling a deal is particularly useful when a customer wants to upgrade. You can cancel all of the products in the old deal as a group before purchasing the new deal for the customer's account. You can cancel a deal immediately or backdate the cancellation of a deal to a date earlier than the current date. You use Customer Center to cancel deals.

Note:

• After you cancel a deal, you cannot reactivate the deal or the products it contains.

• You cannot cancel a required deal. Instead, either transition to a new plan or close the service associated with the deal. See "About Plan Transitions in BRM".

How Deals Are Canceled

To cancel a deal, use the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode. This opcode cancels all products and discounts associated with the specific deal and then cancels the deal itself. If more than one instance of a deal has been purchased for the account or service, each deal instance must be canceled individually.

To cancel a deal, PCM_OP_SUBSCRIPTION_CANCEL_DEAL does the following:

1. Opens a transaction.

2. Checks if the deal is required within the corresponding plan. If so, the cancellation is not permitted.

3. From the input flist, retrieves the PIN_FLD_PACKAGE_ID, PIN_FLD_SERVICE_OBJ, name, and type of the products and discounts associated with the deal.

   If the deal being canceled has the same PIN_FLD_PACKAGE_ID and PIN_FLD_SERVICE_OBJ as another deal, then PIN_FLD_DEAL_OBJ is also required to uniquely identify the deal.

4. Validates that the deal is available for cancellation.

5. For each product, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls the PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT opcode to cancel the product.

   The opcode does not directly delete customized products in the deal whose base products are also included in the deal. Customized products are automatically deleted when their base products are deleted by PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT. The opcode does delete customized products whose base products are not included in the deal.

6. For each discount, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls the PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT opcode to cancel the discount.

7. Creates an /event/billing/deal/cancel object for auditing purposes.

8. If the deal cancel is successful, returns the /account POID and the POID of the /event/billing/deal/cancel event.

Managing Plans

You add new services to an account by purchasing a plan. Plans provide the deals, products, and discounts needed for configuring the new services.

You can also backdate plan purchases.

You also use plans to set and change credit limits in an account. For more information, see "Changing a Customer's Credit Limit".

BRM allows you to transition accounts from one plan to another.

About Plan Transitions in BRM

You specify the rules that govern the transition of an account from the source plan to a target plan. BRM imposes certain limitations on when accounts can transition to or from other plans. It requires you to define plan transition rules for each plan-to-plan transition by manually configuring the transition rules in Pricing Center.

BRM uses the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode to transition accounts from the current (source) plan to a specified (target) plan. When a CSR transitions an account from one plan to another, Customer Center calls the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode to obtain a list of all the available plans to which the account can transition. The opcode then attempts the plan-to-plan transition.

You provide the required transition type as the value of PIN_FLD_TRANSITION_TYPE in the input flist for PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode. The transition type can be defined as one of the following:

• Not defined, set as (0).

• Upgrade, set as (1).

• Downgrade, set as (2).

• Generation change, set as (3). See "Defining a Generation Change for Plans".

• Custom transition type. See "Creating Custom Transition Types for Deals and Plans".

You can use the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode to customize plan transitions.

Factors to Note about Plan Transitions in BRM

When you transition accounts from one plan to another plan in BRM:

• If the transition type is a generation change, the two plans do not have to share the same primary service. If the transition type is an upgrade or a downgrade, the two plans must share the same primary service.

• If the source and target plans are a valid combination, you can configure the transition rule such that the source plan retains the non-currency grants as valid to the end of the cycle. To do so, set the value of PIN_FLD_FLAGS input to the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode to be PIN_SUBS_TRANSITION_CONTROL_ROLLOVER. (See pin_subscription.h.)

• BRM checks the status of any add-on deals (deals that are not part of the source plan) owned by the account. If all add-on deals are canceled, BRM closes the associated services and transitions the account to the target plan. If the add-on deals are not canceled, BRM returns an error and retains the source plan for the account. Therefore, you must first cancel all add-on deals owned by the account before you transition the account to the target plan.

The following restrictions apply to plan transitions in BRM:

• You cannot backdate a plan-transition or generation change to a prior period.

• If you delete a service from a plan, BRM closes that service and sets its status to PIN_STATUS_FLAG_DUE_TO_TRANSITION. You cannot change the status of a closed service.

• BRM does not transfer extended rating attributes (ERAs) data during a plan transition or a generation change. For example, if you have an account with ERA on friends and family and perform a plan transition or generation change, the ERA data is not transferred to the new plan.

• BRM, by default, retains the credit limits associated with the source plan for an account when the source and target plans for that account are associated with the same balance group but each plan has different credit limits. To set new credit limits for the account, you can customize PCM_OP_CUST_POL_TRANSITION_PLAN opcode by doing the following:

  1. Set the credit limit in the PIN_FLD_LIMITS array.

  2. Pass this array in the input flist to the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode,

About Defining Plan Transition Rules in Pricing Center

You can manually configure the plan transition rule for each plan-to-plan transition in Pricing Center. For each such plan transition rule you configure in Pricing Center, BRM creates a /transition object to store the rules. For more information on how to define transition rules in Pricing Center, see the Pricing Center Help.

You can perform plan transitions to any plan without creating transition objects. This is a useful approach because for each plan in the BRM system, you need to specify all other plans to which the plan can transition. For example, if you have 300 plans and each plan can transition to or from any other plan, you define 89,401 (299 x 299) plan transition rules, thus creating 89,401 /transition objects.

In addition, every time you add a plan, you must define the transition rules for each existing plan to point to the new plan. As a result, the number of transition rules that you need to define in Pricing Center increases in proportion to any increase in the number of plans you support.

You can perform plan transitions to any plan without creating /transition objects to store the transition rules. See "About Providing Transition Rules Using Policy Opcode".

About Providing Transition Rules Using Policy Opcode

You use the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to automatically enable plan transitions to any plan without /transition objects.

Note:

Customize the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode for only the plan transitions for which a /transition object is not defined in Pricing Center.

When BRM attempts to transition an account and the plan transition rule does not have a /transition object, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the following information you provide in the output flist of the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode:

• Your specification on whether to charge any cancellation fees associated with the source plan for the account and purchase fees for the new product for this transition.

• The Primary Basic Service (PBS) that must apply to the plan transition.

Note:

If you do not provide these values, the opcode searches for a /transition object and if no /transition object exists for the transition rule, the transition will fail.

You can provide these values to handle some plan transitions and configure plan transition rules in Pricing Center for others. For more information on the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode, see BRM Developer's Reference.

Note:

• You can customize plan transitions in this way if the transition does not involve a generation change.

• You cannot customize deal transitions in this manner. Pricing Center must be used to set up transition rules to transition deals.

• You cannot transition plans under certain conditions. For example, you cannot transition a plan when add-on deals that are not part of the original plan are active and owned by the account.

How BRM Transitions Accounts from Source Plans to Target Plans

The PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode transitions accounts from source plans to target plans in the following way:

1. Calls the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to perform any custom validations.

   When the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode completes its actions, it passes the values provided by you to PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode.

2. For plan 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 plan 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 policy opcode.

3. Validates the Primary Basic Service (PBS) that must be applied on the plan transition. For plan 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 policy opcode. For:

   • A regular transition, the two transition plans share a primary service. If not, the transaction fails.

   • For a plan transition that involves a generation change, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN skips this step because the two plans do not have to share the same primary service.

4. Handles the non-currency grants in the source plan 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 plan retains non-currency grants and they are valid to the end of the cycle.

   To do so, the rollover function checks the plan list for the source and target plans and takes the following action:

   • If the plans are in the same plan 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 plans are not in the same plan list, this function searches for all the sub-balance buckets that are impacted by the transition and truncates the bucket to the current time.

5. Acts on the services in the plan-to-plan transition. If any services in the plans are listed as inactive, the transition is aborted.

   • 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 deals are canceled and the deals from PIN_FLD_TO_SERVICE are purchased. Any account-level deals in FROM_PLAN are canceled. Any account-level deals in TO_PLAN are purchased.

6. For the plan 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 plan at 00:00:00 hours at the end of the day of transition.

   Additionally, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN performs these steps:

   • Prepares the input flist for the PCM_OP_CUST_UPDATE_SERVICES opcode 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 plan being phased out ends at January 16, 2004, at 00:00:00 hours.

   • Calls the PCM_OP_ACT_SCHEDULE_CREATE opcode with the above 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, allowing the end date to occur one day later.

     – Allows a Product-End-Delay-For-Plan-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.

7. Charges any cancellation fees for the old deal and purchase fees for the new deal 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 policy opcode).

   Note:

   All cycle fees and non currency resources are always prorated regardless of the product's cancellation proration setting.

8. 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 plans 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.

Customizing Plan Transitions without Configuring /transition Objects

You can customize plan transitions without configuring the /transition object by doing the following:

• Obtain a list of plans available for transition: Use the PCM_OP_CUST_POL_TRANSITION_PLANS policy opcode. Customer Center calls this policy opcode to return the list of plans available for transition.

  This policy opcode takes a plan POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of plans available for transition as output. For more information, see PCM_OP_CUST_POL_TRANSITION_PLANS in BRM Developer's Reference.

• Customize the validation as necessary: This is optional. Use the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to perform any additional validation checks or filters for transitioning plans.

  For example, you can restrict a plan transition to customers from a particular location or require that customers own the first plan for a specific period of time before allowing the transition to a different plan.

• Provide custom values for service and fees: This action is required if you plan to customize plan transitions without configuring the /transition object.

  Modify the output flist of the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to specify the service that must be associated with the plans and whether to waive purchase and cancellation fees associated with the plans. To do so:

  1. Add the PIN_FLD_RESULTS array to the output flist of the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode:

     0 array RESULTS
     1 int FEE_FLAG
     1 str PERMITTED
       
     

  2. Set the PIN_FLD_FEE_FLAG field in PIN_FLD_RESULTS to one of the values in Table 11-2:

     Table 11-2 PIN_FLD_FEE_FLAG Values

     Value	Description
     0	Charge cancellation fees for the old product and purchase fees for the new product.
     1	Waive purchase fees.
     2	Waive cancellation fees.
     3	Waive purchase fees and cancellation fees.

     
     

  3. Set the PIN_FLD_PERMITTED field of this array to the Primary Basic Service (PBS) that must apply to the plan 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"
     

Customizing Account-Level Deals during Plan Transitions

You can customize account-level deals during plan transitions. To do so, provide the associated product information in the PIN_FLD_PRODUCTS input field for the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode. PIN_FLD_PRODUCTS is located in the PIN_FLD_DEAL_INFO substructure of the input flist for the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode.

For more information on PCM_OP_SUBSCRIPTION_TRANSITION_PLAN, see BRM Developer's Reference.

Defining a Generation Change for Plans

A generation change allows you to transition your customers between 2G (second generation) and 3G (third generation) wireless plans and services. Plans are called 2G or 3G depending on whether their primary service type runs on a 2G or 3G wireless network. A 3G wireless network is faster than a 2G network and can transmit video and two-way video telephone calls.

You can use any 2G or 3G service type. For example, the service types could be:

• /service/telco/pdc, a 2G service type based on the Personal Digital Cellular (PDC) standard for digital mobile telephony.

• /service/telco/imt, a 3G service type based on the International Mobile Telecommunications (IMT) standard for 3G wireless communications.

How a Generation Change Works

Whether you are transitioning a customer from a 2G to a 3G plan or from a 3G to a 2G plan, both plans are valid all day on the day of transition. The plan that is being phased out expires at 00:00:00 hours at the end of the transition day; the plan being transitioned to becomes valid at 00:00:00 hours at the beginning of the transition day.

You set the transition rules between two plans. You can also set up standalone deals as add-ons and specify that the transition rules apply to those deals as well.

Important:

• When a transition between two plans is under way, no other transition is allowed between the two plans for the duration of the transition day.

• You can backdate the subscription actions to a prior period in case of a generation change, but doing so can lead to incorrect results.

The New Plan

For the plan replacing the current plan, the following happens at 00:00:00 hours at the start of the transition day:

• The purchase, cycle, and usage start dates are set to 00:00:00 hours at the beginning of the transition day.

• All dependent services and deals associated with the plan are included in the transition.

• Any cycle fees for this plan are charged from 00:00:00 hours at the beginning of the transition day to the end of the billing cycle.

  Note:

  Purchase and cancel fees can be configured to be waived during the transition.

The following happens at transition time or slightly after:

• All configured deals are purchased for the service.

• The new service is provisioned.

The Current Plan

For the plan you are phasing out, the following happens at 00:00:00 hours at the end of the transition day:

• The current service is closed.

• Any dependent services are closed.

• All associated products and dependent services are canceled.

• Forward and arrears cycle fees are prorated from the beginning of the billing cycle to the cancellation time.

Configuring Services for a Generation Change

By default, the service being phased out is active for one day, the day the generation change takes place. You can configure the number of days both services involved in a generation change are active.

To change the number of days the service being phased out is active, configure the prod_end_offset_plan_transition parameter in the billing instance of the /config/business_params object.

To modify the number of days the phased-out service is active:

1. Use the following command to create an editable XML file from the billing instance of the /config/business_params object:

   pin_bus_params -r BusParamsBilling bus_params_billing.xml 
     
   

   This command creates the XML file named bus_params_billing.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

2. Search the XML file for following line:

   <ProdEndOffsetPlanTransition>10</ProdEndOffsetPlanTransition>
     
   

3. Change 10 to the number of days you want the phased-out service to remain active (the default is 10 days). For example, if you change the value to 15, the phased-out service remains active 15 days after generation of the new service. The minimum number of days you can keep a phased-out service active is 1 and the maximum is 31.

   Caution:

   BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM billing configuration.

4. Save and close the file.

5. Use the following command to load the change into the /config/business_params object:

   pin_bus_params bus_params_billing.xml 
     
   

   You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

6. Read the object with the testnap utility or Object Browser to verify that all fields are correct.

   See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for more information on how to use Object Browser.

7. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

About Backdating Subscription Actions

Subscription actions backdating lets you perform certain subscription actions so that the operations take effect on a prior date instead of the date it occurred.

You can perform subscription backdating operations to rectify errors, such as errors committed while performing subscription operations or errors resulting from a high latency between the networks and billing systems.

For example, you might want to backdate a subscription operation when:

• A customer requests a product cancellation on October 30, but the cancellation is not recorded in the BRM system until November 15. The customer is charged for the period of October 30 to November 15.

• A customer requests a product purchase on January 1, but the purchase date is entered in the BRM system as February 1.

BRM supports the following subscription backdating operations:

• Backdated account creation. See "About Backdated Account Creation".

• Backdated account and service status change. See "About Backdated Status Change".

• Backdated product, discount, deal, or plan purchase. See "About Backdated Product, Discount, Deal, or Plan Purchase".

• Backdated product, discount, or deal cancellation. See "About Backdated Product, Discount, or Deal Cancellation".

• Backdated product or discount purchase, usage, or cycle start and end date. See "About Backdated Purchase, Usage, or Cycle End Dates".

• Backdated sequential discount purchase, cancellation, and modification if the validity rules are set to Prorated discount. See the discussion of validity rules in BRM Configuring Pipeline Rating and Discounting.

You can perform subscription backdating by using either of the following methods:

• By using Customer Center.

  Subscription backdating is available only to customer service representatives (CSRs) who have the appropriate permission. Permissioning can be enforced only through Customer Center.

• By passing the backdated date in the PIN_FLD_END_T field of the corresponding subscription opcodes.

About Backdating Beyond the G/L Posting Date

BRM does not allow backdating beyond the G/L posting date.

When you post a G/L report, you prevent backdating adjustments, write-offs, or subscription transactions, prior to the last date you posted the G/L report. This maintains general ledger data integrity. After they are posted, the G/L report updates the /data/ledger_report object. This object records the date of the latest posted G/L report and controls transaction backdating.

You can run G/L reports at any time without posting data. When you do not post data, backdating is not affected.

How Effective Time Is Used to Validate Backdating Operations

BRM does not allow backdating if the date to which you want to backdate the operation on an account, service, product, or discount is prior to the respective effective dates (creation dates).

Rerating of Events for the Backdated Period

Backdated purchase or cancellation of a product or discount automatically triggers rerating. In these cases, BRM uses event notification to create rerate jobs that rerate the events in the product or discount. In all other subscription backdating scenarios, you must either run rerating manually or configure the trigger-dependent rerating. See "About Automatic Rerating of Backdated Events" in BRM Setting Up Pricing and Rating.

For example:

• You might manually need to rerate the usage events that had been rated prior to the backdating action.

  For example, on October 15, a usage event for a product is charged at $2.00 per minute. On November 1, a new product is purchased backdated to September 1. The new product has the usage rate of $1.00 per minute and has a higher priority than the first product. In order for the usage that occurred on October 15 to get rated with the new product, you must rerate the usage events manually.

• If you backdate the cancellation of a shared discount, you will need to rerate the accounts or services in the group, because the accounts or services might have used the discount.

BRM lets you set up trigger-dependent rerating for the backdating operations. See "Setting Up Trigger-Dependent Rerating" in BRM Setting Up Pricing and Rating.

About Backdated Product, Discount, Deal, or Plan Purchase

When you backdate a product, discount, deal, or plan 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.

See "Example of Backdated Product Purchase" and "Example of Backdated Discount Purchase".

BRM does not allow you to backdate the product, discount, deal, or plan purchase if:

• The backdated purchase date is prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".

• The backdated purchase date is prior to the account or service's effective date. See "How Effective Time Is Used to Validate Backdating Operations".

• 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 product purchase prior to December 15, which is the date of the last status change.

  Note:

  • BRM does not apply a fold, rollover product, or bill time discount for the past accounting cycles when you backdate the purchase of the fold, rollover product, or bill time discount.

  • Backdating discounts with discount validity rules are supported only for discounts that are prorated. For more information On discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.

How Sub-balance Buckets Are Created for Backdated Product Purchase

When the backdated product purchase spans beyond the current accounting cycle, multiple cycle events and sub-balance buckets are created. That is, if a backdated purchase of a product spans multiple cycles, one cycle event is created for each cycle and the free resource 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 product to January 15. The product 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 resources for March 1 to April 1.

  Important:

  If you backdate the purchase of a discount 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 by real-time rating to prorate the cycle fee 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 cycle fees in the bill of the current cycle.

Example of Backdated Product Purchase

When you backdate the purchase of a product that includes cycle forward events, cycle forward fees are prorated and applied from the backdated purchase date through the current date.

For example, consider that you create an account on September 1 with the DOM set to the 1. On November 5, you backdate the purchase of a product that has the following details to September 15:

• Cycle forward charge of $9.95.

• Proration set to Charge based on amount used.

The following cycle charges are applied:

• $4.97 for the period from September 15 to October 1 (for 15 days).

• $9.95 for the period from October 1 to November 1.

• $9.95 for the period from November 1 to December 1.

These charges are included in the next bill that gets generated during the bill run on December 1. This bill also includes the charges that are generated for the period of December 1 to January 1.

In the same example, if the product being purchased has cycle arrears fees instead of cycle forward fees, the two cycles until the current cycle are charged as follows:

• $4.97 for the period from September 15 to October 1 (for 15 days).

• $9.95 for the period from October 1 to November 1.

These charges will get included in the next bill that gets generated during the bill run on December 1.

Example of Backdated Discount Purchase

Consider that on April 1, you create an account that owns a product with a cycle forward fee of $50. The cycle fee of $50 for April1 1 to May 1 is applied. On April 16, purchase a discount that applies 10% on the monthly cycle fees, backdated to April 1. A discount of $5 is applied for the period of April 1 to May 1.

Backdating a Product, Discount, Deal or Plan Purchase

To backdate a product, discount, deal, or plan purchase, enter the backdated time in the PIN_FLD_ END_T field of the corresponding opcode. For example, to backdate a product 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.

About Backdated Product, Discount, or Deal Cancellation

The cancellation of a product can be backdated as far back as the purchase date of the product.

Note:

If you backdate a discount purchase to a date prior to the product purchase date, the discount will not be applied in the bill of the current cycle. The discount will be applied in the bill of the next cycle.

Important:

If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be refunded only for the current accounting cycle.

BRM does not allow you to backdate the product, discount, or deal cancellation if:

• The backdated cancellation date is prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".

• The backdated cancellation date is prior to the product or discount's effective date. For example, a product or discount that was purchased to be effective from January 15 cannot have any event on it backdated prior to January 15. See "How Effective Time Is Used to Validate Backdating Operations".

• The backdated cancellation 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 product cancellation prior to December 15, which is the date of the last status change.

  Note:

  • When you backdate the cancellation of a fold, rollover product, or bill time discount, you must run rerating to apply the corrections on the events that occurred after the backdated date.

  • Backdating discounts with discount validity rules are supported only for discounts that are prorated. For more information on discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.

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.

The PCM_OP_SUBSCRIPTION_CYCLE_FORWARD opcode determines the scale values that are used by real-time rating to prorate the cycle fee amount to be refunded. This opcode prorates and applies the cycle fee amount to be refunded when a product or discount is canceled or inactivated.

When you backdate the cancellation of a product with cycle forward events, cycle forward fees are prorated and refunded from the backdated cancellation date.

Example of backdated product cancellation

When you backdate the cancellation of a product 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 product 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 cancellation

On April 1, consider that you create an account that owns a product 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 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 product 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) will be January 15 and February 1 respectively, while the EARNED_START_T and EARNED_END_T for the current cycle will be February 1 and March 1 respectively.

Backdating a Product, Discount, or Deal Cancellation

To backdate a product, discount, or deal cancellation, enter the backdated time in the PIN_FLD_ END_T field of the corresponding opcode. For example, enter the date to which you want to backdate the cancellation in the PIN_FLD_ END_T field of the PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT opcode to backdate a product cancellation.

Getting Data about Deals, Products, Discounts, and Services

Use the following opcodes to get data about deals, products, discounts, and services:

• PCM_OP_CUST_POL_GET_PLANS. See "Getting Plans, Deals, and Products for Purchase".

• PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS. See "Getting a List of Deals, Products, Discounts, and Services".

• PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS. See "Getting a List of Plans and Deals That an Account Owns".

• PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS. See "Reading Data for All Valid Purchased Products and Discounts".

• PCM_OP_SUBSCRIPTION_GET_HISTORY. See "Finding Events Associated with Deals, Products, Discounts, and Services".

Getting Plans, Deals, and Products for Purchase

For more information on purchasing plans, deals, and products, see "Managing Customers' Services and Products".

Use the following opcodes to get plans, deals, and products for customer purchase:

• To get a list of plans for customer purchase, use the PCM_OP_CUST_POL_GET_PLANS policy opcode. This policy opcode chooses the plans to return based on the AAC fields in the input flist.

  If the account is new, this policy opcode gets plans from the new plan list. Otherwise, it uses the addon plan list. If it does not find a list, the default plan list is used.

  You can customize the PCM_OP_CUST_POL_GET_PLANS policy opcode to search the /group/plan_list object by customer type and display the correct plan lists based on the customer type.

  For more information on plan lists, see "About Plan Lists" in BRM Setting Up Pricing and Rating.

• To get a list of deals for customer purchase, use the PCM_OP_CUST_POL_GET_DEALS policy opcode. This policy opcode searches for all /deal objects that are valid (deal END_T = 0 is valid). Each deal in the list is then read and checked to see whether the deal's permitteds array allows the storable object type to purchase it.

  Use the PCM_OP_CUST_POL_READ_PLAN policy opcode to customize deals during account creation. For a given plan, this policy opcode constructs a tree of services, deals, and products associated with that plan. This policy opcode retrieves account-level plans in addition to plans related to services.

• To get a list of products for customer purchase, use the PCM_OP_CUST_POL_GET_PRODUCTS policy opcode. The product's permitteds array is checked for valid storable object types purchasing the product.

Getting a List of Deals, Products, Discounts, and Services

To get the hierarchical relationships of deals, products, discounts, and services associated with an account, use the PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS opcode. This policy opcode is used by Customer Center when a request is made to view a list of an account's deals, products, discounts, and services in a hierarchical format.

By default, PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS does not return ”item” or ”canceled and deleted” products and discounts. Set PIN_FLD_FLAGS in the input flist to get item, canceled, and deleted product and discount instances. For these records, the information about the product and discount instances are retrieved from the /purchased_product and /purchased_discount purchase and cancellation event objects.

Note:

Item, canceled, and deleted product and discount instances are not returned if the product's or discount'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 products and discounts 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 product or discount 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 Plans and Deals That an Account Owns

To get a list of the plans that an account owns, use the PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode. This policy opcode retrieves a list of plans, deals, or both that an account owns.

Note:

The policy opcode returns plans or deals that an account owns. It does not return a plan if the plan has only optional deals. The plan must have at least one purchased deal.

The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode takes an account POID from the input flist and returns a list of all plans, including balance group information and deals the account owns.

If the account contains optional deals that it does not own, those deals are returned with the list as eligible to purchase (PIN_FLD_BOOLEAN value of 0).

The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode can perform additional filtering of plans or deals before they are returned. For example, add filtering logic to this policy opcode to return only inactive optional deals.

Plans and deals that were closed during a transition are not added to the output flist.

Caution:

An account owning more than one instance of a plan is not supported. In this case, this policy opcode returns deals for one of the plans selected at random.

The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode returns deals in a PIN_FLD_DEALS array, even if it found them listed in the account in the older PIN_FLD_DEAL_OBJ field.

Reading Data for All Valid Purchased Products and Discounts

To get the purchased products and discounts for accounts and services, use the PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS opcode.

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 the following values:

• An /account object: The opcode gets all the products and discounts for the account and its services.

• A /billinfo object: The opcode gets the purchased products and discounts associated with the specified bill unit.

• A /service object: The opcode gets the purchased products and discounts that belong to the specified service.

The opcode performs a search based on the specified scope object. Most of the other parameters are filters that work on a particular scope. The input flist looks 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_END_T           TSTAMP [0] (1154415600) Tue Aug  1 00:00:00 2006
0 PIN_FLD_VALIDITY_FLAGS  INT [0] 3
0 PIN_FLD_INCLUSION_FLAGS INT [0] 2
0 PIN_FLD_OVERRIDE_FLAGS  INT [0] 2
 0 PIN_FLD_SELECT_RESULT   INT [0] 
0 PIN_FLD_OVERRIDDEN_OBJ  POID [0] 0.0.0.1 /purchased_product 324706 0 
0 PIN_FLD_DEAL_OBJ        POID [0] 0.0.0.1 /deal 615702 3
0 PIN_FLD_PACKAGE_ID      INT [0] 23
0 PIN_FLD_PRODUCTS        ARRAY [*]     NULL array ptr
0 PIN_FLD_DISCOUNTS       ARRAY [*]     NULL array ptr
  

Use the following parameters to limit the search further:

• To retrieve only products or only discounts, use the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays.

• To retrieve a limited number of fields, specify those fields under the PRODUCTS and DISCOUNTS arrays.

• To retrieve products and discounts with a specific status, pass the PIN_FLD_STATUS_FLAGS field and specify one of the following values:

  • PIN_SUBS_FLG_OFFERING_STATUS_ACTIVE: Retrieves only active offerings.

  • PIN_SUBS_FLG_OFFERING_STATUS_INACTIVE: Retrieves only inactive offerings.

  • PIN_SUBS_FLG_OFFERING_STATUS_CLOSED: Retrieves only closed offerings.

    Note:

    Using multiple values implies the target object can satisfy any of them.

• To retrieve products or discounts valid as of a specified 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 the following values:

  • PIN_SUBS_FLG_OFFERING_VALIDITY_CYCLE: The opcode compares the specified END_T value with the CYCLE_END_T value.

  • PIN_SUBS_FLG_OFFERING_VALIDITY_PURCHASE: The opcode compares the specified END_T value with the PURCHASE_END_T value.

  • PIN_SUBS_FLG_OFFERING_VALIDITY_USAGE: The opcode compares the specified END_T value with USAGE_END_T value.

    Note:

    Using multiple flags implies the target object must satisfy all of them.

• To fetch all eligible products and discounts whose validity period has the latest end time, set the input flist's PIN_FLD_SELECT_RESULT field to 4. If that field is set to another value or omitted, the opcode returns only the first product or discount with the latest end time that it finds.

  Note:

  This opcode fetches product and discount records from the audit table in the BRM database. In that table, records are sorted on the end date of their validity period. Within a particular date group, however, the records are sorted randomly. Therefore, the opcode returns them in a random order. To control the order in which such records are displayed in an invoice, you must customize the invoicing feature to sort the records on an appropriate invoice field.

• To retrieve all eligible account and subscription offerings, pass the PIN_FLD_INCLUSION_FLAGS field on the input flist with one or more of the following values:

  • PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_PRODS: Retrieves all eligible products.

  • PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_DISCS: Retrieves all eligible discounts.

    Note:

    When this field is omitted, only eligible offerings from a specified scope are returned.

• To retrieve only account products and discounts, 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 customized products that override the base product, pass the following two fields in the input flist:

  • PIN_FLD_OVERRIDE_FLAGS field set to PIN_SUBS_FLG_OFFERING_OVERRIDE_PRODS_ONLY. When a valid product POID is passed in the OVERRIDDEN_OBJ field, this flag returns all the customized products that override the specified base product. When a NULL product POID is sent, only the base products are returned. This field is valid for any scope.

  • PIN_FLD_OVERRIDDEN_OBJ set to the POID of the base product that is overridden. This flag searches for all the products that use that base product, including the base product itself. If the OVERRIDDEN_OBJ field is null and the PIN_FLD_OVERRIDE_FLAGS value is set to PIN_SUBS_FLG_OFFERING_OVERRIDE_PRODS_ONLY, only base products are retrieved.

• To retrieve products and discounts for only a single plan, pass the PIN_FLD_PACKAGE_ID field set to the package ID. This field can be used with any scope.

• To retrieve products and discounts for a specific deal, pass the PIN_FLD_DEAL_OBJ field set to the /deal object's POID.

PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS returns all purchased products and discounts, including canceled products and discounts, within the specified parameters.

Finding Events Associated with Deals, Products, Discounts, and Services

Use the PCM_OP_SUBSCRIPTION_GET_HISTORY opcode to retrieve the event history for a deal, product, discount, or service instance associated with an account.

This opcode retrieves events for a deal, product, discount, or service instance in a specified date range. Which events are returned depends on the category specified in the input flist:

• If a deal is specified, a history of all events associated with the specific deal instance is returned for the account. The deal is identified by the PIN_FLD_PACKAGE_ID field in the input flist.

• If a product is specified, a history of all events associated with the specific product instance is returned for the account. The product instance is identified by the PIN_FLD_OFFERING_OBJ field in the input flist.

• If a discount is specified, a history of all events associated with the specific discount instance is returned for the account. The discount 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.

Retrieving Product Details

Use the PCM_OP_PRICE_GET_PRODUCT_INFO opcode to gather product information, including:

• Pipeline rate plan data, if the product includes events configured for pipeline rating.

• Provisioning tag details from the /config/provisioning_tag object or the /config/telco/* object, if a product is configured with a provisioning tag. See "Working with Provisioning Tags" in BRM Setting Up Pricing and Rating.

The opcode searches for the /product object you specify in the input flist. You can specify either the POID of the object or a type-only POID and the product name.

The opcode examines each PIN_FLD_USAGE_MAP array in the product information returned by the search. Based on the content of the array, the opcode searches for and retrieves several different types of rating information:

• The opcode retrieves the content of all real-time rate plans included in the usage map, as well as the content of the /rate objects included in those rate plans.

• If a usage map array includes an event to be rated by a pipeline rate plan, the opcode optionally retrieves pipeline rate plan data from the database. You specify whether the opcode retrieves pipeline rate plan data by passing the FM_PRICE_SUPPRESS_PIPELINE_DATA flag in the opcode call:

  • When the FM_PRICE_SUPPRESS_PIPELINE_DATA flag is set (0x0001) in the opcode call, the opcode retrieves the pipeline rate plan data from the database.

  • When the FM_PRICE_SUPPRESS_PIPELINE_DATA flag is not set (0) in the opcode call, the opcode does not retrieve any pipeline rate plan data.

  For more information on passing flags in opcode calls, see "Understanding the PCM API and the PIN Library" in BRM Developer's Guide.

• If it includes a /rate_plan_selector object, the opcode retrieves its contents.

• If it includes a /rollover object, the opcode retrieves its contents.

The opcode returns the product details in the output flist.

If the /product object includes a provisioning tag attribute, the opcode performs the following:

• For /service/telco/* service types, the opcode retrieves the provisioning tag details from the /config/telco/* object and returns it in the output flist's PIN_FLD_PROVISIONING_TAG_INFO array.

• For all other service types, the opcode retrieves the provisioning tag details from the /config/provisioning_tag object and returns it in the output flist's PIN_FLD_PROVISIONING_TAG_INFO array.

If the product is customized, the PIN_FLD_TAILORMADE field has the value 1. The PIN_FLD_TAILORMADE_DATA field includes information about customized real-time rates, stored as semicolon-delimited, comma-separated pairs of resources and percentages.

Creating Customized /Product Objects

Use the PCM_OP_PRICE_PREP_TAILORMADE_PRODUCT opcode to assemble the data required to create or modify a customized /product object.

The input to the opcode includes the following:

• The POID of the base product to be customized. A type-only POID can be used instead if the product name is supplied.

• The product's customized real-time rate plans and rates.

• The product's customized pipeline pricing data, including rate plan versions, rate plan configurations, price models, model selectors, and model selector rule sets.

• A list of customized pipeline pricing customizations, expressed in string format as semicolon-delimited, comma-separated pairs of resource IDs and percentages. For example, 20% discounts on US dollar and minutes resources are represented as USD,-20;MIN,-20.

During the creation of a customized product, the opcode does the following:

• Retrieves full product and pipeline rate plan details.

• Applies the percentage increase or decrease specified in the customization to the applicable real-time rate's balance impacts.

• Creates a name for the customized product by prepending the current time in seconds (expressed in hexadecimal) to the base product name. See "About Customized Product and Pipeline Pricing Component Names".

• For each pipeline rate plan configuration in the input flist, creates copies of price models and model selectors and applies percentage increases or decreases when necessary.

• Renames customized pipeline pricing components. The code of each component is changed to include a two-letter abbreviation, the current time in milliseconds (expressed in hexadecimal), and a unique integer value. See "About Customized Product and Pipeline Pricing Component Names".

• Returns an flist for the complete customized /product object, including both original and customized data for both real-time and pipeline rate plans.

You pass the output of this opcode to the PCM_OP_PRICE_SET_PRICE _LIST opcode, which commits the customized /product object to the BRM database.

When the opcode is called to modify an existing customized product, the PIN_FLD_POID and PIN_FLD_NAME fields in the PIN_FLD_PRODUCTS array contain the actual values for the existing customized /product object.

The PIN_FLD_TAILORMADE_DATA fields contain the new customization percentages and resources. The opcode updates the current real-time and pipeline rates based on the new percentages. If the changes affect pipeline rate plans that were not previously customized, the opcode creates copies of pricing data that is now required.

Validation Rules for Products, Discounts, Deals, and Plans

• A product cannot be canceled if it belongs to a required deal or to a deal that has a dependency relationship.

• A deal cannot be transitioned if the source service and the target service are not the same service.

• A deal cannot be transitioned if the associated service is inactive.

• A deal cannot be transitioned if it is required in the associated plan.

• A plan cannot be transitioned if the source service and the target service are not the same service or if the service is inactive.

Creating Custom Transition Types for Deals and Plans

By default, BRM provides these transition types for plans and deals:

• Upgrade

• Downgrade

• Generation Change

To add custom transition types for deals and plans:

1. Open the BRM_Home/sys/data/pricing/example/pin_transition_type file in a text editor.

2. Add your custom transition types by using this syntax:

   TransitionIDNumber    TransitionString 
     
   

   where:

   • TransitionIDNumber specifies the ID of the transition type. This value will be visible in the /transition object. Your custom ID numbers must be unique and greater than the number 100. However, they need not be in numerical order.

   • TransitionString specifies the transition name that is displayed in Pricing Center.

   For example, add the following line to create a custom transition type named RED:

   101      RED
     
   

3. Save and close the file.

4. Go to the directory in which you saved the pin_transition_type file and enter the following command:

   load_transition_type [TransitionTypeFile] 
     
   

   where TransitionTypeFile specifies the name and location of the file that contains your custom transition types. By default, the utility uses the pin_transition_type file in the directory from which you run the utility.

   Note:

   For more information on the utility's syntax, see "load_transition_type".

5. Restart Pricing Center.

Your new transition types are loaded into the /config/transition_type object and are displayed in Pricing Center the next time you start it.

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.