7 Rating Implementation and Customization

This chapter provides information on implementing and extending the default Oracle Communications Billing and Revenue Management (BRM) rating functionality.

For general information on rating, see the following topics:

How Rating Works

The PCM_OP_ACT_USAGE opcode is the main BRM rating opcode. In addition, subscription opcodes, such as PCM_OP_SUBSCRIPTION_CYCLE_FORWARD, are used for applying fees.

How BRM Rates and Records Usage Events

BRM uses PCM_OP_ACT_USAGE to rate usage events and record them in the BRM database. For example, this opcode is called when an event is generated for a user login session.

Important:

Do not call PCM_OP_ACT_USAGE directly.

PCM_OP_ACT_USAGE takes as input an /account object POID (Portal Object ID) and a type-only POID that specifies the type of event being recorded.

The PIN_FLD_PRODUCTS array may be included in the input flist to supply or override the list of products that the account owns.

PCM_OP_ACT_USAGE performs the following operations:

  1. Determines whether the event is pre-rated. If the event is pre-rated, the opcode does not rate the event. However, to support taxation for the following adjustments, disputes, and settlements, this opcode performs additional filtering for pre-rated events:

    • Adjustments at the account level, subscription service level, member service level, and item level

    • Item-level disputes

    • Item-level settlements

    This additional filtering consists of checking the event type and performing one of the following activities, as applicable:

    • Adjustments at the account level, subscription service level, member service level: Gets the adjustment amount and then requests deferred or immediate tax calculation for this amount.

    • Item-level adjustments, disputes, or settlements: Evaluates the adjustment, dispute, or settlement amount for each event in the bill item and determines the proportionate amount for taxation. It then requests deferred or immediate tax calculation for this amount.

    BRM chooses whether to use deferred or immediate taxation for adjustments, disputes, and settlements based on the tax_now entry in the Connection Manager (CM) configuration file (pin.conf).

    For event-level disputes and settlements, PCM_OP_ACT_USAGE also processes notification events that include all the account and balance impact information required to reserve disputed resources and to release them upon settlement. For more information, see "Configuring Adjustments, Disputes, and Settlements" in BRM Managing Accounts Receivable.

  2. Adjusts available balances to include reservations. When PCM_OP_ACT_USAGE is called to reauthorize an ongoing prepaid session, an array of the resources currently reserved for the session (the PIN_FLD_RESERVATION_LIST array) is included in the input flist. PCM_OP_ACT_USAGE gets the account balances from which these reservations were made. It then temporarily adds the amount currently reserved for the session to the remaining unreserved amount in each retrieved balance. The sum of these two amounts represents the total amount of the resource available to the ongoing session. This amount is used to rate the reauthorization request.

    For example, customer X has a resource balance of 70 free minutes. Currently, 30 of the minutes are reserved for session A, 30 are reserved for session B, and 10 are unreserved. BRM receives a request to extend session A for 30 minutes. Before the request is rated to determine whether customer X's account has sufficient resources for it, PCM_OP_ACT_USAGE adds the free minutes currently reserved for session A (30) to the account's unreserved free minutes (10) to get the total free minutes available to session A (30 + 10 = 40). In this case, the total free minutes available to session A (40) does not cover the reauthorization request, which is for 60 minutes (30 for the initial authorization + 30 for the extension).

  3. Determines whether the event is discountable. PCM_OP_ACT_USAGE determines whether the event is discountable.

    Note:

    Discountable events include events to which you can apply product discounts, charge sharing, discount sharing, loyalty points, free minutes, and so forth.

    By default, the rating opcodes perform a credit limit check when rating an event. In CALC_ONLY mode, the credit limit check includes the effects of discounts. Because discounts can reduce the balance impact of an event that might otherwise exceed an account's credit limit, the credit limit check for discountable events is deferred to a real-time discounting pipeline.

    To determine whether an event is discountable, PCM_OP_ACT_USAGE checks the usage maps of all the discounts in your system. If at least one map contains the event type of the event being rated, the event is considered discountable.

    Note:

    PCM_OP_ACT_USAGE evaluates discount usage maps using the data that exists as of the most recent restart of the CM. Instances of event types that are newly added to discount usage maps after the most recent CM restart are therefore not found to be discountable. For example, if you add a new real-time usage event type to an existing discount that does not already include a real-time usage event, events of that type are not found to be discountable. You must restart the CM to make these newly added event types discountable.

    If the event is discountable, PCM_OP_ACT_USAGE retrieves all candidate discounts associated with the customer's account. If one or more candidate discounts are returned, the PCM_OP_RATE_EVENT opcode is called with the PCM_OPFLG_RATE_WITH_DISCOUNTING flag set to True. This flag turns off the credit limit check performed by the real-time rating opcodes and defers it to the real-time discounting pipeline.

    See "Rating Events" for more information about PCM_OP_RATE_EVENT.

  4. Determines how much to charge for the event. If the calling opcode does not specify a rate, PCM_OP_ACT_USAGE does the following:

    • Reads the /config/rum object to generate a ratable usage metric (RUM) candidate for rating the event.

    • Calls PCM_OP_RATE_EVENT to rate the event. See "FM Rate Opcodes Called by PCM_OP_ACT_USAGE".

    • Calls the PCM_OP_RATE_POL_POST_RATING policy opcode to apply any modifications to the /event/activity object after rating the event. See "Modifying Rated Events".

  5. Applies the event's balance impact. PCM_OP_ACT_USAGE applies the balance impact of the event to the account balances as follows:

    • If the account has resources set aside in reservations, the resources are consumed from the reservations.

    • If the account does not have reserved resources, the event balance impact is applied to a balance group in the following order based on what is provided in the input flist:

      • If a bill unit is specified in the input flist, the event balance impact is applied to the default balance group of the bill unit.

      • If a bill unit is not specified, the event balance impact is applied to the specified balance group.

      • If a balance group is not specified, the event balance impact is applied to the balance group of the specified service.

    • Otherwise, the event balance impact is applied to the default account-level balance group.

    Note:

    If the PCM_OPFLG_CALC_ONLY or PIN_ACT_CALC_MAX flag is used, the account balance is not updated.
  6. Records the event. If no balance impact is associated with the event, PCM_OP_ACT_USAGE checks the Event Record Map configuration object (/config/event_record_map cached at CM startup time) against the input event type. If the input event type is configured not to be recorded in BRM, the event is not recorded. Otherwise, the event is recorded.

    PCM_OP_ACT_USAGE performs these tasks:

    • Updates the event fields using information from the specified /account object. PCM_OP_ACT_USAGE associates the /item object POID with the event and sets the PIN_FLD_CURRENCY, /payinfo, /bill object POID, and general ledger (G/L ) segment ID.

      Note:

      PCM_OP_ACT_USAGE does not record the PIN_FLD_EXTENDED_INFO substruct field in the event object. To record the PIN_FLD_EXTENDED_INFO substruct in the event object for customizations, modify the PCM_OP_RATE_POL_POST_RATING policy opcode.
    • Obtains information about event fields to be cached for event searches and invoicing.

    • Retrieves a list of remittance accounts that must be remitted for the event.

      Note:

      BRM caches remittance specifications. The PCM_OP_REMIT_GET_PROVIDER opcode is called only when the remittance specification cache is non-null.
    • Checks whether the event is included in your system's event notification list. If it is, calls the opcodes associated with the event in the list.

Specifying the Rating Mode

You control how PCM_OP_ACT_USAGE rates and records usage events by using the following flags:

  • PCM_OPFLG_CALC_ONLY

    When this flag is passed in the opcode call, PCM_OP_ACT_USAGE calculates the amount to charge, factoring in all applicable discounts, but does not apply the amount to the account balance.

  • PIN_ACT_CALC_MAX

    When PIN_FLD_FLAGS is set to PIN_ACT_CALC_MAX, PCM_OP_ACT_USAGE calculates the maximum quantity that can be consumed based on the event owner's current account balance or reserved amount but does not apply the amount to the account balance.

  • PIN_RATE_FLG_RATE_ONLY

    When PIN_FLD_FLAGS in the PIN_FLD_BAL_IMPACTS array is set to PIN_RATE_FLG_RATE_ONLY, PCM_OP_ACT_USAGE uses rated, pre-rated, and tax balance impact types to rate the event.

    Note:

    When PIN_RATE_FLG_RATE_ONLY is set, PCM_OP_ACT_USAGE returns the event's PIN_FLD_BAL_IMPACT array in the output flist.
  • PIN_RATE_FLG_RERATE

    When the PIN_FLD_FLAGS field in the PIN_FLD_BAL_IMPACTS array is set to PIN_RATE_FLG_RERATE, PCM_OP_ACT_USAGE uses rerated tax balance impact types to rate the event.

    Note:

    When PIN_RATE_FLG_RERATE is set, PCM_OP_ACT_USAGE returns the event's PIN_FLD_BAL_IMPACT array in the output flist.
  • PIN_RATE_FLG_OVERRIDE_CREDIT_LIMIT

    When PIN_FLD_FLAGS in the PIN_FLD_BAL_IMPACTS array is set to PIN_RATE_FLG_OVERRIDE_CREDIT_LIMIT, PCM_OP_ACT_USAGE does not check the credit limit.

FM Rate Opcodes Called by PCM_OP_ACT_USAGE

To rate events, PCM_OP_ACT_USAGE calls the following opcodes:

Rating Events

