7 Charging Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) charging opcode workflows.

Topics in this document:

• Opcodes Described in This Chapter

• Subscription Rating Opcodes

• Implementing Custom Rating

• Getting ERAs for an Event

• Modifying Rated Events

• Modifying ERAs

• Managing Credit Limits and Sub-Balance Consumption Rules

• Maintaining Subscriber's Charging Preferences Data

• Modifying Events before Sending Them to ECE

• Rerating Opcodes

• Suspense Management

• Provisioning Process Opcode Flow

• GPRS Opcodes

Opcodes Described in This Chapter

Table 7-1 lists the opcodes described in this chapter.

Caution:

• Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.

• Do not use SQL commands to change data in the database. Always use the API.

Table 7-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_POL_SPEC_RATES	Implementing Custom Rating
PCM_OP_ACT_USAGE	Resubmitting Suspended Batches Editing Suspended Records in Bulk Writing Off Suspended Records in Bulk Deleting Suspended Records in Bulk
PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES	Deleting Records for Suspended Batches
PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES	Resubmitting Suspended Batches
PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES	Writing Off Suspended Batches
PCM_OP_BILL_GET_LIMIT	Retrieving Credit Limits
PCM_OP_BILL_POL_POST_SET_LIMIT_AND_CR	Managing Credit Limits and Sub-Balance Consumption Rules
PCM_OP_BILL_POL_PRE_SET_LIMIT_AND_CR	Managing Credit Limits and Sub-Balance Consumption Rules
PCM_OP_BILL_SET_LIMIT_AND_CR	How BRM Handles Consumption Rules and Credit Limits
PCM_OP_CUST_GET_SUBSCRIBER_PREFERENCES	Maintaining Subscriber's Charging Preferences Data
PCM_OP_CUST_MODIFY_PROFILE	About Creating Service Orders for Profile Changes
PCM_OP_CUST_SET_PASSWD	Implementing Custom Rating
PCM_OP_CUST_SET_SUBSCRIBER_PREFERENCES	Maintaining Subscriber's Charging Preferences Data
PCM_OP_GPRS_APPLY_PARAMETER	About Associating APNs and QoS with GPRS Services Mapping Service Types to Service-Specific Opcodes Associating APN and QoS Pairs with GPRS Services Updating Custom GPRS Service Fields
PCM_OP_GPRS_POL_APPLY_PARAMETER	About Associating APNs and QoS with GPRS Services Associating APN and QoS Pairs with GPRS Services Updating Custom GPRS Service Fields
PCM_OP_GSM_APPLY_PARAMETER	Updating Custom GSM Service Fields
PCM_OP_GSM_POL_APPLY_PARAMETER	Updating Custom GSM Service Fields
PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT	Modifying Events before Sending Them to ECE Modifying BRM Events That Make Up Account Synchronization Business Events
PCM_OP_IFW_SYNC_PUBLISH_EVENT	Processing BRM Events That Make Up Account Synchronization Business Events
PCM_OP_PROV_PUBLISH_SVC_ORDER	Provisioning Process Opcode Flow
PCM_OP_PROV_UPDATE_SVC_ORDER	Provisioning Process Opcode Flow
PCM_OP_RATE_AND_DISCOUNT_EVENT	Modifying Rated Events
PCM_OP_RATE_GET_ERAS	Getting ERAs for an Event Modifying ERAs
PCM_OP_RATE_POL_POST_RATING	Modifying Rated Events
PCM_OP_RATE_POL_PRE_RATING	Modifying Rated Events Modifying ERAs
PCM_OP_RATE_POL_PROCESS_ERAS	Getting ERAs for an Event Modifying ERAs
PCM_OP_RERATE_CREATE_JOB	How BRM Creates Rerate Jobs How BRM Handles Duplicate Rerate Jobs
PCM_OP_RERATE_INSERT_RERATE_REQUEST	How BRM Creates Rerate Jobs How BRM Handles Duplicate Rerate Jobs Customizing Automatic Creation of Rerate Jobs Specifying a Rerate Reason Code Specifying Selection Criteria Specifying Price Overrides Configuring Event Notification for Override Pricing
PCM_OP_SUBCRIPTION_RERATE_REBILL	Customizing Event Searches for Rerating Specifying Price Overrides
PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST	How BRM Creates Rerate Jobs Specifying a Rerate Reason Code Customizing Automatic Creation of Rerate Jobs Configuring Event Notification for Override Pricing
PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE	Customizing Event Searches for Rerating
PCM_OP_SUBSCRIPTION_PREP_RATE_CHANGE	Rerating Cycle Forward and Cycle Forward Arrears Events
PCM_OP_SUBSCRIPTION_RATE_CHANGE	Rerating Cycle Forward and Cycle Forward Arrears Events
PCM_OP_SUSPENSE_DEFERRED_DELETE	Deleting Suspended Records in Bulk
PCM_OP_SUSPENSE_DELETE_USAGE	Deleting Suspended Records
PCM_OP_SUSPENSE_EDIT_USAGE	Changing the Contents of Fields in Suspended Event Records Deleting Call Records with a Specific Recycle Key and a Status of Succeeded or Written-Off Deleting Records in a CDR File
PCM_OP_SUSPENSE_RECYCLE_USAGE	Initiating Suspense Recycling
PCM_OP_SUSPENSE_SEARCH_DELETE	Deleting Call Records with a Specific Recycle Key and a Status of Succeeded or Written-Off Deleting Records in a CDR File Deleting Suspended Records in Bulk
PCM_OP_SUSPENSE_SEARCH_EDIT	Editing Suspended Records in Bulk
PCM_OP_SUSPENSE_SEARCH_RECYCLE	Recycling Suspended Records
PCM_OP_SUSPENSE_SEARCH_WRITE_OFF	Writing Off Suspended Records in Bulk
PCM_OP_SUSPENSE_UNDO_EDIT_USAGE	Undoing Edits to Suspended Event Records
PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE	Writing Off Suspended Records
PCM_OP_TCF_APPLY_PARAMETER	About Associating APNs and QoS with GPRS Services Mapping Service Types to Service-Specific Opcodes
PCM_OP_TCF_CREATE_SVC_ORDER	About Creating Service Orders for Profile Changes
PCM_OP_TCF_POL_APPLY_PARAMETER	About Associating APNs and QoS with GPRS Services Mapping Service Types to Service-Specific Opcodes Associating APN and QoS Pairs with GPRS Services
PCM_OP_TCF_PROV_CREATE_SVC_ORDER	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_HANDLE_SVC_ORDER	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_SERVICE_ORDER_NOTIFY	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_SERVICE_ORDER_SET_ATTR	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_SERVICE_ORDER_SET_STATE	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_SIMULATE_AGENT	Provisioning Process Opcode Flow
PCM_OP_TCF_PROV_UPDATE_PROV_OBJECT	Provisioning Process Opcode Flow
PCM_OP_TCF_SVC_LISTENER	About Associating APNs and QoS with GPRS Services

Subscription Rating Opcodes

The following opcodes are used for subscription rating:

• PCM_OP_RATE_EVENT. This opcode applies pricing and taxes to a subscription event (for example, a recurring charge or a purchase charge).

  When the optional timestamp field PIN_FLD_WHEN_T is present in the input flist, the opcode searches for the charge offer that is valid at the time specified in the field. It uses the charge offer to rate the event.

  PCM_OP_RATE_EVENT also locates any rollover objects for events, and returns details of the rollover object to the calling opcode.

  Uses the index value in the /product object's PIN_FLD_TAX_SUPPLIER field to locate the correct tax supplier in the cache.

• PCM_OP_RATE_GET_ERAS. This opcode retrieves the extended rating attribute (ERAs) for an event.

  See "Getting ERAs for an Event" .

• PCM_OP_RATE_GET_PRODLIST. This opcode retrieves the list of charge offers owned by an account and filters them with input criteria.

• PCM_OP_RATE_TAX_CALC. This opcode calculates taxes due at the time of purchase or billing.

  See "How PCM_OP_RATE_TAX_CALC Calculates Taxes".

• PCM_OP_RATE_TAX_EVENT. This opcode directs the calculation of taxes for subscription events.

Implementing Custom Rating

You can use the PCM_OP_ACT_POL_SPEC_RATES policy opcode to create a custom rating application. For example, you can rate administrative events or configure rating based on nonevent attributes such as an account attribute or a profile attribute.

You can configure the PCM_OP_ACT_POL_SPEC_RATES policy opcode to be called by another opcode. 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 change, the PCM_OP_CUST_SET_PASSWD opcode specifies the inherited password information.

To charge for custom events and attributes:

1. Modify the PCM_OP_ACT_POL_SPEC_RATES policy opcode or write a custom policy opcode to analyze the event data and assign the charge and impact category.

   See the policy source file of the PCM_OP_ACT_POL_SPEC_RATES policy opcode for a sample implementation.

2. Edit the pin_spec_rates file in BRM_home/sys/data/config to associate the opcode to the event type that it rates.

   The pin_spec_rates file includes examples and instructions.

   Note:

   When you run the load_pin_spec_rates utility, it overwrites the existing setup for administrative events charges. If you are updating a set of administrative events charges, you cannot load new charges only. You load complete sets of charges each time you run load_pin_spec_rates.

3. Create a configuration file for the load_pin_spec_rates utility.

4. Run the load_pin_spec_rates utility to load the contents of the pin_spec_rates file into the database.

   load_pin_spec_rates pin_spec_rates_file
   

5. Define impact categories for the event in PDC or Pricing Center.

6. In PDC or Pricing Center, create the charge offers that can be used to rate an event that is rated by your customized opcode.

Getting ERAs for an Event

PCM_OP_RATE_GET_ERAS retrieves the extended rating attribute (ERAs) for an event. This opcode does the following:

• Reads the /profile/serv_extrating and /profile/acct_extrating objects associated with the service and account in the event.