To rate an event, PCM_OP_RATE_EVENT does the following:

  • When the optional time-stamp field PIN_FLD_WHEN_T is present in the PCM_OP_RATE_EVENT input flist, PCM_OP_RATE_EVENT searches for the price list that is valid at the time specified in the field. It uses the price list to rate the event.

  • PCM_OP_RATE_EVENT sets the optional PIN_FLD_VALID_TO field for CALC_MAX and CALC_ONLY operations. This field is used to limit prepaid product authorizations to a specific time period for non-duration RUMs.

  • If a product or discount starts on first usage and its validity period has not been set, selects the product or discount as a candidate for rating if the purchase time is equal to or earlier than the event time. The opcode returns the first-usage products that are used to rate the event in the PIN_FLD_FIRST_USAGE_PRODUCTS array in the output flist.

  • If rating impacts a balance whose validity period has not yet been set (such as non-currency balances that start on first usage or relative to when they are granted), calculates the resource balance validity period. If resource validity end time is restricted to the granting product's or discount's end time, this opcode compares the calculated end time with the product's or discount's end time and returns the earlier of the two in the output flist.

  • Locates any rollover objects for events and returns details of the rollover object to the calling opcode.

  • Determines whether it should perform a credit limit check. PCM_OP_RATE_EVENT performs a credit check unless:

    • The event is discountable or involves multiple RUMs. In CALC_ONLY mode, the credit limit check is deferred to the real-time pipeline.

    • The event being rated includes the PIN_RATE_FLG_NO_CREDIT_LIMIT_CHECK flag, the applicable rate is a credit limit override rate, or the event is a refund event. (The PIN_RATE_FLG_NO_CREDIT_LIMIT_CHECK flag is set if the event associated with the plan does not use a credit limit. You specify to not use a credit limit in Pricing Center when you set up a plan.)

    PCM_OP_RATE_EVENT sets a value in the PIN_FLD_CHECK_CREDIT_LIMIT field in its output flist to indicate whether a credit limit check should occur, where it should occur, and how the real-time discounting pipeline should handle the event if the credit limit occurs there. Flag values can be summed.

    • PIN_RATE_CREDIT_LIMIT_NEEDED (0x1000) indicates that a credit limit check should be performed.

    • PIN_RATE_CREDIT_LIMIT_LOCATION_CRE (0x100) indicates that the credit limit check is handled by PCM_OP_RATE_EVENT.

    • PIN_RATE_CREDIT_LIMIT_LOCATION_RTP (0x200) indicates that the credit limit check is deferred to the real-time discounting pipeline.

    • PIN_RATE_NO_CREDIT_LIMIT_DISCOUNT_ONLY (0x0): Indicates, for events that are processed by the real-time discounting pipeline, that no credit limit check should occur. This flag is used for events sent to the pipeline for discounting only, typically when rating in normal, as opposed to CALC_ONLY, mode.

    • PIN_RATE_CREDIT_LIMIT_CHECK (0x1): Indicates, for events that are processed by the real-time discounting pipeline, that a credit limit check should be performed by the FCT_CreditLimitCheck module. This flag is typically used for prepaid authorization. If the full amount cannot be authorized, FCT_CreditLimitCheck determines the maximum amount that can be authorized.

  • If the event qualifies for a discount, sends the event to a real-time discounting pipeline.

  • Calls the PCM_OP_RATE_TAX_CALC opcode to calculate taxes.

  • When rating cycle forward events, calculates fees and refunds based on scale values, proration settings, and rates. The opcode uses the values of PIN_FLD_SCALE and PIN_FLD_ORIGINAL_SCALE passed to it by Subscription Manager to determine the scale to apply. These values are set differently depending on whether they are used for applying cycle fees or refunding them.

    The opcode calculates the cycle fee or refund based on the following formula:

    PIN_FLD_SCALE * PIN_FLD_ORIGINAL_SCALE * Rate

    The opcode retains the value of PIN_FLD_ORIGINAL_SCALE that is passed to it, but it sometimes changes the value of PIN_FLD_SCALE depending on the proration setting.

    To calculate cycle fees, the opcode sets PIN_FLD_SCALE to the following values:

    • When purchase proration is set to Do not charge for this cycle, PIN_FLD_SCALE is set to 0.

    • When purchase proration is set to Charge for the entire cycle, PIN_FLD_SCALE is set to 1.

    • When purchase proration is set to Calculate the charge based on the amount used, PIN_FLD_SCALE retains the value passed to the opcode by Subscription Manager.

    To calculate cycle fee refunds, the opcode sets PIN_FLD_SCALE to the following values:

    • When cancel proration is set to Do not charge for this cycle, PIN_FLD_SCALE is set to 1.

    • When cancel proration is set to Charge for the entire cycle, PIN_FLD_SCALE is set to 0.

    • When cancel proration is set to Calculate the charge based on the amount used, PIN_FLD_SCALE retains the value passed to the opcode by Subscription Manager.

    The opcode includes PIN_FLD_SCALE and PIN_FLD_ORIGINAL_SCALE in its output flist. These fields are stored in the /event/billing/product/fee/cycle object.

Retrieving Product Lists

To get the list of products for an event, PCM_OP_ACT_USAGE calls the PCM_OP_RATE_GET_PRODLIST opcode. This opcode gets a list of purchased products (/purchased_product objects) for an account based on the combination of service and event type in its input flist. It returns a list of base products and valid customized products.

In its initial search for products, the opcode uses the event object and optional service object in the flist to determine which products it retrieves:

  • If the input flist does not include a service object POID, the opcode finds all purchased products for the account.

  • If a service is included in the input flist, the opcode selects products that apply to the specified service and the event type in the flist. For example, if the event type is /event/session/telco/gsm and the service is /service/telco/gsm/telephony, the opcode finds products that apply to GSM usage.

After retrieving the list of products, the opcode checks if any of the products are overridden by a customized product that is currently valid. If a product is overridden by a valid customized product, it is removed from the list and not returned by the opcode. The valid customized product is included in the list instead.

If a product is retrieved and its validity period is not yet initialized, information about the product's purchase, cycle, and usage start and end times is returned in the purchase, cycle, and usage *_START_DETAILS and *_END_DETAILS fields respectively.

Generating Ratable Usage Metrics

Use the PCM_OP_ACT_GET_CANDIDATE_RUMS opcode to generate a ratable usage metric (RUM) that can be used to rate the event. A candidate RUM specifies the name, quantity, and unit of measurement for each resource used in the event. For example, an IP fax event's RUM might include the information in Table 7-1:

Table 7-1 Generating Ratable Usage Metrics

Name Quantity Unit

duration

2

minutes

page_count

10

pages

byte_count

9568

bytes


PCM_OP_ACT_GET_CANDIDATE_RUMS performs the following operations:

  1. Calls the PCM_OP_ACT_POL_SPEC_CANDIDATE_RUMS policy opcode to calculate RUMs. See "Customizing How to Calculate RUMs".

  2. Reads the /config/rum object to retrieve the list of valid RUMs for the specified event type.

  3. Combines the configuration data with the event data to produce a RUM candidate for rating the event.

  4. Returns the following data about each RUM:

    • RUM name

    • Quantity to rate

    • Unit (seconds, minutes, bytes)

About Calculating the Maximum Available Usage

BRM uses the PCM_OP_ACT_CALC_MAX_USAGE opcode to calculate the maximum available usage based on one of the following:

  • The account's credit limit and current account balance.

  • The amount reserved for the session.

For example, this opcode is called by the PCM_OP_ACT_AUTHORIZE opcode to calculate the maximum possible duration of a call to prevent prepaid customers from exceeding their current account balance.

PCM_OP_ACT_CALC_MAX_USAGE performs the following operations:

  1. Specifies a huge quantity for the event RUM.

  2. Calls PCM_OP_ACT_USAGE with PIN_FLD_FLAG set to PIN_ACT_CALC_MAX to rate and return the maximum quantity available based on the current balance or the reservation amount. See "How BRM Rates and Records Usage Events".

  3. Returns PIN_FLD_QUANTITY set to one of the following:

    • The maximum usage allowed based on the user's available balance and credit limit or reserved amount.

    • -1 to indicate unlimited usage. This value is returned only when all of the account's available resources can be consumed.

      Note:

      By default, for a duration-type RUM, PCM_OP_ACT_CALC_MAX_USAGE limits the maximum duration to 24 hours. For example, if a user's available balance enables the user to make a call longer than 24 hours, this opcode returns -1. To configure the duration maximum, set the fm_act max_qty_for_duration entry to a value greater than 24 (hours) in the CM configuration file.

This opcode propagates any errors returned from PCM_OP_ACT_USAGE.

About Currency Conversion

During rating, currency conversion is handled by the following opcodes:

  • The PCM_OP_BILL_CURRENCY_CONVERT_AMOUNTS opcode converts the currency according to the conversion rate defined in the /config/currency/conversionrates object. You can set multiple time periods for conversion rates.

    This opcode fails if the specified time is not within the time range or if the source or destination currency is invalid. The ERROR_NOT_FOUND error code is returned.

  • The PCM_OP_BILL_CURRENCY_QUERY_CONVERSION_RATES opcode retrieves the conversion rates from the /config/currency/conversionrates object. This opcode is called by the PCM_OP_BILL_CONVERT_AMOUNTS opcode.

    This opcode fails if no conversion rate is specified between the source and destination currency types. The ERROR_NOT_FOUND error code is returned.

About Applying Cycle Forward Fees

To apply a cycle forward fee to a balance group, use the PCM_OP_SUBSCRIPTION_CYCLE_FORWARD opcode.

This opcode is called to charge or refund cycle forward fees (for example, when a product or discount is purchased, canceled, activated, or inactivated).

PCM_OP_SUBSCRIPTION_CYCLE_FORWARD performs the following operations:

  1. When a product or discount is purchased or activated during the cycle, determines scale values that are used by real-time rating to prorate the cycle forward fee amount to be charged.

  2. When a product or discount is canceled or inactivated during the cycle, determines scale values that are used by real-time rating to prorate the cycle forward fee amount to be refunded.

  3. Uses customized products when valid to calculate fees or refunds. 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.

  4. When a rate change is scheduled for the next or current cycle, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD gets a list of rates and the period in which they are applicable and calculates the correct charges.

  5. Calculates and sets CYCLE_FEE_START_T and CYCLE_FEE_END_T to the next period, if applicable.

  6. After all the products and discounts and their cycle forward rates are determined, it sends the information to PCM_OP_ACT_USAGE to rate and apply the charges.

    Note:

    If the product or discount starts on first usage (when the customer first uses the product or discount) and its validity period has not yet been set, PCM_OP_SUBSCRIPTION_CYCLE_FORWARD does not call PCM_OP_ACT_USAGE, and cycle fees are not applied.
  7. For auditing purposes, it creates /event/billing/product/fee/cycle/cycle_forward_type objects, where type is the frequency of the cycle forward charge (for example, daily, weekly, monthly, bimonthly, quarterly, semiannual, or annual).

  8. If successful, it returns the POIDs of the /account object and the /event/billing/product/fee/cycle/cycle_forward_type event.

About Applying Cycle Arrears Fees

To apply a cycle arrears fee, use the PCM_OP_SUBSCRIPTION_CYCLE_ARREARS opcode.

Note:

Cycle arrears fees are applied only for a single month.

PCM_OP_SUBSCRIPTION_CYCLE_ARREARS performs the following operations:

  1. When products or discounts with cycle fees are canceled or inactivated during a cycle, calculates the scale to prorate the cycle arrears fee amount to be charged.

  2. When a rate change occurred in the previous or next cycle, gets a list of rates and the period in which they are applicable and calculates the correct charges.

  3. Uses customized products when valid to calculate fees or refunds. If a customized product is valid for only part of a cycle, it contributes a portion of the total charge or refund based on the length of its validity.

  4. After all the product and discount cycle arrears rates are determined, sends the information to PCM_OP_ACT_USAGE to rate and apply the charges.

    Note:

    If the product or discount starts on first usage (when the customer first uses the product or discount) and its validity period has not yet been set, PCM_OP_SUBSCRIPTION_CYCLE_ARREARS does not call PCM_OP_ACT_USAGE, and cycle fees are not applied.
  5. Creates the /event/billing/product/fee/cycle/cycle_arrears event for auditing purposes.

  6. If successful, returns the POIDs of the /account object and the /event/billing/product/fee/cycle/cycle_arrears event.