• Reads /group/sharing/profile objects to identify profile sharing groups associated with the services or subscription services in the event. If a profile sharing group is found and is active at the time of the event, the opcode reads the /profile/serv_extrating or /profile/acct_extrating object associated with the group.

• Checks whether each ERA was valid at the time of the event.

• Returns the name of each valid ERA and the names of ERA labels belonging to each valid ERA to the calling policy opcode, PCM_OP_RATE_POL_PROCESS_ERAS.

Modifying Rated Events

Use PCM_OP_RATE_POL_PRE_RATING to modify subscription events before rating. PCM_OP_RATE_POL_PRE_RATING is called by PCM_OP_RATE_AND_DISCOUNT_EVENT.

Use PCM_OP_RATE_POL_POST_RATING to modify rated /event objects (for example, change the G/L ID of an event).

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.

This 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;
   }
}                        

Modifying ERAs

Use PCM_OP_RATE_POL_PROCESS_ERAS to modify ERAs. This opcode calls PCM_OP_RATE_GET_ERAS to find the valid service and account ERAs for an event. This opcode then populates the PIN_FLD_USAGE_TYPE field with the names of valid ERAs and populates the PIN_FLD_PROFILE_LABEL_LIST field with ERA label names.

PCM_OP_RATE_POL_PROCESS_ERAS is called by PCM_OP_RATE_POL_PRE_RATING.

PCM_OP_RATE_POL_PROCESS_ERAS returns the output to PCM_OP_RATE_POL_PRE_RATING.

Managing Credit Limits and Sub-Balance Consumption Rules

Sub-balance consumption rules specify the order in which sub-balances are consumed. For example, when a customer is granted minutes with different validity periods, you can specify which minutes to use first based on the validity start time and end time.

Permanent credit limits specify the maximum amount of a balance element, such as US Dollars, that can accumulate in a balance group. When a credit limit is reached, businesses typically deny customers access to the services associated with the balance group. For example, you might set a customer's credit limit to $100 and then deny service after the customer reaches that limit.

Temporary credit limits specify the maximum amount of a balance element that can accumulate in a balance group during a specified validity period. For example, you might set customer B's credit limit to $200 for December 1, 2031 through January 31, 2032. If the customer also has a permanent credit limit for the same balance element, the temporary credit limit amount is appended to the permanent credit limit amount. For example, if customer B has a permanent credit limit of $100, the customer's credit limit would be $300 for December 1, 2031 through January 31, 2032.

You use the following opcodes to manage credit limits and consumption rules in an account:

• To set sub-balance consumption rules, permanent credit limits, temporary credit limits, or automatic top-up thresholds, use PCM_OP_BILL_SET_LIMIT_AND_CR. See "How BRM Handles Consumption Rules and Credit Limits".

• To retrieve the permanent and temporary credit limits for an account, use PCM_OP_BILL_GET_LIMIT. See "Retrieving Credit Limits".

• To modify the validity dates for an account's temporary credit limit, use PCM_OP_BILL_POL_PRE_SET_LIMIT_AND_CR. By default, this policy opcode does nothing.

• To customize the notification sent after a temporary credit limit is created or expires, use PCM_OP_BILL_POL_POST_SET_LIMIT_AND_CR.

• To customize a customer's permanent credit limit, use PCM_OP_CUST_POL_PREP_LIMIT and PCM_OP_CUST_POL_VALID_LIMIT.

  PCM_OP_CUST_POL_PREP_LIMIT is called by PCM_OP_BILL_SET_LIMIT_AND_CR. PCM_OP_CUST_POL_PREP_LIMIT is an empty hook. See "About the PREP and VALID Opcodes" in BRM Developer's Guide.

How BRM Handles Consumption Rules and Credit Limits

Use PCM_OP_BILL_SET_LIMIT_AND_CR to set one or more of the following for an account: a temporary credit limit, a permanent credit limit, a sub-balance consumption rule, or an automatic top-up threshold.

The opcode sets the consumption rule and credit limits in a balance group for both currency and noncurrency balances. This opcode must be called separately for each balance to set. PCM_OP_BILL_SET_LIMIT_AND_CR creates a new /event/billing/limit event each time a credit limit is changed and a new /event/billing/consumption_rule event each time a consumption rule is changed.

By default, PCM_OP_BILL_SET_LIMIT_AND_CR sets or changes the credit limit, consumption rule, and thresholds in an account's default /balance_group object. To set a consumption rule, credit limit, credit floor, or threshold for any of the other billing entities associated with the object, specify them with the optional PIN_FLD_BAL_GRP_OBJ input flist field.

• A consumption rule is passed in the PIN_FLD_RULES array of the PCM_OP_BILL_SET_LIMIT_AND_CR input flist, which contains the balance element ID of the balance to change or create. The consumption rule is set in the PIN_FLD_CONSUMPTION_RULE field of the /balance_group object of the various billing entities.

• A permanent credit limit is passed in the PIN_FLD_LIMIT array of the opcode's input flist, which contains the balance element ID of the balance to change or create. The credit limit is set in the PIN_FLD_BALANCES array of the /balance_group object of the various billing entities. The POID of this object is passed in the PIN_FLD_BAL_GRP_OBJ field of the input flist.

  If the opcode's PIN_FLD_OVERRIDE_CREDIT_LIMIT input flist field is set to 0, the account's credit limit is enforced. If the flist field is set to 1, the account's credit limit is ignored and the account's balance can exceed the limit.

• A temporary credit limit is passed in the PIN_FLD_TEMP_LIMIT array of the opcode's input flist, which contains the resource ID and validity dates of the balance to change or create. If validity dates are not passed in, they are set from the current date to never expires.

  The opcode sets the temporary credit limit in the PIN_FLD_SUB_BAL_IMPACTS array of the /balance_group object of the various billing entities. If the /balance_group object contains another temporary credit limit with matching validity dates, they are merged into one sub-balance.

  When processing temporary credit limits, PCM_OP_BILL_SET_LIMIT_AND_CR calls the following policy opcodes:

  • PCM_OP_BILL_POL_PRE_SET_LIMIT_AND_CR: Allows you to modify the validity dates for a temporary credit limit.

  • PCM_OP_BILL_POL_POST_SET_LIMIT_AND_CR: Generates an /event/notification/billing/temp_limit notification event when a temporary credit limit is added, and generates an /event/notification/billing/temp_limit/expiry notification event when a temporary credit limit has expired. You can use this policy opcode to customize the /event/notification/billing/temp_limit and /event/notification/billing/temp_limit/expiry notification events.

• A credit floor value is passed in the PIN_FLD_CREDIT_FLOOR field in the PIN_FLD_LIMIT array in the opcode's input flist. Alternatively, you can use the PIN_FLD_DYNAMIC_CREDIT_FLOOR field to determine the credit floor using the granted amounts from the sub-balances that are valid for the current cycle for the resource (for example, minutes). If PIN_FLD_DYNAMIC_CREDIT_FLOOR is set to 1, PIN_FLD_CREDIT_FLOOR is set to NULL, regardless of any value for that parameter that is passed.

• An automatic top-up threshold is passed in the PIN_FLD_RESRC_FIXED_THRESHOLD or PIN_FLD_RESRC_PERC_THRESHOLD field of the PIN_FLD_LIMIT array of the opcode's input flist. The thresholds are stored in the /config/credit_profile object tied to the balance group.

For nonpaying child accounts belonging to a PR_RTCE balance monitoring group: If PIN_FLD_ROLL_UP_CREDIT_LIMIT is set to 1, the opcode rolls up the account's credit limit to the owner of the PR_RTCE balance monitoring group.

A noncurrency balance without an explicitly set credit limit has a default credit limit of zero. If PCM_OP_BILL_SET_LIMIT_AND_CR is called for a nonexistent balance, the balance is created, the credit limit is set, and the current balance is set to zero.

PCM_OP_BILL_SET_LIMIT_AND_CR does not affect the current balances of the account.

To return all fields in the event object, set the PCM_OPFLG_READ_RESULT flag. If this flag is not set, PCM_OP_BILL_SET_LIMIT_AND_CR returns only the POID.

To run PCM_OP_BILL_SET_LIMIT_AND_CR without changing data in the database, use the PCM_OPFLG_CALC_ONLY flag.

• If the flag is set, no fields in the database are changed and the event object is not created. The fields that would have been used to create the event object are returned to the caller.

• If the flag is not set, either the /event/billing/limit object or the /event/billing/consumption_rule object is created to record details of the operation.

Retrieving Credit Limits

Use PCM_OP_BILL_GET_LIMIT to retrieve the permanent and temporary credit limits for an account. To do so, pass in the account POID.

To retrieve credit limits based on specific criteria, also include the following optional input:

• A resource ID, such as 840 for US Dollars, to retrieve credit limits for a specific resource type.

• A balance group POID to retrieve credit limits for a specific balance group.

• A timestamp, such as 1956556800 for Jan 1 00:00:00 2032, where the timestamp falls between a credit limit's validity start date and validity end date (that is, validityStartDate < timestamp < validityEndDate). For example, if the timestamp is 1956556800, the opcode could return a credit limit with validity dates from December 15, 2031 through January 15, 2032, or with validity dates from December 29, 2031 through January 29, 2032.

The opcode returns details about the account's permanent credit limits in the PIN_FLD_LIMIT output flist array, and temporary credit limits in the PIN_FLD_TEMP_LIMIT output flist array.

Maintaining Subscriber's Charging Preferences Data

You can customize your external application to manage subscriber charging preferences during the account creation process by using the following opcodes:

• PCM_OP_CUST_SET_SUBSCRIBER_PREFERENCES

  This opcode creates, modifies, and deletes the /profile/subscriber_preferences object, which contains a subscriber's preference data. You can modify a specific preference or all of the subscriber's preferences.

  If a name for the profile object is not provided for PIN_FLD_NAME in the input flist, this opcode creates a profile with the default name PIN_Profile_Object.

  If the PIN_FLD_POID field in the input flist contains the complete POID of the /profile/subscriber_preferences object, this opcode modifies the data in the /profile/subscriber_preferences object.

  If the PIN_FLD_DELETED_FLAG field in the input flist is set to 1, PCM_OP_CUST_SET_SUBSCRIBER_PREFERENCES deletes the /profile/subscriber_preferences object.

• PCM_OP_CUST_GET_SUBSCRIBER_PREFERENCES

  This opcode retrieves the subscriber's preferences from the /profile/subscriber_preferences object.

  If the PIN_FLD_SUBSCRIBER_PREFERENCE_ID field is populated in the input flist, this opcode returns the data from the /profile/subscriber_preferences object for that preference only. Otherwise, this opcode returns all the preferences for the account.

Modifying Events before Sending Them to ECE

You can modify the BRM events that make up a business event before the business event is sent to Oracle DM for publishing to ECE. You do this by customizing the account synchronization policy opcode, PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT.

PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT modifies specified triggering events before they are included in a business event. This opcode can also be used to filter out certain events not included in account synchronization (for example, an event that has balance impacts only for currency balances), thereby reducing the traffic in the queue.

If you pass an event that does not need modification, PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT passes it directly to the Payload Generator External Module (EM) without modification.

You might want to modify an event to filter out unneeded data, which can improve performance if you publish large quantities of events. You can also use a flag to specify how adjustments should be applied to the account balance (for example, to permit the account to have a negative balance).

To modify a business event before sending it to ECE:

1. Ensure that all the BRM events that make up the business event are associated with opcode number 3626 (PCM_OP_IFW_SYNC_PUBLISH_EVENT) in your system's event notification list.

2. Use PCM_OP_IFW_SYNC_PUBLISH_EVENT to process the BRM events that make up the business event.

   See "Processing BRM Events That Make Up Account Synchronization Business Events".

3. Use PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT to customize the BRM events that make up the business event.

   See "Processing BRM Events That Make Up Account Synchronization Business Events".

Processing BRM Events That Make Up Account Synchronization Business Events

PCM_OP_IFW_SYNC_PUBLISH_EVENT passes BRM events that make up account synchronization business events to PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT for modification.

PCM_OP_IFW_SYNC_PUBLISH_EVENT is called by the event notification feature when an event associated with this opcode in your system's event notification list occurs.

By default, PCM_OP_IFW_SYNC_PUBLISH_EVENT does not modify events; it only passes them to the policy opcode.

If the BRM event is published in the business event, PCM_OP_IFW_SYNC_PUBLISH_EVENT returns one of the following POIDs:

• If the object passed in was an /event type object, the event POID is returned.

• If the object passed in was not an /event type object, a POID of type /publish is returned.

If the BRM event is not published (for example, if you filter out the event based on your business logic), the input flist is returned.

Modifying BRM Events That Make Up Account Synchronization Business Events

You can customize PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT to remove or enhance BRM events and event fields before they are assembled into business events and sent to ECE. For example, you can customize this opcode to do the following:

• Filter out BRM events that you do not want to include in published business events for various business or performance reasons.

  Note:

  • Do not filter out balance impact fields based on the balance element ID. If you do, you might remove fields needed by ECE.

  • Do not modify the code that prepares the login fields (the fm_ifw_sync_pol_prep_logins function). This code is required when a login is changed.

• Modify the value of the PIN_FLD_FLAGS field that is added to PIN_FLD_BAL_IMPACT arrays. This field specifies how to apply adjustments. For example, you can permit a negative balance by specifying a value of 4. If you permit a negative balance, the negative amount is deducted from the account balance with the next billing cycle.

  For example, you might use this method when a customer purchases a service that includes 60 minutes per month and cancels the service before the end of the month. If the customer used all 60 minutes but you prorate the minutes, the amount of usage for the canceled period can be deducted with the next billing cycle (provided the customer has a positive balance at that time).

If the BRM event is published in the business event, PCM_OP_IFW_SYNC_POL_PUBLISH_EVENT returns one of the following POIDs:

• If the object passed in was an /event type, the event POID is returned.

• If the object passed in was not an /event type object, a POID of type /publish is returned.

If the BRM event is not published (for example, if you filter out the event based on your business logic), the input flist is returned.

Rerating Opcodes

See the following topics:

• How BRM Tracks Rerated Events

• How BRM Creates Rerate Jobs

• How BRM Handles Duplicate Rerate Jobs

• Rerating Cycle Forward and Cycle Forward Arrears Events

• Customizing Event Searches for Rerating

• Customizing Automatic Creation of Rerate Jobs

How BRM Tracks Rerated Events

To back out and rerate events, BRM generates adjustment events (/event/billing/adjustment/event). These events contain all of the balance impacts in the original events to fully negate the events. When an event is rerated, the PIN_FLD_RERATE_OBJ field in the original rated event references this backout adjustment event.

When usage events are rerated, the new balance impacts of rerating are included in the same adjustment event that backs out the original balance impacts. This means the original event references the new event that contains the rerated balance impacts.

When cycle fee, cycle discount, fold, and rollover events are rerated, new cycle events are created to apply the balance impacts of rerating. In this case, there is no relationship between the original events and the new (cycle) events that contains the rerated balance impacts.

Because you can use flexible cycles and multiple discounts, there might be more than one rollover, fold, and discount event to rerate for a given billing cycle:

• A fold event is generated per balance for each balance that has a fold.

• A rollover event is generated per balance group for each charge offer that has a rollover.

• A discount event is generated for each cycle discount.

How BRM Creates Rerate Jobs

A rerate job is a pair of /job_batch/rerate and /job/rerate objects in the BRM database. There is a one-to-one relationship between /job/rerate objects and /job_batch/rerate objects, and both are created in the same transaction when one or more accounts are selected for rerating.

BRM uses the PCM_OP_RERATE_INSERT_RERATE_REQUEST opcode to create rerate jobs. This opcode is called by the following:

• The pin_rerate utility, which can be used to manually create rerate jobs

• BRM's automatic rerate job creation mechanism

• Your custom rerating configuration

PCM_OP_RERATE_INSERT_RERATE_REQUEST receives the following information in the input flist:

• The /account POIDs to rerate (required).

• The time from which events must be rerated for the accounts (required).