Customizing the Cycle Interval for Products

To customize the time interval for applying cycle forward and cycle arrears fees for a specified product, use the PCM_OP_SUBSCRIPTION_POL_SPEC_CYCLE_FEE_INTERVAL policy opcode.

This policy opcode is called by PCM_OP_SUBSCRIPTION_CYCLE_FORWARD and PCM_OP_SUBSCRIPTION_CYCLE_ARREARS. The type of cycle event is passed in the PIN_FLD_SCOPE field in the input flist.

By default, this policy opcode is an empty hook to facilitate customization of the cycle forward and cycle arrears start (CHARGED_FROM_T) and end dates (CHARGED_TO_T) for a specific product. The start and end dates provided are used by rating opcodes to calculate the scale to determine the cycle fee amount to charge or refund.

The PIN_FLD_SCALE value in the input and output flists is the original charge scale and is used only to calculate the refund scale.

For example, if a product is purchased on April 1, 2009, with a monthly cycle forward fee of $30 and the purchase, usage, and cycle end dates are set to April 20, 2009, the cycle fee amount is based on the scale for the period April 1, 2009, to April 20, 2009 (20 days) divided by the unit interval from April 1, 2009, to April 30, 2009 (30 days). The cycle fee charged is 20/30 * $30, or $20.

If the product is canceled on April 15, 2009, the refund amount is based on the scale for the period April 15, 2009, to April 20, 2009 (5 days) divided by the unit interval from April 1, 2009, to April 20, 2009 (20 days). Because the refund amount is refunded from the charged amount ($20), the refund is 5/20 * (20/30 * $30), or $5. Here, the scale value 20/30 is the original charge scale or the period the product was valid during the cycle.

To change the scale (for example if you do not want to refund the full amount), change the start and end dates. The refund scale is calculated based on the dates that you provide.

About Restricting the End Time of Granted Resources That Start on First Usage

Note:

This is an optional task that you perform only when you configure the validity periods of granted resources to start on first usage. For more information, see "About Balance Impacts That Become Valid on First Usage".

You can configure BRM to automatically restrict the validity period of granted resources to end no later than the end time of the product or discount that grants the resource.

When you configure resource validity to start on first usage and end on a date relative to the start date (when first usage occurs), you cannot know the actual end date when setting up the rate plan. Restricting the resource end time to the product or discount end time ensures that the resource cannot continue to be consumed after the product or discount expires.

Note:

When a product or discount is canceled, the validity period end time of resources granted by that product or discount is set to the time of the cancellation.

When you restrict resource validity end time, BRM sets the end time to the product or discount end time at the time of the grant. When the customer consumes the granted resource for the first time, the relative end time is calculated:

  • If the calculated end time is later than the granting product or discount end time, the resource validity period uses the product or discount end time.

  • If the calculated end time is earlier than the granting product or discount end time, the resource validity period uses the calculated end time.

    Important:

    If you restrict resource validity end time, you must do so for both real-time rating and pipeline rating.

To restrict resource validity end time, see "Configuring Real-Time Rating to Restrict Resource Validity End Time".

Configuring Real-Time Rating to Restrict Resource Validity End Time

In real-time rating, you restrict resource validity end time to the end time of the product or discount that grants the resource by modifying a field in the multi_bal instance of the /config/business_params object.

You modify the /config/business_params object by using the pin_bus_params utility.

To restrict resource validity end times to product or discount end times:

  1. Run the following command, which creates an editable XML file from the multi_bal instance of the /config/business_params object:

    pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml 
    

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

  2. Search the XML file for following line:

    <RestrictResourceValidityToOffer>FALSE</RestrictResourceValidityToOffer>
    
  3. Change FALSE to TRUE.

    Caution:

    BRM uses the XML in this file to overwrite the existing multi_bal 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 multi-balance configuration.
  4. Save the file and rename it from bus_params_multi_bal.xml.out to bus_params_multi_bal.xml.

  5. Run the following command, which loads the change into the /config/business_params object:

    pin_bus_params bus_params_multi_bal.xml
    

    Run this command from the BRM_Home/sys/data/config directory (where BRM_Home is the directory in which BRM is installed), which includes support files used by the utility.

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

  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.

About Applying Folds

For background information about folds, see "About Fold Events".

Use the PCM_OP_SUBSCRIPTION_CYCLE_FOLD opcode to apply balance impacts for fold events.

PCM_OP_SUBSCRIPTION_CYCLE_FOLD performs the following operations:

  1. Calls the PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD policy opcode to get the order in which to fold the account's resources. By default, folds are applied in ascending order of the resource IDs.

  2. Checks the value of the resource's PIN_FLD_APPLY_MODE field in the /config/beid object to see whether the resource is specified to be rolled over. For more information, see "Specifying Which Resources to Fold".

  3. Applies folds for all of the account's balance groups and also for each resource in the balance group that is specified to be rolled over. However, if a resource ID is specified in the input flist, only that resource is folded.

  4. After applying the balance impacts, creates /event/billing/cycle/fold event for auditing purposes.

  5. If successful, returns the POIDs of the /account object and the /event/billing/product/fee/cycle/fold event.

About Applying Folds Only For Account-Level Products

If a fold is configured at account level, the fold is applicable to all the services in the account. The fold is then applied to the first service that is retrieved. If the resource balance is non-zero after applying the fold to the first service, the fold is applied again to the next service until the resource balance is zero.

To apply the fold only to account-level products, you can configure an account-level balance group to track the resource that you want to fold. The fold is then applied to only the products associated with the account-level balance group and not to all the services in the account.

Customizing How Folds Are Applied

To customize how folds are applied, use the PCM_OP_SUBSCRIPTION_POL_PRE_FOLD policy opcode.

By default, this policy opcode is an empty hook provided to facilitate any customization before folding the currency or non-currency resources. For example, when billing is run, this policy opcode is called to verify that the pin_cycle_fees utility has applied cycle fees to an account.

Customizing the Order to Apply Folds

To customize the order in which folds are applied, use the PCM_OP_SUBSCRIPTION_POL_SPEC_FOLD policy opcode.

By default, resources are folded in ascending order based on the resource ID. This policy opcode enables you to change the order in which resources are folded.

For example, you can fold resources in descending order of the resource IDs. To do this, sort the PIN_FLD_BALANCES array and return the sorted array.

The following example shows the PIN_FLIST_SORT statement for sorting the balances array in descending order:

*out_flistp = PIN_FLIST_COPY(i_flistp, ebufp);
s_flistp = PIN_FLIST_CREATE(ebufp);
PIN_FLIST_ELEM_SET(s_flistp, (void *)NULL, PIN_FLD_BALANCES, PIN_ELEMID_ANY, ebufp);

PIN_FLIST_SORT(*out_flistp, s_flistp, 1, ebufp);

This policy opcode returns the contents of the input flist including the POID of the /balance_group object and the balance array sorted in ascending order.

Specifying Which Resources to Fold

You can specify which resources are impacted by fold events. This enables you to exclude folding resources that do not need to be folded.

To specify the resources to fold, you set the PIN_FLD_APPLY_MODE parameter for the resources in the resource configuration file (BRM_Home/sys/data/pricing/example/pin_beid).

The PIN_FLD_APPLY_MODE parameter can take the following values:

  • 1 indicates the resource will be folded, if appropriate.

  • 0 indicates the resource will not be folded.

By default, folds are enabled for all resources in the pin_beid file.

After modifying the pin_beid file, load the contents of the file into the /config/beid object in the BRM database by running the load_pin_beid utility.

For more information, see the pin_beid file and "load_pin_beid".

Customizing Which Resources to Fold When Products Are Canceled

The PCM_OP_SUBSCRIPTION_POL_PREP_FOLD policy opcode prepares the list of resources that must be folded when a product is canceled. This opcode is called when a product is canceled, and it performs the following functions:

  • Checks the canceled product.

  • Creates a list of resources affected by the cancellation that must be folded.

  • Calls PCM_OP_SUBSCRIPTION_CYCLE_FOLD and passes the list of resources as the input.

If you do not want to fold resources after a product is canceled, customize this policy opcode by removing or commenting out the code in the fm_subscription_pol_prep_fold.c file.

Assigning Rate Plans and Impact Categories to Events

Use the PCM_OP_ACT_POL_SPEC_RATES policy opcode to map an event to a rate plan and impact category.

Note:

Ensure that your rate plan structure uses custom event analysis for the event.

The opcode that calls the PCM_OP_ACT_POL_SPEC_RATES policy opcode passes in the inherited information for an event. For example, to rate a password, the PCM_OP_CUST_SET_PASSWD opcode specifies the inherited password information. The PCM_OP_ACT_POL_SPEC_RATES policy opcode specifies that the password is to be rated.

Though most custom rating functionality is now in the rate plan selector, some special cases require you to use the PCM_OP_ACT_POL_SPEC_RATES policy opcode. In such a case, you must:

  1. Map your custom events to BRM opcodes in the BRM_Home/sys/data/config/pin_spec_rates file, and then load the file into the BRM database by using the load_pin_spec_rates utility.

  2. Define your custom impact categories in the BRM_Home/sys/data/config/pin_impact_category file, and then load the file into the BRM database by using the load_pin_impact_category utility.

This configures the PCM_OP_ACT_POL_SPEC_RATES policy opcode and the rate plan selector to return an event's rate plan and impact category to real-time rating.

Rating an Event Based on Extended Rating Attributes

An event can be rated based on extended rating attributes (ERAs) by using either the usage type or the ERA label, as follows:

  • Usage type: You can select a specific rate plan and impact category based on the usage type of an event, such as ERAs. For example, if the usage type for an event is Friends and Family, you can rate that event with a special rate of $1.00 a minute.

  • ERA label: You can select a specific rate plan based on the ERA label. A label is a separate list of ERA values. You can have multiple labels for a single ERA and use a rate plan selector to choose a different rate based on the label.

    For example, you can have a friends and family ERA with two labels, MYFRIENDS and MYFAMILY, and use the rate plan selector to use a different rate for each list.

For more information on ERAs, see "About Extended Rating Attributes".

To rate an event by using special rates based on an ERA, PCM_OP_ACT_USAGE calls the PCM_OP_RATE_POL_PRE_RATING policy opcode before calling PCM_OP_RATE_EVENT.

The PCM_OP_RATE_POL_PRE_RATING policy opcode calls the PCM_OP_RATE_POL_PROCESS_ERAS policy opcode, which in turn calls the PCM_OP_RATE_GET_ERAS opcode.

PCM_OP_RATE_GET_ERAS retrieves the valid ERAs for an event by performing the following operations:

  1. Gets the service and account data for the event from the input flist.

  2. Finds the ERA information in the associated /profile/serv_extrating or /profile/acct_extrating object. The ERA information includes the ERA name, label names, label values, and validity dates.

    Note:

    By default, BRM includes all ERAs in this process, but you can improve real-time rating performance by configuring BRM to omit checking for account-level ERAs, service-level ERAs, or both during rating.
  3. Identifies profile sharing groups that the service or subscription service for the event belongs to. If membership is found and the group is active, the opcode retrieves the ERA information.

  4. For shared profile groups, finds ERA information in the associated /group/sharing/profiles object. The ERA information includes the ERA name, label names, label values, and validity dates.

  5. Checks whether the ERA is valid for the event start or end time, based on the configuration.

    Note:

    The configuration for using event start time for the validity check is determined by the use_prods_based_on_start_t entry in the CM configuration file. See "Using Event Start Time to Determine a Product's Validity".
  6. If the event time is less than the effective time of any of the profiles, searches for that profile in the audit tables to get the correct data matching the event time.

    If the ERA is found to be not valid, the opcode skips the remaining steps.

  7. If the service has a subscription object, reads the service profiles of that subscription object. If the same ERA is found in the service and subscription service, the service ERA takes precedence.

  8. Returns the names of valid ERAs to the PCM_OP_RATE_POL_PROCESS_ERAS policy opcode.

    The PCM_OP_RATE_POL_PROCESS_ERAS policy opcode uses the data retrieved by PCM_OP_RATE_GET_ERAS to do the following:

  9. Compares certain predefined event fields to the values for the ERAs found in the service or account.

    The specific fields compared depend on the service. By default, the policy opcode is configured to work with a GSM telco service and to compare values in the PIN_FLD_CALLING_FROM and PIN_FLD_CALLED_TO fields.

    The policy opcode can be easily configured to work with a GPRS service. In that case, it compares values in the PIN_FLD_ANI and PIN_FLD_DN fields.

    Note:

    Using the PCM_OP_RATE_POL_PROCESS_ERAS policy opcode with services other than GSM and GPRS requires customization. See "Customizing Real-Time Rating for Friends and Family ERAs".
  10. Populates the PIN_FLD_USAGE_TYPE field with the names of the valid ERAs.

    If multiple ERAs are found for service and account profiles, the ERAs can be combined in the PIN_FLD_USAGE_TYPE field. For example, if Closed User Group (CUG) and Friends & Family (FF) are the qualified ERAs for the event, PIN_FLD_USAGE_TYPE can be set to FF_CUG. By default, PIN_FLD_USAGE_TYPE is populated based on the following qualified ERAs:

    • Friends and Family (FF)

    • Closed User Group (CUG)

    • FF + CUG (FF_CUG)

    You can customize the policy opcode to add other ERAs.

  11. Populates the PIN_FLD_PROFILE_LABEL_LIST field with ERA label names. Multiple names are separated by a comma, unless you specified a different separator in the opcode and the rate plan selector.

  12. Returns the output to the PCM_OP_RATE_POL_PRE_RATING policy opcode.

For specific information about how BRM rates friends and family ERAs, see "About Rating Based on Friends and Family ERAs".

The PCM_OP_RATE_POL_PRE_RATING policy opcode returns the output flist with the PIN_FLD_USAGE_TYPE and PIN_FLD_PROFILE_LABEL_LIST fields to the calling opcode.

The event is then rated or discounted based on the ERA value in either PIN_FLD_USAGE_TYPE or PIN_FLD_PROFILE_LABEL_LIST.

If there are multiple valid ERAs and a rate plan selector is being used for the event, the rating or discounting opcode uses the rate plan selector to determine which ERA should be used for rating or discounting. The rate plan selector would use either EVENT.PIN_FLD_USAGE_TYPE or EVENT.PIN_FLD_PROFILE_LABEL_LIST to determine a rate based on the ERA.

Modifying Rated Events

Use the PCM_OP_RATE_POL_POST_RATING policy opcode to modify rated /event objects (for example, change the G/L ID of an event). This policy opcode is called by PCM_OP_ACT_USAGE.

The input flist matches the /event object that you are modifying. The output flist contains the event field to be changed in the rated object.

The following example shows how to change the G/L ID of an event:

STORABLE CLASS /event {
DESCR = "Objects of the event class are created to record the various "
"system-initated and user-initiated events. The events are "
"either related to a specific service or to an account. The "
"event includes generic information such as start and end "
"times as well the various charges that are incurred by the "
"account due to this event.";
SEQ_START = "1";
INT32 PIN_FLD_GL_ID {
DESCR = "GLID associated with this balance impact. "
"Don't care if 0.";
ORDER = 0;
CREATE = Optional;
MODIFY = Writable;
}
}                        CREATE = Optional;
MODIFY = Writable; 

Caution:

Before calling the PCM_OP_RATE_POL_POST_RATING opcode, the PCM_OP_ACT_USAGE opcode stores the balance of a rated event in a balance group cache rather than in the BRM database. If you customize the PCM_OP_RATE_POL_POST_RATING opcode to call a standard opcode to change the balance of the rated event directly in the database or in a different cache, the balance group cache from which the PCM_OP_ACT_USAGE opcode fetches the final balance impact of the event may not reflect the change made by the PCM_OP_RATE_POL_POST_RATING opcode.

Customizing How to Calculate RUMs

Use the PCM_OP_ACT_POL_SPEC_CANDIDATE_RUMS policy opcode to define the customized policy to specify the candidate RUM.

A candidate RUM specifies the name, quantity, and unit of measurement for each resource used in the event. For example, an IP fax event's RUM might have the information in Table 7-2:

Table 7-2 Example

Name Quantity Unit

duration

2

minutes

page_count

10

pages

byte_count

9568

bytes


By default, the PCM_OP_ACT_POL_SPEC_CANDIDATE_RUMS policy opcode copies PIN_FLD_POID and the PIN_FLD_CANDIDATE_RUMS array to the output flist.

You can change the rules to calculate data by using /config/rum. By default, the PCM_OP_ACT_POL_SPEC_CANDIDATE_RUMS policy opcode supports only simple-arithmetic expressions (addition, subtraction, multiplication, and division), but you can add more complex rules to get the event quantity.

If you add a candidate RUM that has the same name as any RUM in the input flist, drop the one from the input flist to ensure that the RUM names are unique.

Rating and Recording Activity Events

BRM uses the PCM_OP_ACT_ACTIVITY opcode to record and rate activity events. This enables BRM to record any type of activity event and any details specific to the event type. Any type of user action can be recorded as an activity event, but it is especially designed to represent events that occur at a single point in time. All activity events are recorded in the system simultaneously.

Note:

For events related to customer service usage over a period, the PCM_OP_ACT_START_SESSION and PCM_OP_ACT_LOGIN opcodes are called. For more information on the PCM_OP_ACT_START_SESSION and PCM_OP_ACT_LOGIN opcodes, see BRM Developer's Reference.

PCM_OP_ACT_ACTIVITY records events for either /account or /service objects. The /account POID must be specified in both cases.

  • When an /account POID is used alone, PCM_OP_ACT_ACTIVITY records the event for an /account object.

  • When both an /account POID and a /service POID are specified, PCM_OP_ACT_ACTIVITY records the event for a /service object.

  • When a NULL /service POID is specified, PCM_OP_ACT_ACTIVITY records an /account event.

PCM_OP_ACT_ACTIVITY records event details in the following ways:

  • Using the generic /event/activity object, the PIN_FLD_DESCR field specifies details of the event in ASCII text format.

  • If this is insufficient, an inherited object type can be created by the user from the /event/activity object and additional fields added to describe a specific type of event in more detail. When an event of that type occurs, the input flist to this operation must use the PIN_FLD_OBJ_TYPE field to specify the type of event object to create and to include the detailed information fields in the PIN_FLD_INHERITED_INFO substructure. This enables any amount of detail to be recorded for any number of event types.

    Note:

    The PIN_FLD_INHERITED_INFO feature requires you to supply a new storable class definition. You determine the fields necessary in the new inherited storable class type and define them by using PIN_MAKE_FLD.

BRM controls what PCM_OP_ACT_ACTIVITY returns by using the following flags:

  • PCM_OPFLG_READ_RESULT

    When this flag is set, PCM_OP_ACT_ACTIVITY returns all fields in the event object, in addition to the POID.

  • PCM_OPFLG_CALC_ONLY

    • When this flag is set, PCM_OP_ACT_ACTIVITY only calculates the rated amount and does not record the event in the BRM database. The opcode returns the fields that would have been used to create the event object. No fields in the database are changed, and the event object is not actually created.

    • When this flag is not set, PCM_OP_ACT_ACTIVITY creates the /event/activity object to record details of the operation.

Managing Sessions

BRM stores information about sessions in /event/session objects in the BRM database.

A session event differs from an activity event in that the start and end of the session event are recorded separately. A session is designed to efficiently track a customer connecting to some type of service for a period of time. For events that occur at a single point in time, the PCM_OP_ACT_ACTIVITY opcode is called. For more information on the PCM_OP_ACT_ACTIVITY opcode, see BRM Developer's Reference.

You use the following Activity standard opcodes to manage sessions:

Starting Sessions

Use the PCM_OP_ACT_LOGIN opcode to start a customer session.

PCM_OP_ACT_LOGIN performs the following operations:

  1. Calls the PCM_OP_ACT_FIND_VERIFY opcode to verify the customer's identity.

  2. Calls the PCM_OP_ACT_START_SESSION opcode to start a login session. See "Recording the Start of a Session".

  3. Returns an flist with the user's /account POID.

This opcode is usually called by PCM_CONNECT, but it is also called directly. If called by PCM_CONNECT, this opcode ignores the database number in the application's pin.conf file and searches all schemas for the account.

Recording the Start of a Session

Use the PCM_OP_ACT_START_SESSION opcode to record the start of a session event.

This opcode records any type of session event object including details specific to the event type. This opcode does not perform rating. Fees for the session event are calculated and applied when the session ends.

Sessions can be started for either /account or /service objects. The /account object must be specified for both cases.

  • When the /account object is used alone, PCM_OP_ACT_START_SESSION starts a session for the /account object.

  • When both /account and /service object POIDs are specified, PCM_OP_ACT_START_SESSION starts a session for the /service object.

  • When a NULL /service object is specified, PCM_OP_ACT_START_SESSION starts a session for the /account object.