• Accounts related to the accounts to be rerated (for example, an account that used the account's service before a line transfer) along with the start time for each account.

  Note:

  If more than one account is included in the rerate job, the same rerate start time, selection criteria, and price overrides apply to all accounts.

• Your rerate reason (the default rerate reason passed in for BRM automatic rerating scenarios is 0).

• Your selection criteria to identify the events to rerate.

• A list of charge offers, discount offers, or bundles to override the subscriber's existing pricing components during rerating.

To create rerate jobs, PCM_OP_RERATE_INSERT_RERATE_REQUEST does the following:

1. Determines whether to check for duplicate rerate job requests by using the PIN_RERATE_FLG_MULTI_ACCT flag:

   • If the flag is set, the opcode skips the duplicate check.

   • If the flag is not set, the opcode performs the duplicate check. See "How BRM Handles Duplicate Rerate Jobs".

     Note:

     The PIN_RERATE_FLG_MULTI_ACCT flag is set when you run the pin_rerate utility with the -G groupOwnerPoid parameter. See "pin_rerate" in BRM Rerating Events.

2. Creates the /job/rerate and /job_batch/rerate objects.

BRM creates rerate jobs as follows:

1. An event occurs that requires accounts to be rerated.

2. The opcode that triggers rerate job creation when that particular event occurs creates a notification event.

3. The event notification mechanism calls PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST.

4. PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST takes as input the event type and the rerate reason code associated with the event and analyzes the event to determine if rerating is required.

   Note:

   BRM reserves the range of 100 to 120 for automatic rerating reason codes.

5. If rerating is required, PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST calls PCM_OP_RERATE_INSERT_RERATE_REQUEST along with the appropriate rerating criteria to create a rerate job.

   PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST takes as input the event type and the rerate reason code associated with the event. It analyzes the event to determine if rerating is required. If rerating is required, it sets the rerate reason code to 0 and calls PCM_OP_RERATE_INSERT_RERATE_REQUEST with the appropriate rerating criteria to create a rerate job.

   PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST calls PCM_OP_SUBSCRIPTION_INSERT_RERATE_REQUEST only when the reason code passed in is one of those reserved for automatic rerating (reason codes between 100 and 120). By default, if a different reason code is passed in, the opcode does nothing. To create rerate jobs for reason codes other than those reserved for automatic rerating, you must customize PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST.

   By default, PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST passes a reason code of 0 (no rerate reason) to PCM_OP_SUBSCRIPTION_INSERT_RERATE_REQUEST. To rerate accounts separately based on a rerate reason code, customize PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST to pass the rerate reason code it receives (or a different rerate reason code). The rerate reason code is stored in the rerate job object, and you can select rerate jobs based on the specific rerate reason code when you run pin_rerate to process rerate jobs.

   PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST only handles rerating events for BRM's default automatic rerating scenarios. If you do not want to rerate events for those scenarios or only want to rerate events for a few of them, you can customize this opcode to achieve those results.

   You can also customize PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST in other ways. For example, you can change whether rerate jobs are created for specific events: such as when you want to rerate events for only a few (rather than all) automatic rerating scenarios.

   PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST is not called by any opcode.

How BRM Handles Duplicate Rerate Jobs

PCM_OP_RERATE_INSERT_RERATE_REQUEST checks for existing jobs when a new rerate request is made. This opcode compares the data for each top-level account in the rerate request to the data in the existing jobs. To avoid duplicate rerate jobs, accounts are either eliminated from or updated in the rerate request or the existing jobs.

After the duplicate detection process is complete for each top-level account in the rerate request, PCM_OP_RERATE_INSERT_RERATE_REQUEST creates a rerate job with the resulting contents of the rerate request. It then performs checks on the sub-accounts in the rerate request to check for duplicate jobs for line transfers before creating the rerate job.

When the rerate reason code and rerate selection criteria for a rerate request match those of one or more rerate jobs, the request is considered a possible duplicate. When the rerate reason code and rerate selection criteria do not match, the rerate request is not a duplicate, and a new rerate job is created.

To avoid duplicate rerate jobs for an account, PCM_OP_RERATE_INSERT_RERATE_REQUEST compares the following values for duplicate rerate job requests:

• The rerate start times. BRM always uses the earlier start time to ensure that all events are rated.

• The price overrides (if any). BRM uses the latest price overrides for an account because it is assumed to be the most updated.

When the price overrides match, PCM_OP_RERATE_INSERT_RERATE_REQUEST does the following for each top-level account:

• If the rerate start time of the rerate request is later than or equal to the start time of the existing job:

  • If there is only this account in the rerate request, deletes the request. No rerate job is needed.

  • If there are many accounts in the new request, removes only that account from the new request.

• If the rerate start time of the rerate request is earlier than the start time of the existing job:

  • If the existing job contains only this account, updates the existing job to use the earlier start time and removes the account from the rerate request.

  • If the existing job contains other accounts, removes the account from the existing job, keeping the account in the rerate request.

When the price overrides do not match, PCM_OP_RERATE_INSERT_RERATE_REQUEST does the following for each top-level account:

• If the rerate start time of the rerate request is the same or earlier than the start time of the existing job:

  • If there is only one account in the existing job, deletes the job.

  • If there are many accounts in the existing job, keeps the account in the rerate request so the new rerate job start time and price overrides are used. Removes the account from the existing job.

• If the rerate start time of the rerate request is later than the start time of the existing job:

  • If there is only one account in the existing job, deletes the job.

  • If there are many accounts in the existing job, keeps the account in the rerate request so the new price overrides are used. Updates the rerate request start time to use the existing job's start time. Removes the account from the existing job.

Table 7-2 summarizes how PCM_OP_RERATE_INSERT_RERATE_REQUEST handles duplicate rerate job requests:

Table 7-2 Request Handling by PCM_OP_RERATE_INSERT_RERATE_REQUEST

If the Start Time of the New Request Is:	And the Price Overrides:	Perform This Action:
Equal to or later than that of the existing job	Match	If there is only this account in the rerate request, delete the request. No rerate job is needed. If there are many accounts in the rerate request, remove only that account from the rerate request.
Earlier than that of the existing job	Match	If there is only one account in the existing job: Update the existing job to use the earlier start time. Remove the account from the rerate request. If there are many accounts in the existing job: Keep the account in the rerate request. Remove the account from the existing job.
Later than that of the existing job	Do not match	If there is only one account in the existing job, delete the job. If there are many accounts in the existing job: Keep the account in the rerate request so the new price overrides are used. Update the rerate request job start time to use the existing job's start time. Remove the account from the existing job.
Equal to or earlier than that of the existing job	Do not match	If there is only one account in the existing job, delete the existing job. If there are many accounts in the existing job: Keep the account in the rerate request so the rerate request start time and price overrides are used. Remove the account from the existing job.

Rerating Cycle Forward and Cycle Forward Arrears Events

To rerate cycle forward and cycle forward arrears events, BRM uses PCM_OP_SUBSCRIPTION_RATE_CHANGE. This opcode uses the event notification mechanism to trigger the creation of rerating requests when there is a cycle-forward or cycle-forward-arrears event pricing change in the middle of the current cycle.

When you change a cycle fee by adding a new price tier in PDC or Pricing Center, the event notification feature triggers this opcode. This opcode reads the charge offers associated with the event and creates a /rate_change object, which is used by the pin_rate_change utility to create rerating requests. Rerating requests are used to create rerate jobs that are processed when you run the pin_rerate utility.

When you run the pin_rate_change utility after a pricing change, the utility calls PCM_OP_SUBSCRIPTION_RATE_CHANGE and provides details about the accounts and charge offers affected by the pricing change.

PCM_OP_SUBSCRIPTION_RATE_CHANGE returns a notification event of type /event/notification/rate_change for each account picked up by the pin_rate_change utility. Depending on how automatic rerating is configured, the notification event triggers the creation of rerating requests.

When you rerate cycle forward and cycle forward arrears events, you must track pricing changes. To do so, BRM uses PCM_OP_SUBSCRIPTION_PREP_RATE_CHANGE.

This opcode creates the /rate_change object, which stores details about the charge offers affected by a pricing change.

When you change a cycle fee by adding a new price tier, BRM event notification triggers this opcode. This opcode reads the charge offers associated with the event and creates a /rate_change object, which is used by the pin_rate_change utility to create rerating requests.

Customizing Event Searches for Rerating

You can further refine the event selection criteria used for rerating by customizing PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE. This opcode is called when the pin_rerate utility is run with -r parameter to indicate selective rerating.

Note:

An alternative to customizing this opcode to filter the events selected for rerating is to create custom pin_rerate parameters instead.

This opcode is called by PCM_OP_SUBCRIPTION_RERATE_REBILL.

PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE receives an event search template that is based on the account and event selection criteria specified in the pin_rerate command line: for example, to select events related to services specified by the -s parameter.

By default, PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE does not change the search template and returns a copy of the input flist in the output flist.

You can customize the search template in the input flist to rerate specific types of events. Most customizations include changes only to the fields listed in Table 7-3:

Table 7-3 Fields to Customize

Field	Description
PIN_FLD_TEMPLATE	The modified search template.
PIN_FLD_ARGS	The list of search arguments. Note: This list must match the list of arguments in PIN_FLD_TEMPLATE. It is preferable to have arguments of one type only. For example, an event search based on charge offer objects.

PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE receives the following fields in the RESULTS array from PCM_OP_SUBSCRIPTION_RERATE_REBILL:

• PIN_FLD_POID

• PIN_FLD_CREATED_T

• PIN_FLD_EFFECTIVE_T

• PIN_FLD_END_T

• PIN_FLD_SERVICE_OBJ

• PIN_FLD_ACCOUNT_OBJ

• PIN_FLD_UNRATED_QUANTITY

• PIN_FLD_RERATE_OBJ

• PIN_FLD_BAL_IMPACTS [*]

• PIN_FLD_SUB_BAL_IMPACTS [*]

  Note:

  • To assure that the existing mandatory fields in the array are passed back, avoid customizing the RESULTS array. Extra fields added to the array are retrieved but ignored by the standard opcode.

  • Test your customized template to ensure that it works properly before using it with a working database. Use the -e and -c parameters with the pin_rerate utility to test your modifications.

PCM_OP_SUBSCRIPTION_POL_SPEC_RERATE returns the search template that PCM_OP_SUBSCRIPTION_RERATE_REBILL uses to find events in selected accounts that need rerating.

PCM_OP_SUBSCRIPTION_RERATE_REBILL rerates the events for accounts identified by the pin_rerate utility, rerating one account at a time. The rerating start time is specified on the input flist. This opcode calls other opcodes to perform rerating functions.

Customizing Automatic Creation of Rerate Jobs

You can customize automatic creation of rerate jobs. For example, if you rerate usage following a charge offer cancellation, you can set up a charge offer cancellation event to automatically create a rerate job.

To customize automatic creation of rerate jobs, you set up event notification to call a custom opcode that analyzes events to determine if rerating is required. For example, the criteria for rerating might be:

• If the event is a cancel event.

• If the cancel event for a charge offer requires proration on cancellation.

• If rerating needs to occur to calculate proration for this charge offer.

To customize automatic creation of rerate jobs, you must write custom code to specify when to create rerate jobs automatically when certain events occur. You can do one of the following:

• Create one or more custom opcodes. You can create multiple custom opcodes to handle rerating events for different scenarios or create one opcode to handle all scenarios.

• Modify PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST.

Customized automatic rerating works as follows:

1. An event that you have configured in event notification occurs to call the custom opcode. All the fields in the event are passed as input to the custom opcode.

2. The custom opcode analyzes the event using your custom selection criteria to determine if it should trigger rerating.

3. If the event creates a rerate job because it matches your selection criteria, the custom opcode assigns an optional rerate reason code for rerating those events, and specifies any price overrides.

4. PCM_OP_RERATE_INSERT_RERATE_REQUEST creates a rerate job that includes:

   • The account that needs to be rerated.

   • The events that must be rerated for that account.

   • The start time from which to rate the events.

   • The rerate reason.

   • Price overrides, if any.

     Note:

     If more than one account is included in the rerate job, the same selection criteria, price overrides, and start time apply to all the accounts.

5. You run the pin_rerate utility to run the rerate job and rerate the events.

Figure 7-1 shows the rerating process when a purchase event occurs:

Figure 7-1 Customized Automatic Rerating Process

Description of "Figure 7-1 Customized Automatic Rerating Process"

Creating a Custom Opcode for Rerating

Your custom code is required to pass the following to PCM_OP_RERATE_INSERT_RERATE_REQUEST:

• The POIDs of the accounts to be rerated.

  You can also pass in an optional array of additional accounts that are related to these accounts (for example, an account that used the account's service before a line transfer) and the start time for each account.

  Note:

  If an array of accounts is passed in, the same selection criteria and price overrides apply to all the accounts.

• The time from which events must be rerated for the accounts.

Your custom code can optionally pass in the following to PCM_OP_RERATE_INSERT_RERATE_REQUEST:

• A rerate reason code to take advantage of rerating according to type of rerate job. See "Specifying a Rerate Reason Code".

• Selection criteria so that only those events that are required for rerating are identified for an account. See "Specifying Selection Criteria".

• Price overrides to substitute an account's subscribed pricing for alternate pricing during rerating. See "Specifying Price Overrides".

When an event triggers your custom opcode, your opcode may need to obtain data from other events in the database to obtain all of the information required for rerating.

Specifying a Rerate Reason Code

PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST or your custom opcode can pass an optional rerate reason code to PCM_OP_RERATE_INSERT_RERATE_REQUEST. The rerate reason code is stored in the rerate job and can be used to select jobs from the rerate queue for rerating using pin_rerate.

Your rerate reason codes can be any integer, except 1 (1 is reserved for internal use).

Note:

Because you can use multiple rerate reason codes to group rerate jobs for different rerating scenarios, ensure that your rerate reason codes are unique.

The default reason code is 0.

Specifying Selection Criteria

When an account needs to be rerated, not every event for that account may need to be rerated. Your custom opcode can optionally send selection criteria to PCM_OP_RERATE_INSERT_RERATE_REQUEST to select only the subset of events that needs to be rerated.

For example, you may need to rerate events only when they are generated by a specific service or only when they are rated by a specific charge offer or discount offer. You can specify selection criteria to rerate all accounts' events that have an event type of /event/delayed/session/telco/gsm/telephony but only when they are for the service type /service/telco/gsm/telephony and only when they are rated by the charge offer GSM Voice Telephony.

Your selection criteria can be any of the following:

• Event types (array PIN_FLD_EVENTS)

• Service types (array PIN_FLD_SERVICES)

• /product object POIDs (array PIN_FLD_PRODUCTS)

• /discount object POIDs (array PIN_FLD_DISCOUNTS)

• /deal object POIDs (array PIN_FLD_DEALS)

  Note:

  Charge offers and discount offers are mutually exclusive with bundles. Bundles include charge offers and discount offers, so you can pass in a bundle array instead of the charge offer array and discount offer array.

Specifying Price Overrides

You can specify charge offers, discount offers, or bundles to use for a specific rerate job to override an account's subscribed charge offers, discount offers, or bundles during rerating. The price override applies only to that rerate job; subsequent rerate jobs use the subscribed pricing or their own override pricing.

Your custom opcode can send the following price override data to PCM_OP_RERATE_INSERT_RERATE_REQUEST to set a price override for a rerate job:

• An optional array of override charge offer POIDs along with the charge offer it is overriding (PIN_FLD_OVERRIDE_PRODUCTS).

• An optional array of override discount offer POIDs along with the discount offer it is overriding (PIN_FLD_OVERRIDE_DISCOUNTS).

• An optional array of override /deal object POIDs along with the bundle it is overriding (PIN_FLD_OVERRIDE_DEALS).

  Note:

  Charge offers and discount offers are mutually exclusive with bundles because bundles include charge offers and discount offers. The bundle is translated to a list of charge offers and discount offers when it is passed to the rerating opcodes.

The override charge offers and discount offers or bundles must already be defined in your BRM database. They must also be functionally equivalent to the subscribed charge offers and discount offers or bundles; for example, the priority or service-event map would be the same. In addition, override charge offers and discount offers cannot be configured as first usage charge offers.

Note:

You must rerate accounts when an override pricing charge offer is canceled in a given billing cycle so that refunds can be applied correctly.

BRM creates a record when rerating is run with price overrides by using the /rerate_session/override_info object. When override pricing is passed to PCM_OP_SUBSCRIPTION_RERATE_REBILL, this opcodes creates a /rerate_session/override_info object to capture the override pricing information used during rerating.

Configuring Event Notification for Customized Automatic Rerating

When you configure event notification for rerating, you specify the following in the pin_notify file in BRM_home/sys/data/config (or your own merged event notification configuration file):

• The events that trigger rerating.

• The custom opcodes you want BRM to use to analyze the events, to identify whether rerating is required.

To configure event notification for rerating, do the following:

1. If your system has multiple configuration files for event notification, merge them.

2. Ensure that the merged file includes the events you want to trigger rerating and the opcode number of the custom opcode you want to analyze those events.

   For example, these entries call the custom opcode with opcode number 10000:

   # Event notification for rerating
   10000    0    /event/customer/status
   10000    0    /event/billing/product/action/purchase
   

3. (Optional) Add, modify, or delete entries in your final event notification list.

4. (Optional) Create custom code for event notification to trigger.

5. Load your final event notification list into the BRM database.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Configuring Event Notification for Override Pricing

If you use override pricing, you must customize automatic rerating to rerate accounts for cases where a refund could not be applied because an override pricing charge offer was canceled in a given billing cycle.

For a given billing cycle, if you rerate an account with an override charge offer and the charge offer is canceled, BRM cannot calculate a refund for that account because the charge offer is not available to apply the necessary cycle fees. When the refund cannot be applied, BRM creates the notification event /event/notification/product/cancel/no_refund.

To calculate the correct refund amount, you must customize rerating as follows:

1. Write custom code to specify:

   • The account to rerate from the /event/notification/product/cancel/no_refund event.

   • The charge offer to use to apply the cycle fees for the refund to use the override charge offer that was canceled.

     BRM uses the base charge offer associated with the account if you do not specify the override charge offer that was canceled. To specify the override charge offer that was canceled, obtain its information from the latest /rerate_session/override_info object created for the given account.

2. Include your code in a custom opcode or in PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST that handles automatic rerating (opcode number 3787).

   If you create a custom opcode, it must call PCM_OP_RERATE_INSERT_RERATE_REQUEST to create the rerate job.

3. Set up event notification for the event /event/notification/product/cancel/no_refund to call your custom opcode or the policy opcode. For example, to call PCM_OP_SUBSCRIPTION_POL_GENERATE_RERATE_REQUEST, you would enter:

   # Event notification for automatic rerating
   3787    0    /event/notification/product/cancel/no_refund
   

Suspense Management

See the following topics:

• Recycling Suspended Records

• Initiating Suspense Recycling

• Changing the Contents of Fields in Suspended Event Records

• Undoing Edits to Suspended Event Records

• Deleting Suspended Records

• Writing Off Suspended Records

• Processing Suspended Records in Bulk

• Suspended Call Record States

Suspended Call Record States

As suspended records are processed by Suspense Manager, they are assigned one of the following states:

• Suspended. The record could not be processed by Offline Mediation Controller.

• Recycling. The record is being sent through Offline Mediation Controller again to be rated.

• Succeeded. The record has been successfully recycled and rated.

• Written off. The record will not be recycled, but is being stored for further use.

Table 7-4 lists the details about the states:

Table 7-4 Suspended Call Record States

State	PIN_FLD_STATUS value in /suspended_usage	Can be edited	Can be recycled	Can be written off	Can be deleted	Can be archived and deleted
Suspended	0	Yes	Yes	Yes	No	No
Recycling	1	No	No	No	No	No
Succeeded (Successfully processed)	2	No	No	No	Yes	Yes
Written off	3	No	No	No	Yes	Yes

Recycling Suspended Records

PCM_OP_SUSPENSE_SEARCH_RECYCLE searches for and queues suspended call records for recycling. There are many search criteria that you may use to search the records, such as by CDR file or by recycle key.

You can specify the following criteria:

• A recycle key

• A CDR file

• A search template

PCM_OP_SUSPENSE_SEARCH_RECYCLE is usually called by the pin_recycle utility, which searches for and deletes call records with a specific recycle key and a status of Succeeded (or Written-off).

Searching for Records in a CDR File

The BRM standard recycling feature collects and manipulates all calls contained in a CDR file at the same time. PCM_OP_SUSPENSE_SEARCH_RECYCLE searches for a specified CDR file and queues its suspended event records for recycling. If successful, the event records are assigned a status of Succeeded.

Searching for Records with a Recycle Key

PCM_OP_SUSPENSE_SEARCH_RECYCLE is used by features that must temporarily delay rating of event records. This opcode searches for all Suspended call records containing the recycle key passed in on the input flist. It then queues those call records to be rated at the next opportunity. If successful, the event records are assigned a status of Succeeded.

Initiating Suspense Recycling

PCM_OP_SUSPENSE_RECYCLE_USAGE initiates event record recycling. The Suspense Management Center calls this opcode when the user chooses to recycle suspended event records.

PCM_OP_SUSPENSE_RECYCLE_USAGE can operate in test mode. In test mode, the event record is processed normally. The results, however, are not output if the event record is processed successfully.

PCM_OP_SUSPENSE_RECYCLE_USAGE takes as input an array of /suspended_usage object POIDs, a list of suspense override reasons, and a value that indicates whether the event records should be recycled in test mode. This opcode then creates an /admin_action/suspended_usage/recycle object with that information.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_RECYCLE_USAGE performs these operations:

• Confirms that the suspended event record has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.

• Changes the event record status to Recycling. The value of the PIN_FLD_STATUS field in the /suspended_usage object is set to 1.

• Creates an /admin_action/suspended_usage/recycle object containing the recycle mode and override reasons (passed in the input flist).

• Adds the POID of the newly created /admin_action/suspended_usage/recycle object to the actions array of each /suspended_usage object.

• Sets the PIN_FLD_RECYCLE_OBJ field of each /suspended_usage object to the /admin_action/suspended_usage/recycle object POID.

After event records are recycled, their /suspended_usage objects are updated by using the Suspended Event (SE) Loader:

• If an event record is successfully recycled, the status is changed to Succeeded, and the PIN_FLD_STATUS value is changed to 2.

• If an event record is not successfully recycled, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. In addition, the following fields are updated because their original values could have changed:

  • The suspense reason code, PIN_FLD_SUSPENSE_REASON.

  • The suspense subreason code, PIN_FLD_SUSPENSE_SUBREASON.

• If PCM_OP_SUSPENSE_RECYCLE_USAGE was run in test mode, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. The corresponding test values (PIN_FLD_TEST_SUSPENSE_REASON, PIN_FLD_TEST_SUSPENSE_SUBREASON, and PIN_FLD_TEST_SUSPENSE_ERROR_CODE) are updated to include information about the results of the test recycling.

• The number of times the record has been recycled (in PIN_FLD_NUM_RECYCLES) is increased by 1.

PCM_OP_SUSPENSE_RECYCLE_USAGE returns the routing POID specified in the input flist.

Resubmitting Suspended Batches

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES resubmits suspended CDR file. Suspense Management Center calls this opcode when the user chooses to resubmit suspended batches.

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES takes an array of /suspended_batch object POIDs and a list of suspense override reasons as input. This opcode then creates an /admin_action/suspended_batch/resubmit object with that information.

For the whole set of /suspended_batch objects specified in the input flist, PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES performs these operations:

• Creates a transaction if it is not already opened.

• Creates an ADMIN_ACTION object, /admin_action/suspended_batch/resubmit, with the override reason, for each /suspended_batch object.

• Validates the status of each /suspended_batch object (Batch Suspense Record) and updates the status with the result of the resubmission.

• Creates an event Flist (with /event/notification/suspense/batch_resubmit) and calls PCM_OP_ACT_USAGE in CALC_ONLY mode.

• Closes the transaction

After CDR file are resubmitted, their /suspended_batch objects (Batch Suspense Records) are updated by using the SE Loader:

• The PIN_FLD_NUM_RESUBMISSIONS field in each /suspended_batch object is incriminated.

• If a batch is successfully resubmitted, the status is changed to Succeeded, and the PIN_FLD_STATUS value is changed to 2.

• If a batch is not recycled successfully, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. This will cause all the batches in the resubmission task to be rolled back as well. In addition, these fields are updated because their original values could have changed:

  • The suspense reason code, PIN_FLD_BATCH_SUSPENSE_REASON.

  • The suspense sub-reason code, PIN_FLD_BATCH_SUSPENSE_SUBREASON.

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES returns the routing POID specified in the input flist.

Changing the Contents of Fields in Suspended Event Records

Use PCM_OP_SUSPENSE_EDIT_USAGE to change the contents of fields in suspended event records. Suspense Management Center calls this opcode to edit a suspended call record.

Note:

You cannot edit the CDR or event record fields of records in a CDR file that has been suspended by batch suspense and has a Batch Suspense Record.

PCM_OP_SUSPENSE_EDIT_USAGE performs these operations:

• Takes as input an array of /suspended_usage object POIDs and an array of the event record fields to be edited, including the old and new values.

• For each event record field to be edited, this opcode:

  • Creates an /admin_action/suspended_usage/edit object, which includes both the old and new values.

  • Adds the /admin_action/suspended_usage/edit object POID to the top of the /suspended_usage_edits object stack. If the stack is full, it removes the oldest POID.

• For each /suspended_usage object, this opcode:

  • Confirms that the suspended event record has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.

  • Adds the /admin_action/suspended_usage/edit object POID and the old value to each /suspended_usage object's action array.

  • Updates the modified flag (PIN_FLD_EDITED), which indicates that the field has been edited.

PCM_OP_SUSPENSE_EDIT_USAGE returns an array of the POID of the /admin_action/suspended_usage/edit objects it creates.

Undoing Edits to Suspended Event Records

Use PCM_OP_SUSPENSE_UNDO_EDIT_USAGE to undo edits to suspended event records.

This opcode is called by Suspense Management Center to the undo edits. It replaces the value of a field in a suspended call record with the value in that field before the last edit was made.

PCM_OP_SUSPENSE_UNDO_EDIT_USAGE performs these operations:

• Searches for the /suspended_usage_edits object If a /suspended_usage_edits object exists, this opcode reads and locks it.

• Confirms that the POID of the /admin_action/suspended_usage/edit object on the input flist matches that of the top POID of the /suspended_usage_edits object stack. If the two don't match, returns failure status (PIN_FLD_RESULT is set to 1) and returns the POID at the top of the /suspended_usage_edits object stack.

• Confirms that each suspended call record affected by the edit has a status of Suspended.

• Undoes the edit by replacing the existing field values with the values before the last edit was saved (the values referenced by the POID at the top of the /suspended_usage_edits object stack).

• Adds the session, service, and date and time details of the undo edit operation in the PIN_FLD_UNDO_DATA array of the /admin_action/suspended_usage/edit object.

• Removes the POID of the /admin_action/suspended_usage/edit object from the top of the /suspended_usage_edits object stack.

PCM_OP_SUSPENSE_UNDO_EDIT_USAGE returns a PIN_FLD_RESULT value of:

• 0 if the undo edit was successful. Also:

  • The PIN_FLD_POID field contains the POID of the /admin_action/suspended_usage/edit object.

  • The PIN_FLD_COUNT field contains the number of records that were processed.

• 1 if the /admin_action/suspended_usage/edit POID in the input flist does not match the POID at the top of the /suspended_usage_edits object stack.

Deleting Suspended Records

Use PCM_OP_SUSPENSE_DELETE_USAGE to delete suspended event records.

The Suspense Management Center calls this opcode to delete event records. Event records can be deleted only if their status is Written-off or Succeeded.

PCM_OP_SUSPENSE_DELETE_USAGE takes as input an array of /suspended_usage object POIDs to be deleted.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_DELETE_USAGE performs these operations:

• Confirms that the suspended event record has a status of Succeeded or Written off. The value of the PIN_FLD_STATUS field in the /suspended_usage object must be 2 or 3.

• Deletes the /suspended_usage object.

• Generates a /event/notification/suspense/delete object that records the deletion.

PCM_OP_SUSPENSE_DELETE_USAGE returns the routing POID specified in the input flist.

Deleting Records for Suspended Batches

Use PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES to delete /suspended_batch objects (Batch Suspense Records).

Note:

This opcode deletes records, not the files associated with them.

Suspense Management Center calls this opcode to delete Batch Suspense Records (/suspended_batch objects). Batch Suspense Records can be deleted only if their status is Written-off or Succeeded.

PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES takes as input an array of /suspended_batch object POIDs to be deleted.

For each /suspended_batch object specified in the input flist, PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES performs these operations:

• Creates a transaction if it is not already opened.

• Confirms that the suspended batch file has a status of Succeeded or Written-off. The value of the PIN_FLD_STATUS field in the /suspended_batch object must be 2 or 3. Otherwise, an error code is generated and the transaction ends.

• Deletes the /suspended_batch object.

• Generates an /event/notification/suspense/batch_delete event.

• Closes the transaction.

PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES returns the routing POID specified in the input flist.

Deleting Call Records with a Specific Recycle Key and a Status of Succeeded or Written-Off

Use PCM_OP_SUSPENSE_SEARCH_DELETE to delete call records with a specific recycle key and a status of Succeeded or Written-off.

You can specify the following criteria:

• A recycle key

• A CDR file

• A search template

This opcode can also delete a suspended call record if PIN_FLD_MODE is set correctly.

To search for and recycle suspended call records containing a specific recycle key, use PCM_OP_SUSPENSE_EDIT_USAGE.

Set the PIN_FLD_FLAGS field to either of these values:

• 0: Directs PCM_OP_SUSPENSE_EDIT_USAGE to delete event records with a status of:

  • Succeeded (successfully processed)

  • Written-off

• 1: Directs PCM_OP_SUSPENSE_EDIT_USAGE to delete event records with a status of:

  • Succeeded (successfully processed)

  • Written-off

  • Suspended. PCM_OP_SUSPENSE_EDIT_USAGE first writes off, then deletes, these event records

Deleting Records in a CDR File

PCM_OP_SUSPENSE_SEARCH_DELETE is used with the BRM standard recycling feature, which acts on all the calls contained in a single CDR file simultaneously. Using pin_recycle with the -d parameter deletes all calls in a CDR file that have a status of Succeeded. Using pin_recycle with the -D parameter deletes all calls in a CDR file with a status of Succeeded or Written off.

PCM_OP_SUSPENSE_SEARCH_DELETE is also used by features that must temporarily delay rating of event records. The error prevents event records from being rated by assigning them a status of Suspended. Those features then use PCM_OP_SUSPENSE_EDIT_USAGE to find and recycle the call records. If successful, the event records are assigned a status of Succeeded. PCM_OP_SUSPENSE_SEARCH_DELETE then deletes those successfully recycled call records.

Writing Off Suspended Records

Use PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE to write off suspended event records.

When a suspended event record is written off, it can no longer be edited or recycled.

PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE takes as input an array of /suspended_usage object POIDs.

• PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE creates an /admin_action/suspended_usage/writeoff object that records the write-off.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE performs these operations:

• Confirms that the suspended event record has a status of Suspended; the PIN_FLD_STATUS value must be 0.

• Adds the POID of the newly created /admin_action/suspended_usage/writeoff object to the array of actions in the /suspended_usage object.

• Changes the status to Written-off. The value of the PIN_FLD_STATUS field in the /suspended_usage object is changed to 3.

• Generates an /event/notification/suspense/batch_writeoff event.

PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE returns the POID of the /admin_action/suspended_usage/writeoff object created.

Writing Off Suspended Batches

Use PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES to write off suspended CDR files.

When you write off a suspended CDR file, you can no longer resubmit it, but you can delete it.

The opcode creates an /admin_action/suspended_batch/writeoff object that records the write-off and sets the status of the Batch Suspense Record (/suspended_batch) to Written-off.

PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES performs these operations:

• Create a transaction if it is not already opened.

• Confirms that the suspended event record has a status of Suspended; the PIN_FLD_STATUS value must be 0.

• PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES takes as input an array of /suspended_batch object POIDs.

• Adds the POID of the newly created /admin_action/suspended_batch/writeoff object to the array of actions in the /suspended_batch object.

• Changes the status of the Batch Suspense Record (/suspended_batch) to Written off; The value of the PIN_FLD_STATUS field in /suspended_batch is changed to 3.

• Generates an /event/notification/suspense/batch_writeoff event.

• Closes the transaction.

PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES returns the POID of the /admin_action/suspended_batch/writeoff object created.

Processing Suspended Records in Bulk

You can use the Suspense Manager opcodes to edit, delete, recycle, and write off a large number of suspended records. For more information, see the following topics:

• Processing Suspended Records in Multiple Steps

• Editing Suspended Records in Bulk

• Writing Off Suspended Batches

• Deleting Suspended Records in Bulk

Processing Suspended Records in Multiple Steps

You can process suspended records in multiple steps by calling the opcodes multiple times to avoid a large database transaction:

1. Specify the number of records to process in each opcode call in a configuration file, and load the file into the /config/pin_suspense_system_params storable class.

2. Call the opcode in calc-only mode to retrieve the count and POID range of the records that match your search criteria.

3. Use a simple logic to determine the number of times to call the opcodes depending on the number of records you want each opcode call to process.

4. Call the opcode several times with a set of records each time and consolidate the results returned by each opcode call.

   Note:

   For each opcode call, you must provide the POID range and the corresponding arguments in the input flist.

Because each operation is performed in multiple steps, if the operation is successful in any of the steps, you get the number of records processed. You also get an error message for the unsuccessful records, which you can display to the user. If any one of the steps fails, the entire step and the following steps are canceled and an error message is returned.

Note:

Suspense Management Center and the pin_recycle utility perform suspense management operations in multiple steps by calling the opcodes multiple times.

Editing Suspended Records in Bulk

Use PCM_OP_SUSPENSE_SEARCH_EDIT to perform the same set of edits on a large number of suspended records that meet the criteria you specify.

This opcode makes changes to the records in one database operation instead of accessing the database for each record. It calls the following opcodes:

• PCM_OP_BULK_WRITE_FLDS, to update the objects in the database.

  The opcode finds the accounts that meet the criteria specified in PIN_FLD_ARGS and updates them with the information in PIN_FLD_VALUES.

  Specify the fields and values to set, along with the POID type of the object, in the input flist. You must update at least one field.

  Use the PCM_OPFLG_ADD_ENTRY flag to create array elements. If the specified array element already exists, this flag is ignored. PCM_OPFLG_ADD_ENTRY cannot be used to create ordinary fields.

  The opcode returns the POID type and count of the object whose fields were updated.

• PCM_OP_ACT_USAGE, to generate the edit event notification.

  Note:

  You cannot undo edits performed on a large number of records or any edits made before the bulk edit operation.

PCM_OP_SUSPENSE_SEARCH_EDIT follows these steps to edit suspended records:

1. Takes as input the following information:

   • The POID type of the suspended usage class.

   • The search criteria template.

   • The fields and values that must be edited in the object.

   • An array of the event record fields to be edited, including the old and new values.

2. Does one of the following:

   1. If the PCM_OPFLG_CALC_ONLY flag is set, returns the count and the POID range of records that meet the search criteria.

   2. If the PCM_OPFLG_CALC_ONLY flag is not set, searches for the /suspended_usage_edits objects.

3. Does one of the following:

   1. If it finds /suspended_usage_edits objects, clears all the POIDs of the edit actions stored in the objects.

      Note:

      After the objects are changed, the current changes or previous changes cannot be undone.

   2. If it does not find a /suspended_usage_edits object, creates a new /suspended_usage_edits object.

4. For each event record field to be edited, creates an /admin_action/suspended_usage/edit object, which includes both the old and new values.

5. For each /suspended_usage object, performs the following operations:

   • Verifies that the suspended event record has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.

   • Adds the /admin_action/suspended_usage/edit object POID and the old value to each /suspended_usage object's action array.

   • Updates the PIN_FLD_EDITED field to indicate that the field has been edited.

If successful, PCM_OP_SUSPENSE_SEARCH_EDIT generates an edit notification event that includes the administrative action POID of the edit action and returns success along with the count of the objects edited. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.

Writing Off Suspended Records in Bulk

Use PCM_OP_SUSPENSE_SEARCH_WRITE_OFF to write off all suspended records that meet the criteria you define.

Note:

You cannot edit or recycle suspended records that are written off.

This opcode writes off a large set of suspended records in one database operation instead of accessing the database for each record. It calls the following opcodes:

• PCM_OP_BULK_WRITE_FLDS to mark a large number of objects in the database as written off.

• PCM_OP_ACT_USAGE to generate the write-off event notification.

PCM_OP_SUSPENSE_SEARCH_WRITE_OFF follows these steps to write off suspended records:

1. Takes as input the POID type of the suspended usage class and the search criteria template for the objects to be written off.

2. If the PCM_OPFLG_CALC_ONLY opcode flag is set, returns the count of records that match the search criteria and the POID range of the records that satisfy the criteria.

3. If the PCM_OPFLG_CALC_ONLY flag is not set, creates the /event/notification/suspense/batch_writeoff object that records the write off and returns that object with the count of records written off.

4. For each /suspended_usage object that meets the criteria specified in the template, performs these operations:

   • Verifies that the suspended event record has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.

   • Adds the POID of the newly created /admin_action/suspended_usage/writeoff object to the array of actions in the /suspended_usage object.

   • Changes the status to Written-off. The value of the PIN_FLD_STATUS field in the /suspended_usage object is changed to 3.

If successful, PCM_OP_SUSPENSE_SEARCH_WRITE_OFF generates a write-off notification event that includes the administrative action POID of the write-off action and returns success along with the number of records written off. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.

Deleting Suspended Records in Bulk

Use PCM_OP_SUSPENSE_SEARCH_DELETE to delete all suspended records that meet the criteria you define. This opcode is scheduled to run at a later time to ensure revenue assurance.

Note:

You can only delete records that are succeeded or written off.

PCM_OP_SUSPENSE_SEARCH_DELETE deletes a large set of suspended records in one database operation instead of accessing the database for each record. It calls PCM_OP_ACT_USAGE to generate the delete event notification.

PCM_OP_SUSPENSE_SEARCH_DELETE follows these steps to delete suspended records:

1. Takes as input the POID type of the suspended usage class and the search criteria template for the objects to be deleted.

2. If the PCM_OPFLG_CALC_ONLY opcode flag is set, returns the count of records that match the search criteria and the POID range of the records that satisfy the criteria.

   If the PCM_OPFLG_CALC_ONLY flag is not set, creates the /event/notification/suspense/batch_delete object that records the deletion.

3. For each /suspended_usage object that meets the criteria specified in the template, performs these operations:

   • Verifies that the suspended event record has a status of Succeeded or Written off. The PIN_FLD_STATUS value in the object must be 2 or 3.

   • Event records with a status of Succeeded and those with a status of Written off that do not have a deferred duration are deleted immediately.

   • If the status of the suspended record is Written off, the opcode checks if there is a deferred duration and if the deferred duration is greater than 0. The deferred duration is a parameter defined in the /config/suspense_params object.

     Note:

     The load utility is provided to load the deferred duration parameter.

     If there is a deferred duration, then PCM_OP_SUSPENSE_SEARCH_DELETE will not remove the suspended record from the database but rather change the status of the suspended records from written off to delete pending. PCM_OP_SUSPENSE_SEARCH_DELETE will create a schedule object to run PCM_OP_SUSPENSE_DEFERRED_DELETE.

   • The schedule object will call PCM_OP_SUSPENSE_DEFERRED_DELETE to be run at the deferred duration time.

   • PCM_OP_SUSPENSE_SEARCH_DELETE or PCM_OP_SUSPENSE_DEFERRED_DELETE deletes the object from the suspense db.

4. Generates a /event/notification/suspense/delete object that records the deletion for each suspended record that was deleted.

If successful, PCM_OP_SUSPENSE_SEARCH_DELETE generates a delete notification event that includes the administrative action POID of the delete action and returns success along with the number of records deleted. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.

Provisioning Process Opcode Flow

Services Framework provisioning generates service orders as follows:

1. A customer account creates or modifies a service, device, or profile. This generates a notification event.

2. The event notification system calls the opcode specified in the /config/notify object. By default, PCM_OP_TCF_PROV_CREATE_SVC_ORDER is called.

3. PCM_OP_TCF_PROV_CREATE_SVC_ORDER performs the following:

   1. Determines whether the service type passed in the input flist is supported by Services Framework. All telco service types and all service types listed in the /config/service_framework/permitted_service_types object are supported.

   2. Determines the provisioning configuration object to use.

   3. Determines the service order configuration object to use.

   4. Generates the service order business event (/event/provisioning/service_order/telco/*).

      Note:

      The service order business event contains “telco" in its name for both telco and nontelco service types, because the common substruct for holding the service order data is at the /event/provisioning/service_order/telco level.

4. The event notification system calls the opcode specified in the /config/notify object. By default, PCM_OP_TCF_PROV_HANDLE_SVC_ORDER is called.

5. PCM_OP_TCF_PROV_HANDLE_SVC_ORDER performs the following:

   1. Determines whether the service order status is NEW. If it is, the opcode calls PCM_OP_TCF_PROV_SERVICE_ORDER_SET_STATE to update the service order status to READY.

      PCM_OP_TCF_PROV_SERVICE_ORDER_NOTIFY performs service order state changes. PCM_OP_TCF_PROV_SERVICE_ORDER_SET_ATTR ppdates a service order object.

   2. Determines whether to call the Network Simulator by reading the simulate_agent entry in the CM pin.conf file. If simulate_agent is set to 1, the opcode calls PCM_OP_TCF_PROV_SIMULATE_AGENT to simulate the provisioning flow with the CM.

   3. Determines the provisioning mode for the service type by reading the /config/service_framework/permitted_service_types object. The default is Queued.

   4. Calls PCM_OP_TCF_POL_PROV_HANDLE_SVC_ORDER with the service order event details and provisioning mode.

6. PCM_OP_TCF_POL_PROV_HANDLE_SVC_ORDER performs any custom actions before it is passed to dm_prov_telco, and then returns to the calling opcode. This opcode dis an empty hook, but you can customize it to override the provisioning mode and modify service order event details.

7. PCM_OP_TCF_PROV_HANDLE_SVC_ORDER calls PCM_OP_PROV_PUBLISH_SVC_ORDER to publish the service order.

8. PCM_OP_PROV_PUBLISH_SVC_ORDER publishes the service order to dm_prov_telco.

9. dm_prov_telco determines the provisioning mode by reading the PIN_FLD_MODE flist entry. dm_prov_telco operates in Queued mode when the entry is 0 and Confirmed mode when the entry is 1.

   • In Queued mode, dm_prov_telco queues the request in-memory and calls PCM_OP_TCF_PROV_SERVICE_ORDER_SET_STATE to update the service order status to PROVISIONING.

   • In Confirmed mode, dm_prov_telco sends the service order to the network provisioning agent through a TCP/IP connection and waits for a response.

After the network provisioning agent returns a response in flist format, Services Framework provisioning performs the following:

1. dm_prov_telco sends the response to PCM_OP_PROV_PUBLISH_SVC_ORDER.

2. PCM_OP_PROV_PUBLISH_SVC_ORDER passes the response to PCM_OP_TCF_PROV_HANDLE_SVC_ORDER.

3. PCM_OP_TCF_PROV_HANDLE_SVC_ORDER calls PCM_OP_PROV_UPDATE_SVC_ORDER to update the service order status.

4. PCM_OP_PROV_UPDATE_SVC_ORDER changes the service order status to Processed and generates the /event/provisioning/service_order/telco/* business event.

5. PCM_OP_TCF_PROV_UPDATE_SVC_ORDER updates the /event/provisioning/service_order/telco object with the provisioning response specified in the opcode input flist.

6. The event notification system calls the opcode specified in the /config/notify object. By default, PCM_OP_TCF_PROV_UPDATE_PROV_OBJECT is called.

7. PCM_OP_TCF_PROV_UPDATE_PROV_OBJECT updates the service's status and supplementary features.

About Creating Service Orders for Profile Changes

Profiles are added and removed from BRM service objects through the purchase and cancellation of charge offers and bundles. Services Framework provisioning includes profiles in service orders as directed by the provisioning configuration object /config/provisioning/telco. PCM_OP_TCF_CREATE_SVC_ORDER determines whether to create a service order based on data that has been added, changed, or removed from this object.

This opcode subscribes to the /event/notification/profile/pre-modify and /event/notification/profile/modify events generated by PCM_OP_CUST_MODIFY_PROFILE to create service orders for profile changes. Based on the value in the status field of the profile object, a service order is created and stored in the /event/provisioning/service_order/telco/service_name event by capturing changes made to the profile object.

GPRS Opcodes

Use GPRS opcodes to configure and provisiong GPRS services.

About Associating APNs and QoS with GPRS Services

In BRM, an APN is stored as a device (/device/apn). Because the APN is a network device and because a single APN can be used by multiple customers, you cannot map APN devices to GPRS services. Instead, the GPRS service references an APN and its appropriate quality of service (QoS) value based on the charge offer purchased by the customer.

BRM associates APN and QoS pairs with a GPRS service as follows:

1. A customer purchases, cancels, or modifies a bundle or charge offer that includes a GPRS service and provisioning tag.

2. The BRM system generates one of the following business events:

   • /event/billing/deal/purchase

   • /event/billing/production/action/modify

   • /event/billing/deal/cancel

   • /event/billing/product/action/cancel

   • /event/billing/product/action/purchase

3. The BRM event notification system detects the event and calls the opcode specified in the /config/notify object. The default configuration specifies to call PCM_OP_TCF_SVC_LISTENER.

4. PCM_OP_TCF_SVC_LISTENER checks the event's start and end date to determine whether the action is deferred for a future date.

   • If the event is not deferred, the opcode calls PCM_OP_TCF_APPLY_PARAMETER to update the GPRS service and ERA objects impacted by the charge offer provisioning update.

   • If the event is deferred, the opcode creates a /schedule object for executing PCM_OP_TCF_APPLY_PARAMETER at the scheduled time.

5. PCM_OP_TCF_APPLY_PARAMETER retrieves the service extension and service ERA information from the /config/telco/gprs object and passes the information to PCM_OP_TCF_POL_APPLY_PARAMETER.

6. When the service type is /service/telco/gprs, PCM_OP_TCF_POL_APPLY_PARAMETER calls PCM_OP_GPRS_APPLY_PARAMETER.

7. PCM_OP_GPRS_APPLY_PARAMETER writes the APN and QoS pairs to the flist's PIN_FLD_APN_ARRAY array.

8. PCM_OP_GPRS_APPLY_PARAMETER calls PCM_OP_GPRS_POL_APPLY_PARAMETER to update information about any custom /service/telco/gprs fields.

9. PCM_OP_TCF_APPLY_PARAMETER updates the service extensions and ERAs in the /service/telco/gprs object.

To customize how BRM associates APNs and QoS values with GPRS services, see "Associating APNs and QoS with GPRS Services".

Associating APNs and QoS with GPRS Services

See the following topics:

• Mapping Service Types to Service-Specific Opcodes

• Associating APN and QoS Pairs with GPRS Services

• Updating Custom GPRS Service Fields

Mapping Service Types to Service-Specific Opcodes

Use PCM_OP_TCF_POL_APPLY_PARAMETER to update information in the flist's PIN_FLD_SERVICES and PIN_FLD_PRODUCTS array and then pass the information to the appropriate service-specific opcode.

PCM_OP_TCF_POL_APPLY_PARAMETER takes as input the configuration object flist, the service flist, and the inherited information flist and then updates the service flist.

PCM_OP_TCF_POL_APPLY_PARAMETER is called by PCM_OP_TCF_APPLY_PARAMETER.

By default, PCM_OP_TCF_POL_APPLY_PARAMETER returns an empty inherited info flist.

If you added a substruct to a customized service, you can use PCM_OP_TCF_POL_APPLY_PARAMETER to fill in the substruct fields. These fields are updated in the database.

For example, a GSM service (/service/telco/gsm) could include a field for the bearer in the configuration object (/config/telco) in the service extensions array PIN_FLD_SERVICE_EXTENSIONS. You could use PCM_OP_TCF_POL_APPLY_PARAMETER to add the bearer information through the service extension to update the service flist.

Table 7-5 shows the opcode called for each supported service type:

Table 7-5 Supported Service Type Opcodes

Service Type	Opcode Called
/service/telco/gprs	PCM_OP_GPRS_APPLY_PARAMETER
/service/telco/gsm	PCM_OP_GSM_APPLY_PARAMETER

Associating APN and QoS Pairs with GPRS Services

Use PCM_OP_GPRS_APPLY_PARAMETER to associate APN and QoS pairs with a /service/telco/gprs service. This opcode is called by PCM_OP_TCF_POL_APPLY_PARAMETER when processing /service/telco/gprs services.

PCM_OP_GPRS_APPLY_PARAMETER reads the bearer service, APN name, and QoS information from the input flist's PIN_FLD_SERVICE_EXTENSIONS array and performs the following:

• If the Bearer service is passed in the input flist, the opcode adds the value to the output flist's PIN_FLD_BEARER_SERVICE field of the PIN_FLD_GPRS_INFO substruct.

• If the APN name and QoS are passed in the input flist, the opcode adds the values to the output flist's PIN_FLD_APN array in the PIN_FLD_INHERITED_INFO substruct.

The opcode then calls PCM_OP_GPRS_POL_APPLY_PARAMETER to perform any customizations. See "Updating Custom GPRS Service Fields".

Updating Custom GPRS Service Fields

Use PCM_OP_GPRS_POL_APPLY_PARAMETER to update custom fields in the /service/telco/gprs object. This opcode takes as input the configuration object flist, the service flist, and the inherited information flist from the calling PCM_OP_GPRS_APPLY_PARAMETER.

By default, PCM_OP_GPRS_POL_APPLY_PARAMETER returns the information passed in the input flist. This opcode can be customized to update the service flist by adding values to customized fields.

PCM_OP_GPRS_POL_APPLY_PARAMETER is called by PCM_OP_GPRS_APPLY_PARAMETER.

Updating Custom GSM Service Fields

Use PCM_OP_GSM_POL_APPLY_PARAMETER to update custom fields in the /service/telco/gsm object. PCM_OP_GSM_POL_APPLY_PARAMETER updates the service flist by adding values to customized fields for a service. This opcode takes as input the configuration object flist, the service flist, and the inherited information flist from the calling PCM_OP_GSM_APPLY_PARAMETER.

By default, PCM_OP_GSM_POL_APPLY_PARAMETER returns an empty inherited info flist.

If you added a substruct to a customized service, you can use PCM_OP_GSM_POL_APPLY_PARAMETER to fill in the substruct fields. These fields are updated in the database.

For example, a GSM service (/service/telco/gsm) could include a field for the bearer in the configuration object (/config/telco) in the service extensions array PIN_FLD_SERVICE_EXTENSIONS. You could use PCM_OP_GSM_POL_APPLY_PARAMETER to add the bearer information through the service extension to update the service flist.

PCM_OP_GSM_POL_APPLY_PARAMETER is called by PCM_OP_GSM_APPLY_PARAMETER. PCM_OP_GSM_APPLY_PARAMETER reads the service extensions from the input flist and adds corresponding GSM service values. The opcode reads the bearer service, APN name, and QoS information from the input flist's PIN_FLD_SERVICE_EXTENSIONS array and performs the following:

• If the Bearer service is passed in the input flist, the opcode adds the value to the output flist's PIN_FLD_BEARER_SERVICE field of the PIN_FLD_GSM_INFO substruct.

• If the APN name and QoS are passed in the input flist, the opcode adds the values to the output flist's PIN_FLD_APN array in the PIN_FLD_INHERITED_INFO substruct.