Session details can be recorded in the following ways:

  • In the generic /event/session object, the PIN_FLD_DESCR field specifies details of the session in a text format.

  • If that is insufficient, you can create an inherited object type from the /event/session object and add fields to describe a specific type of session in more detail.

    When a session of the specified type occurs, the input flist to PCM_OP_ACT_START_SESSION can specify the type of event object to create with the PIN_OBJ_TYPE field and include the detailed information fields in the PIN_FLD_INHERITED_INFO substructure. This enables any amount of detail to be recorded for any number of session types.

    Within the PIN_FLD_INHERITED_INFO array, the program supplies a new storable class definition. You determine the fields necessary in the new inherited storable class type and define them by using PIN_MAKE_FLD. This procedure is explained in the pcm.h file. PCM_OP_ACT_START_SESSION then automatically creates storable class definitions and supplies updated release files containing the new storable class definitions.

BRM controls how PCM_OP_ACT_START_SESSION records the start of a session event by using the following flags:

  • PCM_OPFLG_READ_RESULT

    When this flag is set, PCM_OP_ACT_START_SESSION returns all fields in the event object in addition to the /account POID.

  • PCM_OPFLG_CALC_ONLY

    • When this flag is set, PCM_OP_ACT_START_SESSION returns the fields that would have been used to create the event object. No fields in the database are changed, and the event object is not actually created.

    • When the flag is not set, PCM_OP_ACT_START_SESSION creates an /event/session object to record the details of the session event.

Updating a Session Event

Use the PCM_OP_ACT_UPDATE_SESSION opcode to update information in a session event.

Note:

The session event object must already have been created by a call to PCM_OP_ACT_START_SESSION or by an opcode that calls that opcode.

This opcode updates the PIN_FLD_DESCR field and any inherited data fields in the session object. Only the fields specified in the opcode's input flist are updated; all other fields in the /event/session object are left unchanged. This opcode uses the generalized PIN_FLD_INHERITED_INFO substruct so it can update /event/session objects of any type.

Recording the End of a Session

Use the PCM_OP_ACT_LOGOUT opcode to record the end of a login session. This opcode calls the PCM_OP_ACT_END_SESSION opcode to end the session and assess any changes.

Rating and Recording Session Events

Use the PCM_OP_ACT_END_SESSION opcode to rate and record the end of a session event.

PCM_OP_ACT_END_SESSION performs the following operations:

  1. Records the session's ending time stamp.

  2. Updates the PIN_FLD_DESCR field and any inherited data fields in the /event/session object.

  3. Returns the following, depending on the flags passed in:

    • When the PCM_OPFLG_READ_RESULT flag is set, the opcode returns all fields in the event object, in addition to the POID.

    • When the PCM_OPFLG_CALC_ONLY flag is set, the opcode returns the fields that would have been used to create the event object. No fields in the database are changed, and the event object is not actually created.

    • When no flags are set, the opcode returns the POID of the event object.

Loading Sessions in Real Time

Use the PCM_OP_ACT_LOAD_SESSION opcode to create, rate, and record a session event as a single operation. This opcode is valuable as a tool to load sessions in real time.

Managing Price Lists

You specify how to charge for the services and products offered by your company by creating a price list. This data is then stored in the BRM database as pricing objects, such as /deal, /plan, and /product objects.

For information on how BRM uses price lists, see "About Creating a Price List".

You can create, retrieve, modify, or delete price list data individually or globally.

Committing Price List Data to the BRM Database

Use the PCM_OP_PRICE_SET_PRICE_LIST opcode to commit all data for a price list, including plans, products, offer profiles, and deals, to the BRM database. This opcode is called directly by Pricing Center, Customer Center, your custom client application, or the loadpricelist utility to load price list data into the database.

PCM_OP_PRICE_SET_PRICE_LIST creates one input flist that contains information for creating, modifying, or deleting the following pricing objects:

  • /best_pricing

  • /deal

  • /dependency

  • /discount

  • /offer_profile

  • /plan

  • /product

  • /sponsorship

  • /transition

PCM_OP_PRICE_SET_PRICE_LIST performs the following in one transaction:

  • Verifies the relationships and dependencies between the pricing objects

  • Commits all objects to the BRM database

  • Prepares a list of all /sponsorship objects that were created or modified and generates the /event/notification/price/sponsorships/modify notification event

  • Prepares a list of all /product objects that were created or modified and generates the /event/notification/price/products/modify notification event

  • Prepares a list of all /offer_profile objects that were created or modified and generates the /event/notification/price/offer_profile/modify notification event

  • Prepares a list of all /discount objects that were created or modified and generates the /event/notification/price/discounts/modify notification event

Retrieving Price List Data from the BRM Database

Use the PCM_OP_PRICE_GET_PRICE_LIST opcode to retrieve price list data from the BRM database. This opcode is called directly by the following applications to retrieve price list data:

  • Pricing Center

  • Customer Center

  • A custom client application

  • loadpricelist, when used with the -r parameter

PCM_OP_PRICE_GET_PRICE_LIST retrieves data about the following pricing objects, rebuilds the product flist, and then returns the data back to the calling application:

  • /best_pricing

  • /deal

  • /dependency

  • /discount

  • /offer_profile

  • /plan

  • /product

  • /sponsorship

  • /transition

By default, this opcode returns all price list data. However, you can specify that the opcode retrieve only /product, /discount, or /sponsorship objects by passing optional input flist fields:

  • To retrieve only /product, /discount, or /sponsorship objects, pass the PIN_FLD_FLAGS input flist field set to 0x10 for /product objects, 0x20 for /discount objects, and 0x40 for /sponsorship objects. You can specify multiple object types by adding these values; for example, set PIN_FLD_FLAGS to 0x30 to retrieve both /product and /discount objects. You can also set the field to 0x0008 to retrieve tailor-made products or other customized pricing data from the BRM system.

  • To retrieve /product and /discount objects based on the service type, pass the PIN_FLD_PERMITTED input flist field set to the desired service type, such as /service/email.

  • To retrieve /product, /discount, or /sponsorship objects based on the object modification time, pass the PIN_FLD_MOD_T input flist field set to the desired time stamp.

If the opcode retrieves customized pricing data, the output flist includes the PIN_FLD_TAILORMADE field in the product array with a value of 1. The output flist also includes PIN_FLD_TAILORMADE_DATA, which lists the resources modified by the customization and the percentage changes.

The purchase, cycle, and usage validity periods of products and discounts are returned in the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays in the output flist. If the purchase, cycle, or usage period has a relative start or end time, the relative offset information is returned in respective START_UNIT and START_OFFSET or END_UNIT and END_OFFSET fields. The unit fields specify the type of offset unit, such as minutes, days, or accounting cycles. The offset fields specify the number of offset units in the relative period.

If the purchase, cycle, or usage period starts on first usage (when the customer first uses the product or discount) and the validity period has not yet been set, the START_OFFSET field has a value of -1.

The validity period of resources is returned in the PIN_FLD_BAL_IMPACTS array in the PIN_FLD_RATES array. If the resource has a relative start or end time, the relative offset information is returned in the PIN_FLD_RELATIVE_START_UNIT and PIN_FLD_RELATIVE_START_OFFSET or PIN_FLD_RELATIVE_END_UNIT and PIN_FLD_RELATIVE_END_OFFSET fields. For resources, the unit fields specify only cycles. The offset fields specify the number of offset cycles in the relative period.

If the resource starts on first usage (when the customer consumes the resource for the first time) and the validity period has not yet been set, the PIN_FLD_RELATIVE_START_OFFSET field has a value of -1

Managing Individual Pricing Objects

You can manage an individual pricing object, such as a /deal object, by using the PCM_OP_PRICE_COMMIT_* standard opcodes. These opcodes create, modify, or delete objects by using data in the input flist only; they do not verify relationships or dependencies with other pricing objects before committing changes to the database. For example, the PCM_OP_PRICE_COMMIT_PRODUCT opcode creates a /product object without first verifying that it is associated with a deal in the price list.

Important:

Because these opcodes do not verify dependencies with other pricing objects, you should use them in development environments only. To create pricing objects in a production environment, use the PCM_OP_PRICE_SET_PRICE_LIST opcode. See "Committing Price List Data to the BRM Database".

You use the following opcodes to manage individual pricing objects:

Managing /product Objects

Use the PCM_OP_PRICE_COMMIT_PRODUCT opcode to create, modify, or delete /product objects in the BRM database.

To create or modify /product objects, pass details about the product in the opcode's PIN_FLD_PRODUCT input flist array. In the array, you must also pass in the PIN_FLD_CODE field set to the /product object's unique identifier and the PIN_FLD_NAME field set to the product's name, which is modifiable.

This opcode validates and commits the following objects from a product flist: /rate, /rate_plan, /rate_plan_selector, and /rollover. Products are created or modified and, if the delete flag is sent in, deleted.

/rate_plan objects can have multiple rates, one for each rate tier (priority), date, day, and time-of-day range. These ranges are structured into a four-level tree of rate tier, date, day, and time. An optional rate plan selector is used when multiple rate plans from which to select are available.

When a product grants a non-currency resource, such as free minutes, the validity period of the granted resource is stored in the /rate object's PIN_FLD_BAL_IMPACTS array. See "Managing the Validity Period of Granted Resources".

PCM_OP_PRICE_COMMIT_PRODUCT performs the following in one transaction:

  • Generates the /event/notification/price/products/modify notification event

  • Commits all objects to the BRM database

  • Returns the following in the output flist:

    • If all operations are successful, this opcode returns PIN_FLD_RESULTS set to 1 and PIN_FLD_PRODUCTS set to the /product POID.

    • If any operation fails, this opcode returns PIN_FLD_RESULTS set to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Managing the Validity Period of Granted Resources

Resource validity periods define when a granted resource is available for consumption.

To set a resource's start and end times, pass the following values in the PIN_FLD_BAL_IMPACTS array in the PIN_FLD_RATES array of the PCM_OP_PRICE_COMMIT_PRODUCT input flist:

  • Set the PIN_FLD_FLAGS field to PIN_RATE_BAL_FLG_GRANTABLE (0x08). This specifies that the balance impact is granting the resource.

  • Specify the start times as follows:

    • To start on a specific date, pass the date in PIN_FLD_START_T.

    • To start immediately, set the value of PIN_FLD_START_T to 0.

    • To start on first usage (when the customer impacts the resource balance for the first time), set the value of PIN_FLD_RELATIVE_START_OFFSET to -1.

    • To start relative to the grant date, set the value of PIN_FLD_RELATIVE_START_UNIT to the type of relative unit and set the number of units in PIN_FLD_RELATIVE_START_OFFSET.

  • Specify the end time as follows:

    • To never end, set the value of PIN_FLD_END_T to 0.

    • To end relative to the start date, set the value of PIN_FLD_RELATIVE_END_UNIT to the type of relative unit and set the number of units in PIN_FLD_RELATIVE_END_OFFSET.

For more information about how to specify the unit and offset values, see "Specifying Relative Start and End Times for Granted Resources".

When the deal is committed to the BRM database, any relative validity information is stored in the PIN_FLD_START_DETAILS and PIN_FLD_END_DETAILS fields in the /rate object's PIN_FLD_BAL_IMPACTS array.

When the resource is granted to an account, any relative validity information is stored in the PIN_FLD_VALID_FROM_DETAILS and PIN_FLD_VALID_TO_DETAILS fields in the account /balance_group object's PIN_FLD_BAL_IMPACTS array.

For information about the values stored in details fields, see "Storing Start and End Times for Granted Resources".

Specifying Relative Start and End Times for Granted Resources

Relative start and end date information for granted resources is passed in UNIT and OFFSET fields:

  • PIN_FLD_RELATIVE_START_UNIT

  • PIN_FLD_RELATIVE_START_OFFSET

  • PIN_FLD_RELATIVE_END_UNIT

  • PIN_FLD_RELATIVE_END_OFFSET

The UNIT fields specify the type of offset unit, and the offset fields specify the number of units in the relative period. The UNIT fields can be one of the following values:

  • 1 = Seconds

  • 2 = Minutes

  • 3 = Hours

  • 4 = Days

  • 5 = Months

  • 8 = Accounting cycles

  • 9 = Event cycles

The UNIT and OFFSET fields are used in combination to determine the relative offset period. For example:

  • If PIN_FLD_RELATIVE_START_UNIT has a value of 8 (accounting cycles) and PIN_FLD_RELATIVE_START_OFFSET has a value of 2, the granted resource becomes valid (available for consumption) two accounting cycles after the resource is granted.

  • If PIN_FLD_RELATIVE_END_UNIT has a value of 5 (months) and PIN_FLD_RELATIVE_END_OFFSET has a value of 2, the validity period ends two months from the date it becomes valid.

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.

Storing Start and End Times for Granted Resources

The validity period information for granted resources that is passed in the unit and offset fields of opcode flists is stored in the /rate object's PIN_FLD_BAL_IMPACTS array in these details fields:

  • PIN_FLD_START_DETAILS

  • PIN_FLD_END_DETAILS

The details fields are 32-bit integer fields that store the following values:

  • Mode: The mode specifies generally when the validity period starts or ends. The mode also helps to determine how the start and end times are set in the account's /balance_group object when the resource is granted. The mode is stored in the lower 8th bit and can have one of the following values:

    For START-DETAILS:

    • 0 = PIN_VALIDITY_ABSOLUTE: The validity period starts on the date specified in PIN_FLD_START_T. When the resource is granted, the start date is set in the /balance_group object's PIN_FLD_VALID_FROM field.

    • 1 = PIN_VALIDITY_IMMEDIATE: The validity period starts when the resource is granted. The /balance_group object's PIN_FLD_VALID_FROM field is set to the grant date.

    • 3 = PIN_VALIDITY_FIRST_USAGE: The validity period starts when the resource balance is first impacted by an event.

    • 4 = PIN_VALIDITY_RELATIVE: The validity period starts relative to the grant date. When the resource is granted, the start date is calculated by adding the relative offset period to the grant date. The start date is then set in the /balance_group object's PIN_FLD_VALID_FROM field.

    For END-DETAILS:

    • 0 = PIN_VALIDITY_ABSOLUTE: The validity period ends on the date specified in PIN_FLD_END_T. When the resource is granted, the end date is set in the /balance_group object's PIN_FLD_VALID_TO field.

    • 2 = PIN_VALIDITY_NEVER: The validity period never ends. When the resource is granted, the /balance_group object's PIN_FLD_*_END_T field is set to 0.

    • 4 = PIN_VALIDITY_RELATIVE: The validity period ends relative to when it starts. When the resource is granted, the end date is calculated by adding the relative offset period to the start date. The end date is then set in the /balance_group object's PIN_FLD_VALID_TO field.

      Note:

      When the resource starts on first usage, the mode of the end time can be only PIN_VALIDITY_NEVER or PIN_VALIDITY_RELATIVE.

      When the resource is granted and its validity is activated, PIN_FLD_VALID_FROM and PIN_FLD_VALID_TO are set in the /balance_group object, and the mode in the PIN_FLD_VALID_FROM_DETAILS and PIN_FLD_VALID_TO_DETAILS fields in the /balance_group object are set to PIN_VALIDITY_ABSOLUTE.

  • Relative offset unit: This value is set when the resource balance starts at a time relative to when it is granted or when the resource balance ends at a time relative to the start time. It specifies the type of offset unit and corresponds to the value of PIN_FLD_RELATIVE_START_UNIT or PIN_FLD_RELATIVE_END_UNIT that is passed in opcode flists. The relative offset unit is stored in the next four bits of the details field.

  • Number of offset units: This value specifies how many offset units are in the relative period and corresponds to the value of PIN_FLD_RELATIVE_START_OFFSET or PIN_FLD_RELATIVE_END_OFFSET that is passed in opcode flists. The number of offset units is stored in the remaining 20 bits of the details field.

Customizing How to Create and Delete Products

To customize how to create and delete products:

  • To enable data modification during /product object creation, use the PCM_OP_PRICE_POL_PREP_PRODUCT policy opcode. Use this policy opcode to enhance /product objects with additional data not provided by either the GUI application or by the Price List FM.

    The PCM_OP_PRICE_COMMIT_PRODUCT opcode calls this policy opcode before creating a new /product object.

    Note:

    This policy opcode is called before the Price List FM performs any validation checks.
  • To enable validation during /product object creation, use the PCM_OP_PRICE_POL_VALID_PRODUCT policy opcode. This policy opcode can be used to perform validations in addition to those performed by the Price List FM.

    The PCM_OP_PRICE_COMMIT_PRODUCT opcode calls this policy opcode before creating a /product object. By default, this policy opcode is an empty hook that returns the result PIN_PRICE_VERIFY_PASSED.

  • To verify that deleting a /product object is permitted, use the PCM_OP_PRICE_POL_DELETE_PRODUCT policy opcode. Use this policy opcode to perform validations in addition to those performed by the Price List FM.

    PCM_OP_PRICE_COMMIT_PRODUCT calls this policy opcode before deleting the /product object. By default, it returns the result PIN_PRICE_VERIFY_PASSED.

    Success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that the operation succeeded and a value of 0 indicates that the operation failed.

Using Opcodes to Customize Products

You can customize products by changing individual rates and price models for specific resources. Customer service representatives (CSRs) can use this capability in Customer Center, but you can also call opcodes from third-party CRM applications.

Note:

Customer Center enforces permissioning requirements for product customization. Permissioning is not enforced when you customize products by calling opcodes directly. You must implement permissioning in the CRM tool that calls the opcodes.

Creating a Customized Product

To create custom products:

  • Call the PCM_OP_PRICE_GET_PRODUCT_INFO opcode to retrieve information about the base product, based on its POID.

  • Based on information about the base product and on the customization information (resources modified and the percentage modification), use the PCM_OP_PRICE_PREP_TAILORMADE_PRODUCT opcode to prepare an flist for the new customized /product object.

  • Call the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode to purchase the customized product and create a /purchased_product object to represent it in the account. This opcode calls the PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT opcode.

  • Pass the flist prepared by PCM_OP_PRICE_PREP_TAILORMADE_PRODUCT to the PCM_OP_PRICE_SET_PRICE_LIST opcode to commit the customized /product object to the BRM database. See "Committing Price List Data to the BRM Database".

  • Call the PCM_OP_SUBSCRIPTION_CYCLE_FORWARD opcode to apply the appropriate cycle fees. See "About Applying Cycle Forward Fees".

Modifying a Customized Product

From Customer Center, the only change you can make to an existing customized product is to modify its validity dates. This limitation does not apply when modifying customized products by calling opcodes directly, however.

  • Specify changes to the customized product's rates and price models and pass them to PCM_OP_PRICE_PREP_TAILORMADE_PRODUCT to prepare an flist for the modified customized /product object.

  • Pass the flist to PCM_OP_PRICE_SET_PRICE_LIST to update the /product object. See "Committing Price List Data to the BRM Database".

  • Call the PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode to update the /purchased_product object associated with the customized product.

Managing /discount Objects

Use the PCM_OP_PRICE_COMMIT_DISCOUNT opcode to:

  • Create, modify, or delete /discount objects in the BRM database

  • Create pipeline discount models

    Note:

    The opcode cannot modify pipeline discount models.

Creating /discount Objects

To create /discount objects, pass details about the discount in the opcode's PIN_FLD_DISCOUNT input flist array. You can also optionally create a pipeline discount model by using the PIN_FLD_PIPELINE_DISC_MODELS input flist array. See "Creating Pipeline Discount Models".

An offer profile and the provisioning tag for the associated discount use the same name and that name must be unique. If you create an offer profile to associate with existing discount, use the provisioning tag in the discount object to name the offer profile. When you configure a new discount around an existing offer profiles, use the appropriate offer profile name as the provisioning tag for the discount. Use the resource specified in the offer profile as a tracking resource in the discount that is attached to the offer profile.

When the /discount object does not exist in the database, PCM_OP_PRICE_COMMIT_DISCOUNT creates a /discount object by doing the following:

  • Calling the PCM_OP_PRICE_POL_PREP_DISCOUNT policy opcode to perform any custom preparation. By default, this policy opcode is an empty hook, but you can customize it to enhance /discount objects with additional data or to perform other custom actions. See "Customizing /discount Objects".

  • Calling the PCM_OP_PRICE_POL_VALID_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions. See "Customizing /discount Objects".

  • Creating the specified /discount object in the BRM database.

  • Generating the /event/notification/price/discounts/modify notification event. This enables you to synchronize discounts between BRM and external CRM applications.

PCM_OP_PRICE_COMMIT_DISCOUNT performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Creating Pipeline Discount Models

To create pipeline discount models, pass details about the discount model in the PCM_OP_PRICE_COMMIT_DISCOUNT opcode's PIN_FLD_PIPELINE_DISC_MODELS input flist array. The array can contain the following information:

  • Discount model version and configuration

  • Discount/chargeshare trigger

  • Discount/chargeshare condition

  • Discount/chargeshare rules

  • Discount/chargeshare master

  • Discount/chargeshare detail

  • Discount/chargeshare step

The discount model, trigger, rule, step, and master are uniquely identified by a code string in the PIN_FLD_CODE_STR field. If a code string is not passed in the input flist, the opcode generates one automatically.

Modifying /discount Objects

To modify /discount objects, pass details about the discount in the opcode's PIN_FLD_DISCOUNT input flist array. In the array, you must also pass in the PIN_FLD_CODE field set to the /discount object's unique identifier and the PIN_FLD_NAME field set to the discount's name, which is modifiable.

Important:

This opcode overwrites data in existing /discount objects, so be sure you pass in the correct object to modify.

When the object already exists in the database, PCM_OP_PRICE_COMMIT_DISCOUNT modifies the /discount object by doing the following:

  • Overwriting the specified /discount object in the BRM database.

  • Generating the /event/notification/price/discounts/modify notification event. This enables you to synchronize discounts between BRM and external CRM applications.

PCM_OP_PRICE_COMMIT_DISCOUNT performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Deleting /discount Objects

To delete /discount objects, pass details about the discount in the opcode's PIN_FLD_DISCOUNT input flist array and set the PIN_FLD_DELETED_FLAG input flist field to 1.

When PIN_FLD_DELETED_FLAG is set, PCM_OP_PRICE_COMMIT_DISCOUNT deletes the /discount object by doing the following:

  • Calling the PCM_OP_PRICE_POL_DELETE_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

  • Deleting the specified /discount object in the BRM database.

PCM_OP_PRICE_COMMIT_DISCOUNT performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_DISCOUNT sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Customizing /discount Objects

You can customize the /discount object before it is committed to the database by using the Price List FM policy opcodes:

  • To enable data modification during /discount object creation, use the PCM_OP_PRICE_POL_PREP_DISCOUNT policy opcode. Use this policy opcode to enhance /discount objects with additional data not provided by either the GUI application or by the Price List FM.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_DISCOUNT. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    Success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that all operations succeeded and a value of 0 indicates that the operation failed.

  • To enable validation during /discount object creation, use the PCM_OP_PRICE_POL_VALID_DISCOUNT policy opcode. This policy opcode can be used to enhance /discount objects with additional data not provided by either Pricing Center or by other opcodes in the Price List FM.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_DISCOUNT before creating a /discount object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    This policy opcode is called before the Price List FM performs any default validation checks.

    Success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that all operations succeeded and a value of 0 indicates that the operation failed.

  • To verify that deleting a /discount object is permitted, use the PCM_OP_PRICE_POL_DELETE_DISCOUNT policy opcode. Use this policy opcode to perform validations in addition to those performed by the Price List FM.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_DISCOUNT before it deletes a /discount object. By default, this policy opcode is an empty hook, but you can customize it to enhance /discount objects with additional data or to perform other customizations.

    This policy opcode is intended as a place for you to add validation checks or other functionality before allowing a /discount object to be deleted. For example, you may want to confirm that the valid time period for the /discount object has expired before allowing it to be deleted.

    Success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that all operations succeeded and a value of 0 indicates that the operation failed.

Retrieving Discount Data

Use the PCM_OP_PRICE_GET_DISCOUNT_INFO opcode to retrieve details about the real-time /discount object along with the pipeline discount model information from the BRM database. The discount model data includes the following:

  • Discount model version and configuration

  • Discount/chargeshare trigger

  • Discount/chargeshare condition

  • Discount/chargeshare rules

  • Discount/chargeshare master

  • Discount/chargeshare detail

  • Discount/chargeshare step

  • Balance impact

This opcode takes as input the discount object POID and optionally the discount object name. This opcode performs the following:

  1. Retrieves the real-time /discount object details from the BRM database.

  2. Retrieves the related pipeline discount model information used by the /discount object.

  3. Returns details about the real-time /discount object and pipeline discount model in the output flist.

Managing /deal Objects

Use the PCM_OP_PRICE_COMMIT_DEAL opcode to create, change, or delete /deal objects in the BRM database.

This opcode accepts an flist consisting of a PIN_FLD_DEAL array, each element of which represents a /deal object.

PCM_OP_PRICE_COMMIT_DEAL determines whether to create, modify, or delete the specified /deal object:

  • When the object does not exist, this opcode creates the specified /deal object by doing the following:

  • When the object already exists, this opcode modifies the specified /deal object in the BRM database.

    Important:

    PCM_OP_PRICE_COMMIT_DEAL overwrites data in existing /deal objects, so be sure you pass in the correct object to modify.
  • When the PIN_FLD_DELETED_FLAG is set, this opcode deletes the specified /deal object by doing the following:

    • Calling the PCM_OP_PRICE_POL_DELETE_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Deleting the specified object in the BRM database.

PCM_OP_PRICE_COMMIT_DEAL performs all operations within a single transaction, so success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that all operations succeeded and a value of 0 indicates that the operation failed. When the operation fails, the opcode also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

To set the purchase, cycle, and usage start and end dates of the products and discounts in the deal, 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 within the purchase validity period.
  • To start immediately, set the value of PIN_FLD_*_START_OFFSET to 0.

  • To start on first usage (when the customer uses the product or discount for the first time), set the value of PIN_FLD_*_START_OFFSET to -1.

  • To start relative to the purchase date, 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.

    Note:

    If you specify a relative unit for more than one period (purchase, cycle, or usage) and you select a different relative unit for each, if one of the relative units is cycles, the PCM_OP_PRICE_POL_VALID_DEAL policy opcode cannot validate that the cycle or usage period falls within the purchase period. The validation for this kind of configuration is performed when the product is purchased by a customer.
  • To never end, set the value of PIN_FLD_*_END_OFFSET to 0.

  • To end relative to the start date, 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.

For more information about how to specify the unit and offset values, see "Specifying Relative Start and End Times for Products and Discounts in a Deal".

If the deal's products or discounts grant resources that start on first usage (when the customer 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.

When the deal is committed to the BRM database, the purchase, cycle, and usage validity information is stored in the PIN_FLD_*_START_DETAILS and PIN_FLD_*_END_DETAILS fields in the /deal object's product and discount arrays. For information about the values stored in the details fields, see "Storing Start and End Times for Products and Discounts in a Deal".

Specifying Relative Start and End Times for Products and Discounts in a Deal

When the purchase, cycle, or usage period of a product or discount has a relative start or end time, the details about the relative period are passed in opcode flists in UNIT and OFFSET fields.

The following 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

  • Months = 5

  • Accounting cycles = 8

The following 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 for each purchase, cycle, and usage period are used in combination to determine the relative offset period. 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.

Information about the relative offset validity periods is stored in the BRM database in DETAILS fields in the /deal object's products and discounts arrays. For more information, see "Storing Start and End Times for Products and Discounts in a Deal".

The product and discount start and end dates (the PIN_FLD_*_START_T and PIN_FLD_*_END_T fields) are not set in the /deal object but are set in the /purchased_product and /purchased_discount objects when the product or discount is purchased.

Storing Start and End Times for Products and Discounts in a Deal

When a product or discount has a relative start or end time, the relative information passed in the PIN_FLD_*_UNIT and PIN_FLD_*_OFFSET fields of opcode flists is stored in the database in PIN_FLD_*_DETAILS fields in the /deal object:

  • 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

The START-DETAILS and END-DETAILS fields are 32-bit integer fields that store three values: 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 also helps to determine how the start and end dates are set in the account's /purchased_product and /purchased_discount objects when the product or discount is purchased. The mode is stored in the lower 8th bit and can have one of the following values:

    For the START-DETAILS:

    • 1 = PIN_VALIDITY_IMMEDIATE: The validity period starts when the product or discount is purchased. When purchased, the PIN_FLD_*_START_T field in the account's /purchased_product or /purchased_discount object is set to the purchase time.

    • 3 = PIN_VALIDITY_FIRST_USAGE: The validity period starts when the product or discount is first used to rate the customer's usage.

    • 4 = PIN_VALIDITY_RELATIVE: The validity period starts relative to the purchase date. When the product or discount is purchased, the start date is calculated by adding the relative offset period to the purchase date. The start date is then set in the purchased product's or purchased discount's PIN_FLD_*_START_T field.

    For the END-DETAILS:

    • 2 = PIN_VALIDITY_NEVER: The validity period never ends. When the product or discount is purchased, the purchased product's or purchased discount's PIN_FLD_*_END_T field is set to 0.

    • 4 = PIN_VALIDITY_RELATIVE: The validity period ends relative to when it starts. When the product or discount is purchased, the end date is calculated by adding the relative offset period to the start date. The end date is then set in the purchased product's or purchased discount's PIN_FLD_*_END_T field.

    When PIN_FLD_*_START_T and PIN_FLD_*_END_T are set in the account's /purchased_product and /purchased_discount objects, the mode in the details fields of those objects is set to PIN_VALIDITY_ABSOLUTE.

  • Relative offset unit: This value is set when the product or discount starts at a time relative to the purchase date or ends at a time relative to the start date. It 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 the following values:

    • Seconds = 1

    • Minutes = 2

    • Hours = 3

    • Days = 4

    • Months = 5

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

Customizing How to Create and Delete Deals

To customize how to create and delete deals, use the following policy opcodes:

  • To enable data modification during /deal object creation, use the PCM_OP_PRICE_POL_PREP_DEAL policy opcode.

    By default, this policy opcode is an empty hook, but you can customize it to enhance /deal objects with additional data not provided either by the GUI application or by the Price List FM or to perform other custom actions.

    This policy opcode is called before the Price List FM performs any validation checks.

  • To enable validation during /deal object creation, use the PCM_OP_PRICE_POL_VALID_DEAL policy opcode. This policy opcode can be used to perform validations in addition to those performed by the Price List FM.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_DEAL. By default, this policy opcode is an empty hook; it returns the result PIN_PRICE_VERIFY_PASSED.

  • To verify that deleting a /deal object is permitted, use the PCM_OP_PRICE_POL_DELETE_DEAL policy opcode. Use this opcode to perform validations in addition to those performed by the Price List FM.

    PCM_OP_PRICE_COMMIT_DEAL calls this policy opcode before deleting the /deal object. By default, this policy opcode is an empty hook provided to facilitate customization. It returns the result PIN_PRICE_VERIFY_PASSED.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

Managing /plan Objects

Use the PCM_OP_PRICE_COMMIT_PLAN opcode to create, modify, or delete /plan objects in the BRM database.

This opcode accepts an flist consisting of a PIN_FLD_PLAN array, each element of which represents a /plan object.

PCM_OP_PRICE_COMMIT_PLAN determines whether to create, modify, or delete the specified /plan object:

  • When the object does not exist, this opcode creates the specified /plan object by doing the following:

    • Calling the PCM_OP_PRICE_POL_PREP_DISCOUNT policy opcode to perform any custom preparation. By default, this policy opcode is an empty hook, but you can customize it to enhance /plan objects with additional data or to perform other custom actions.

    • Calling the PCM_OP_PRICE_POL_VALID_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Creating the specified object in the BRM database.

  • When the object already exists, this opcode modifies the specified /plan object in the BRM database.

    Important:

    This opcode overwrites data in existing /plan objects, so be sure you pass in the correct object to modify.
  • When the PIN_FLD_DELETED_FLAG is set, this opcode deletes the specified /plan object by doing the following:

    • Calling the PCM_OP_PRICE_POL_DELETE_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Deleting the specified object in the BRM database.

PCM_OP_PRICE_COMMIT_PLAN performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_PLAN sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_PLAN_LIST sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Managing /dependency Objects

Use the PCM_OP_PRICE_COMMIT_DEPENDENCY opcode to create, modify, or delete a /dependency object. This object specifies any dependencies between two discounts or between a discount and a plan.

This opcode accepts an flist that includes a PIN_FLD_DEPENDENCY array, each element of which represent a /dependency object.

Flist /dependency Arrays

The arrays defining prerequisite and mutually exclusive relationships require the names of the two product objects. The name of the product that requires another product is listed in the PIN_FLD_DEPENDENT_NAME field; the name of the required product is listed in the PIN_FLD_DEPENDEE_NAME field. For example, if your business has an email product that requires a Basic Dialup product, email is the dependee and Basic Dialup is the dependent:

0 PIN_FLD_DEPENDENCIES   ARRAY  [12] 
1  PIN_FLD_DEPENDEE_OBJ    POID [0] 0.0.0.1 /deal -1 0 
1  PIN_FLD_DEPENDENT_OBJ   POID [0] 0.0.0.1 /deal -1 0 
1  PIN_FLD_DEPENDEE_NAME    STR [0] "Basic Dialup" 
1  PIN_FLD_DEPENDENT_NAME   STR [0] "email" 
1  PIN_FLD_TYPE             ENUM [0] 1

PCM_OP_PRICE_COMMIT_DEPENDENCY performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_DEPENDENCY sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_DEPENDENCY sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Customizing How to Create and Delete Dependencies

To customize how to create and delete dependencies, use the following policy opcodes:

  • To enable data modification during /dependency object creation, use the PCM_OP_PRICE_POL_PREP_DEPENDENCY policy opcode. Use this policy opcode to enhance /dependency objects with additional data not provided by either the GUI application or by the Price List FM. For example, you would modify this policy opcode if your business requires that you change a mutually exclusive relationship into a required one, without using Pricing Center.

    PCM_OP_PRICE_COMMIT_DEPENDENCY calls this policy opcode before creating a new /dependency object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    This policy opcode is called before the Price List FM performs any validation checks.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

  • To enable validation during /dependency object creation, use the PCM_OP_PRICE_POL_VALID_DEPENDENCY policy opcode. This policy opcode can be used to change /dependency relationships without using Pricing Center.

    This policy opcode is called by PCM_OP_PRICE_SET_PRICE_LIST and PCM_OP_PRICE_COMMIT_DEPENDENCY before creating a /dependency object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

  • To verify that deleting a /dependency object is permitted, use the PCM_OP_PRICE_POL_DELETE_DEPENDENCY policy opcode. Use this policy opcode to perform validations in addition to those performed by the Price List FM.

    For example, you can use this policy opcode to confirm that the valid time period for the /dependency object has expired before allowing it to be deleted.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_DEPENDENCY before it deletes a /dependency object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

Managing /transition Objects

Use the PCM_OP_PRICE_COMMIT_TRANSITION opcode to create, modify, or delete a /transition object.

This opcode accepts an flist consisting of a PIN_FLD_TRANSITION array, each element of which represents a /transition object.

PCM_OP_PRICE_COMMIT_TRANSITION determines whether to create, modify, or delete the specified /transition object:

  • When the object does not exist, this opcode creates the specified /transition object by doing the following:

    • Calling the PCM_OP_PRICE_POL_PREP_TRANSITION policy opcode to perform any custom preparation. By default, this policy opcode is an empty hook, but you can customize it to enhance /transition objects with additional data or to perform other custom actions.

    • Calling the PCM_OP_PRICE_POL_VALID_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Creating the specified object in the BRM database.

  • When the object already exists, this opcode modifies the specified /transition object in the BRM database.

    Important:

    This opcode overwrites data in existing /transition objects, so be sure you pass in the correct object to modify.
  • When the PIN_FLD_DELETED_FLAG is set, this opcode deletes the specified /transition object by doing the following:

    • Calling the PCM_OP_PRICE_POL_DELETE_TRANSITION policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Deleting the specified object in the BRM database.

PCM_OP_PRICE_COMMIT_TRANSITION performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_TRANSITION sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_TRANSITION sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Customizing How to Create and Delete Transitions

To customize how to create and delete transitions, use the following policy opcodes:

  • To enable data modification during /transition object creation, use the PCM_OP_PRICE_POL_PREP_TRANSITION policy opcode. Use this policy opcode to enhance /transition objects with additional data not provided by either the GUI application or by the Price List FM.

    For example, if your business waives purchase and cancellation fees for its San Francisco customers, you would implement that logic in this policy opcode.

    PCM_OP_PRICE_COMMIT_TRANSITION calls this policy opcode before creating a new /transition object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    This policy opcode is called before the Price List FM performs any validation checks.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

  • To enable validation during /transition object creation, use the PCM_OP_PRICE_POL_VALID_TRANSITION policy opcode. This policy opcode can be used to change /transition relationships without using Pricing Center.

    For example, if your business requires that you prohibit underage customers from transitioning to a specific deal, you would add that limitation to this policy opcode.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_TRANSITION before creating a /transition object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    This policy opcode is called before the Price List FM creates the /transition object.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

  • To verify that deleting a /transition object is permitted, use the PCM_OP_PRICE_POL_DELETE_TRANSITION policy opcode. Use this policy opcode to perform validations in addition to those performed by the Price List FM.

    For example, you can use this policy opcode to confirm that the valid time period for the /transition object has expired before allowing it to be deleted.

    This policy opcode is called by PCM_OP_PRICE_COMMIT_TRANSITION before it deletes a /transition object. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    Success or failure is indicated by the value returned for PIN_FLD_RESULTS. When successful, PIN_FLD_RESULTS is set to 1. When any operation fails, PIN_FLD_RESULTS is set to 0.

Managing /group/plan_list Objects

Use the PCM_OP_PRICE_COMMIT_PLAN_LIST opcode to commit /group/plan_list objects to the BRM database.

This opcode connects to the database, opens a transaction, and retrieves the /plan_list flist. PCM_OP_PRICE_COMMIT_PLAN_LIST searches the PIN_FLD_PLAN flist to match the name and type fields in the plan list flist. This plan is checked against existing plans in the database. If the plan does not exist, this opcode reports an error and stops the transaction. If the plan does exist, this opcode adds the flist to the PIN_FLD_RESULTS array. This process is repeated until all plan list entries are added to the PIN_FLD_RESULTS array and committed to the database. The committed changes include new, modified, or deleted objects.

PCM_OP_PRICE_COMMIT_PLAN_LIST performs all operations within a single transaction, so success or failure is indicated by the value returned for PIN_FLD_RESULTS:

  • When successful, PCM_OP_PRICE_COMMIT_PLAN_LIST sets PIN_FLD_RESULTS to 1.

  • When any operation fails, PCM_OP_PRICE_COMMIT_PLAN_LIST sets PIN_FLD_RESULTS to 0. It also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Managing /sponsorship Objects

Use the PCM_OP_PRICE_COMMIT_SPONSORSHIP opcode to create, change, or delete a /sponsorship object.

PCM_OP_PRICE_COMMIT_SPONSORSHIP determines whether to create, modify, or delete the specified /sponsorship object:

  • When the object does not exist, this opcode creates the specified /sponsorship object by doing the following:

    • Calling the PCM_OP_PRICE_POL_PREP_DISCOUNT policy opcode to perform any custom preparation. By default, this policy opcode is an empty hook, but you can customize it to enhance /sponsorship objects with additional data or to perform other custom actions.

    • Calling the PCM_OP_PRICE_POL_VALID_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Creating the specified object in the BRM database.

    • Preparing a list of all /sponsorship objects that were created.

    • Generating the /event/notification/price/sponsorships/modify notification event.

  • When the object already exists, this opcode modifies the specified object by doing the following:

    • Updating the specified object in the BRM database.

    • Preparing a list of all /sponsorship objects that were modified.

    • Generating the /event/notification/price/sponsorships/modify notification event.

      Important:

      This opcode overwrites data in existing /sponsorship objects, so be sure you pass in the correct object to modify.
  • When the PIN_FLD_DELETED_FLAG is set, this opcode deletes the specified /sponsorship object by doing the following:

    • Calling the PCM_OP_PRICE_POL_DELETE_DISCOUNT policy opcode to perform any custom validation. By default, this policy opcode is an empty hook, but you can customize it to validate field values or to perform other custom actions.

    • Deleting the specified object in the BRM database.

PCM_OP_PRICE_COMMIT_SPONSORSHIP performs all operations within a single transaction, so success or failure is indicated by the value returned in the PIN_FLD_RESULTS output flist field: a value of 1 indicates that all operations succeeded and a value of 0 indicates that the operation failed. If the operation fails, the opcode also returns two additional fields: PIN_FLD_RESULT_FORMAT, which lists all error codes, and PIN_FLD_DESCR, which provides a concise error description.

Managing Filter Sets

Filter sets enable you to apply system products and system discounts to a select group of customers (for example, those with the best credit history). You define which customers and events qualify for specified products and discounts by using Pricing Center or a custom client application. Each filter set specifies:

  • The criteria an EDR must meet to qualify for the filter set: that is, list of required EDR fields and their values

  • The list of applicable system products and system discounts, along with their validity dates and priorities

BRM stores information about each filter set in /filter_set/product objects.

To manage filter sets, use the following opcodes:

Creating Filter Sets

Use the PCM_OP_FILTER_SET_CREATE opcode to create /filter_set/product objects in the BRM database. This opcode is called directly by Pricing Center.

PCM_OP_FILTER_SET_CREATE performs the following operations:

  1. Confirms that the object to be created is a /filter_set/product object, or one subclassed from it. The type of object is specified in the PIN_FLD_POID field of the input flist.

  2. Creates the /filter_set/product object.

  3. Generates an /event/filter_set/create object to record details of the event.

  4. Returns the POID of the new /filter_set/product object.

Updating Filter Sets

Use the PCM_OP_FILTER_SET_UPDATE opcode to modify existing /filter_set/product objects. This opcode is called directly by Pricing Center.

PCM_OP_FILTER_SET_UPDATE performs the following operations:

  1. Determines whether to add, modify, or delete data in the object by checking the PIN_FLD_FLAG field:

    • When the flag is set to 0, the opcode modifies filter set data.

    • When the flag is set to 1, the opcode adds filter set data.

    • When the flag is set to 2, the opcode deletes filter set data.

  2. Modifies data in the specified /filter_set/product object.

  3. Creates an /event/filter_set/update object to record details of the event.

  4. Returns the POID of the /filter_set/product object.

Deleting Filter Sets

Use the PCM_OP_FILTER_SET_DELETE opcode to delete /filter_set/product objects from the BRM database. This opcode is called directly by Pricing Center.

PCM_OP_FILTER_SET_DELETE performs the following operations:

  1. Deletes the specified /filter_set/product object.

  2. Generates an /event/filter_set/delete object to record details of the event.

  3. Returns the POID of the /filter_set/product object.