10 Balance Monitoring

This chapter describes Oracle Communications Billing and Revenue Management (BRM) Balance Monitoring Manager.

Before reading this document, you should be familiar with BRM system architecture, pipeline rating, and event notification. For information, see the following:

For information about using the balance monitoring interface in Customer Center, see the Customer Center Help.

About Balance Monitoring

You use balance monitoring to enable your customers to monitor the balance of a group of accounts in near real time. Balance monitoring collects the balance impacts for a specified group of accounts and services, and notifies customers when their balance is too high. Customers and CSRs can also access the group's total balance at any time by using a custom client interface.

For example, a family with multiple wireless telephony accounts can create a balance monitor that tracks the entire family's balance and that alerts them when the balance total exceeds $100.

Balance monitoring provides advantages to:

  • Service providers because it reduces the risk of debt exposure from nonpaying customers. Customers who track their balances are less likely to accrue excessive charges that they cannot pay.

  • Customers because they can monitor spending habits and are alerted when charges exceed their specified values. They can then reduce usage or inform members of the group that are generating excessive charges.

To create a balance monitor, customers define:

About Monitor Groups

Customers specify which account or service balances they want to track by creating a monitor group. Each monitor group includes the following:

Customers can create monitor groups manually or automatically:

  • With manual creation, customers specify each member to include in the monitor group.

  • With automated creation, customers only specify an owner and monitor type, and BRM automatically finds and adds members to the monitor group. Customer Center balance monitoring supports automated creation.

See "About Creating and Maintaining Balance Monitors".

About Monitor Group Owners

Monitor group owners have permission to view group balances, add or remove group members, and add or change threshold and credit limit values.

Monitor group owners can be accounts or services and can be anywhere in a hierarchy chain. For example, an owner could be a parent account in an account hierarchy or a paying or nonpaying child account.

About Monitor Group Members

Any of the following can be members of a monitor group:

  • Accounts. Members of a monitor group can include parent accounts, paying child accounts, and nonpaying child accounts. BRM monitors the balances for all services under a member account. For example, if a member account contains a GSM service and a GPRS service, BRM adds the current balance for both services to the group balance.

  • Services. Members of a monitor group can include services, such as the GSM service, for a group of accounts. When the member is a service, BRM monitors charges for that service only. For example, a company that pays all GSM services for its employees could create a monitor group that includes each employee's GSM service but excludes any other services owned by the employee accounts.

Accounts and services can belong to one or more monitor groups. BRM tracks the monitor groups to which an account or service belongs and then accesses this information during the rating process to determine where to apply balance impacts. For more information, see "About Synchronizing Monitor Data between Real-Time and Pipeline Batch Rating".

About Monitor Group Types

Monitor group types specify the type of members a monitor group contains. For example, group membership can be restricted to nonpaying child accounts and their services, or it can include both paying and nonpaying child accounts and their services.

Table 10-1 shows the monitor group types supported by BRM:

Table 10-1 Supported Monitor Types

Monitor Type Description

Hierarchy

Includes paying and nonpaying child accounts and their services.

Paying Responsibility

Includes nonpaying child accounts and their services.

Service Level

Includes a member service in a subscription group.

When a customer attempts to add a member to a monitor group, BRM validates the member against rules you specify for each monitor group type. The default implementation contains no validation rules for these monitor group types, but you can create custom group types or create your own rules by customizing the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode. For information, see "Validating the Members of a Balance Monitor Group".

Sample Monitor Groups

Figure 10-1 shows how you can create three different monitor groups in one account hierarchy. In this example, the corporation pays all account charges accumulated by its employees.

  • The company creates a monitor group to track the balances of its employees. In this case, the owner of the monitor group is the company and the members are all employee accounts.

  • Manager B creates a separate monitor group to track the balance for his department. In this case, the owner of the monitor group is manager B and the members include the accounts of manager B and all of his direct reports.

  • Employee 5 creates a monitor group to track his own account balance. In this case, the employee is both the owner and the sole member of the monitor group.

Figure 10-1 Monitoring Groups in a Hierarchy

Description of Figure 10-1 follows
Description of ''Figure 10-1 Monitoring Groups in a Hierarchy''

About the Balances of a Monitor Group

The balance for a monitor group is a running total that includes all balance impacts generated by its members. BRM updates the balance when a group member generates a usage event or when you create or modify a monitor group.

BRM stores the total balance for a particular monitor group in /balance_group/monitor objects in the database. For information, see "Creating /balance_group/monitor Objects".

Balance Impacts Included in a Monitored Balance

Monitored balance totals include the following:

  • All standard Accounts Receivable (A/R) impacts, such as these:

    • Discounts

    • Account-level adjustments and disputes

    • Payments

    • Refunds

    • Write-offs

    For more information, see "About Accounts Receivable".

  • Taxes. Monitored balance totals include taxes that are applied during the real-time rating process only. Any taxation that is deferred to the billing process is not included in the balance total.

  • Sponsored or charge sharing charges. Monitored balance totals include charges that apply to the sponsor's account only.

    See "About Monitoring Charge Sharing and Sponsored Account Balances".

About Monitoring Charge Sharing and Sponsored Account Balances

When an account belongs to a charge sharing or sponsor group, its balances may be paid by more than one account. For example, an employee may pay his own wireless usage fees but have his monthly subscription fees paid by his company. When this occurs, each balance monitor tracks only the charges for which it is responsible. In this example, the company's balance monitor tracks the subscription fee, and the employee's balance monitor tracks all usage charges.

For example, assume a company pays only for its employees' monthly subscription fees. If employees A, B, and C are each charged $10 in subscription fees but accrue $100 in usage fees, the company's balance monitor includes only $30 in subscription fees as shown in Figure 10-2.

Figure 10-2 Balance Monitor with Usage and Cycle Fee

Description of Figure 10-2 follows
Description of ''Figure 10-2 Balance Monitor with Usage and Cycle Fee''

When Balance Impacts Are Added to a Monitored Balance

BRM updates the balance of a monitor group at the following times:

  • When a balance monitor is created. When you first create a balance monitor and run the pin_monitor_balance utility, BRM automatically calculates the group balance. BRM retrieves the current balance of each member and adds it to the group balance.

    For more information, see "About Creating and Maintaining Balance Monitors".

  • When members are added to or removed from a monitor group. When a member is added to a monitor group, BRM automatically adds the member's current balance to the group balance when pin_monitor_balance is run. Likewise, when a member is removed from a monitor group and pin_monitor_balance is run, BRM automatically decreases the group balance.

    For more information, see "About Creating and Maintaining Balance Monitors".

  • As a result of pipeline rating. When rating events, the pipeline rating module calculates any monitor balance impacts immediately. However, the impacts are not added to the group balance until you load the data into the BRM database and run the balance monitor utility. Therefore, there is a small lag between the time an event occurs and the time it impacts the group balance.

    For more information, see "About Balance Monitoring and Pipeline Rating".

  • As a result of real-time rating. When rating events, BRM calculates any monitor balance impacts immediately. However, the impacts are not added to the group balance until you run the balance monitor utility. Therefore, there is a small lag between the time an event occurs and the time it impacts the group balance.

    For more information, see "About Balance Monitoring and Real-Time Rating".

Alerting Customers When Monitored Balances Cross Limits or Thresholds

To be alerted when the balance of their monitor group is approaching predefined values, customers must set up thresholds and credit limits. BRM then tracks the group balances and generates notification events when the balances cross above or below the threshold value or credit limit.

BRM checks whether a group balance has crossed a threshold or a credit limit whenever the following occur:

  • The balance of a monitor group is updated

  • Monitor group owners add or change limit and threshold values

For information about handling this in Customer Center, see the Customer Center Help.

About Setting Limits and Thresholds

To be alerted when a monitored balance reaches a certain value, customers must define the following for each balance monitor:

  • Credit floor. The credit floor specifies the starting point for a threshold value. The default credit floor is NULL. You must set the credit floor to a non-NULL value.

  • Credit limit. The credit limit specifies the ending point for a threshold value. BRM uses the credit limit to calculate the threshold value, which is a percentage of the credit limit. BRM generates a notification event when the group balance crosses above or below the credit limit.

    Note:

    Balance monitor credit limits are separate from account credit limits. Account credit limits specify the maximum balance for an individual account and affect the way BRM handles authorizations and rating. Monitor credit limits are used only to calculate threshold values and do not affect authorization and rating.

  • Thresholds. Thresholds specify the balance totals that trigger an alert to CSRs and monitor group owners. Owners specify thresholds in the following ways:

    • As a percentage of the credit limit in 5% increments (75%, 80%, 85%, and so on). To be notified when the credit limit is reached, select the 100% threshold setting.

    • As a fixed value, such as $90 or 50 minutes.

      Important:

      You must set a value for each of these parameters. BRM cannot send notification events when any of the following are true: the credit floor is NULL, the credit limit is infinite or undefined, or the threshold is undefined.

For example, a customer might set a monitor group's credit floor to $0, credit limit to $100, and thresholds to 70%, 90%, and 100%. This causes BRM to generate notification events whenever the monitored balance crosses above or below $70, $90, and $100.

You define a balance monitor's credit floor, credit limit, and threshold values when you create the balance monitor in Customer Center or your custom client application. BRM then stores the values in a /config/credit_profile object in the BRM database.

About Using Event Notification to Alert Customers

BRM uses event notification to alert monitor owners when balances cross a threshold or credit limit. When a monitored balance crosses a threshold or limit, the following occurs:

  1. BRM generates one of these notification events:

    • /event/notification/threshold— Indicates that the balance crossed above a threshold value or credit limit.

    • /event/notification/threshold_below— Indicates that the balance crossed below a threshold value or credit limit.

      For information about these events, see "Event Notification Definitions" in BRM Developer's Reference.

  2. BRM calls the opcode associated with the event in your system's event notification list. See "About the Event Notification List" in BRM Developer's Guide.

  3. The opcode processes the event data and passes information to your custom client application.

To enable this, you must configure the event notification feature, the opcode (if it is a policy opcode), and your custom client application to process these events and alert balance monitor owners. For more information, see "Configuring Event Notification for Balance Monitoring".

About Notification Events for Balance Monitoring

BRM generates notification events whenever a monitored balance crosses over or under a credit limit or threshold. This enables you to make BRM perform different actions depending on the event type. For example, you can customize BRM to send an email to both you and the group owner when the group balance crosses above a threshold, but to send an email only to the group owner when the balance falls below a threshold.

About the Number of Notification Events

BRM generates one notification event for each monitored balance that crosses a threshold or credit limit. When one event causes a balance to cross multiple thresholds, BRM generates only one event that lists all settings that were breached.

For example, member A belongs to balance monitors 1 and 2. When member A generates a usage event that crosses the 50% and 55% thresholds for monitor 1, and the 40% threshold for monitor 2, BRM generates only two events:

  • The first notification event specifies that the balance of monitor 1 surpassed both the 50% and 55% thresholds.

  • The second notification event specifies that the balance of monitor 2 surpassed the 40% threshold.

Information Included in Balance Monitor Notification Events

Each balance monitor notification event includes the following information:

  • Target balance monitor.

  • Resource ID.

  • Alert type: Credit limit or threshold breach.

  • Reason for the breach:

    • Upward breach. The monitored balance crossed above a threshold value.

    • Downward breach. The monitored balance crossed below a threshold value, for example, when the customer makes a payment.

    • Upward reset. The owner of the balance monitor increased a threshold value, causing the balance to cross below a threshold. For example, this occurs when the current balance is $50 and you change the value of threshold 1 from $40 to $60. In this case, the $50 balance crosses below the new setting for threshold 1.

    • Downward reset. The owner of the balance monitor decreased a threshold value, causing the balance to pass above a threshold. For example, this occurs when the current balance is $40 and you change the value of threshold 1 from $50 to $25. In this case, the $40 balance passes above the new setting for threshold 1.

  • Monitor type: Hierarchy credit exposure, paying responsibility credit exposure, or service level.

  • Source of the breach.

    Note:

    BRM does not provide a source ID when the alert is due to a threshold reset or group member addition.

  • List of thresholds or credit limits that were breached. For example, 50% and 70%. For credit limit breaches, this field is set to 100%.

For more information about these events, see "Updating Monitor Balances and Sending Credit Limit/Threshold Breach Notifications".

Providing Real-Time Access to the Balances of Monitor Groups

Balance monitor owners can access the balance for their monitor groups in real-time by using a Web interface, such as a Web-enabled phone or computer. When monitor owners log in, BRM collects their account information and optionally a date range and then retrieves the following for each balance monitor:

  • Beginning balance of the monitor group on the start date

  • Ending balance of the monitor group on the end date

To provide your customers and CSRs with access to real-time monitor balances, you must customize your client interface to use the BRM API. For information, see "Displaying Balance Monitor Information in Client Applications".

About Creating and Maintaining Balance Monitors

You create and modify balance monitors by using a third-party customer relationship management (CRM) application. To implement balance monitoring in your CRM application, you must configure it to accept the following information for each balance monitor and pass it to the BRM API:

  • Balance monitor name

  • Balance monitor owner

  • List of group members

  • The monitor group type: hierarchy, paying responsibility, or service level

  • Credit limit (optional)

  • Credit floor (optional)

  • Threshold settings (optional)

Balance Monitor Creation Process Overview

The process that BRM uses to create or modify a balance monitor depends on whether you implement balance monitoring in your system with or without Automated Monitor Setup (AMS).

  • With AMS, you can automate many of the balance monitor processes. AMS automatically adds and removes members from the balance monitor for you.

  • Without AMS, you add and remove members manually. You must use this method to create balance monitors for custom monitor types.

    Important:

    The Customer Center balance monitoring functionality requires AMS and does not support adding and removing members manually.

BRM creates balance monitors as follows:

  1. Takes as input all information about the balance monitor, such as the monitor owner and threshold settings.

  2. Creates a bucket to store the balance of the monitor group.

  3. Adds members to the balance monitor. BRM determines whether the following is true:

    • AMS is enabled.

    • The monitor type is hierarchy, paying responsibility, or service level.

    If both are true, BRM uses AMS to add members. BRM uses the monitor owner and monitor type to find all appropriate child accounts and services, and adds them to the monitor. See "About Using AMS to Manage Balance Monitors Automatically".

    If either one is false, BRM adds members without AMS. BRM takes as input the list of members and validates them against custom criteria. All members that pass validation are added to the balance monitor. See "Managing Balance Monitors without AMS".

  4. Retrieves the current balance of all members and adds it to the group balance.

About Using AMS to Manage Balance Monitors Automatically

You configure BRM to automatically add and remove members from balance monitors, based on the monitor group type, by using Automated Monitor Setup (AMS). AMS is a group of opcodes that automate many of the balance monitor processes, making balance monitoring easier to set up and use.

AMS creates and updates balance monitors by following the organizational hierarchy of accounts and services. This synchronizes the membership between a hierarchy and a monitor group.

Important:

AMS works only for the three default monitor group types: hierarchy, paying responsibility, and service level. For custom group types, you must create balance monitors without AMS. See "Managing Balance Monitors without AMS".

AMS automatically adds and removes members from balance monitors when the following occur:

  • A balance monitor is created. AMS takes as input the parent (owner) account or service and the monitor type, and then searches through the parent's lineage to find accounts and services that match the criteria for the monitor type. All subordinate accounts and services that meet the criteria are added as members.

    For example, when users create a paying responsibility-type monitor, AMS adds to the monitor the parent account and its services and all subordinate nonpaying child accounts and their services.

  • An account hierarchy or subscription group is changed. AMS automatically adds or removes members from any associated balance monitors, based on the monitor type. For example, when you add a nonpaying child account to a hierarchy, AMS automatically:

    • Finds all parent accounts at a higher level in the hierarchy than the specified child account.

    • Finds all hierarchy and paying responsibility balance monitors associated with each parent account.

    • Adds the child account and its services to each balance monitor.

When a balance monitor is created or a hierarchy or subscription group changes, the following occurs:

  1. BRM generates an AMS notification event.

  2. The BRM event notification feature calls one of the AMS opcodes.

  3. The AMS opcodes add or remove members from the appropriate monitor group and update the monitored balance.

Managing Balance Monitors without AMS

When creating or updating balance monitors without AMS, users are responsible for adding and removing members. BRM does not verify that balance monitors include all appropriate child accounts and services in a hierarchy or subscription group nor does it check whether a hierarchy or subscription group changes over time.

Users must add or remove members when the following occur:

  • A balance monitor is created. Users specify the individual accounts and services to add to the balance monitor.

  • An account hierarchy or subscription group is changed. Users must manually update any balance monitors associated with the hierarchy or subscription group. When an account is added to a hierarchy, users must manually add the account to all balance monitors associated with the group. Likewise, when an account is removed from a hierarchy, users must manually remove the account from any associated monitors.

To manage balance monitors without AMS, see "Using the Balance Monitor API to Create and Maintain Balance Monitors".

Balance Monitoring Process Overview

Figure 10-3 shows the balance monitoring process.

Figure 10-3 How BRM Processes Balance Monitoring Data

Description of Figure 10-3 follows
Description of ''Figure 10-3 How BRM Processes Balance Monitoring Data''

BRM processes balance monitoring data as follows:

  1. BRM rates events and collects any monitored balance impact data.

  2. BRM publishes monitored balance impacts to the monitor queue.

    See "Understanding the Monitor Queue".

  3. The pin_monitor_balance utility retrieves data from the monitor queue and calls the PCM_OP_BAL_APPLY_MONITOR_IMPACTS opcode to perform the following:

About Balance Monitoring and Real-Time Rating

Real-time rating processes monitored balances as follows:

  1. Rates the event and applies any discounts.

  2. Determines whether the event owner belongs to any monitor groups.

  3. Determines whether balance monitoring is enabled.

  4. Generates monitor balance impacts for each monitor group listed in the /ordered_balgrp object. The monitor balance impact includes the following data:

    • Event owner

    • Amount

    • Resource ID

    • Balance monitor (POID of the /balance_group/monitor object)

  5. Publishes the monitor balance impacts to the monitor queue.

    See "Understanding the Monitor Queue".

About Balance Monitoring and Pipeline Rating

Pipeline Manager processes monitored balances as follows:

  1. Pipeline modules rate the event and apply any discounts.

  2. The FCT_Account module determines whether the event owner belongs to any monitor groups and, if it does, enriches the MONITOR_LIST section of the EDR container with information about each monitor group.

    For information, see "FCT_Account" in BRM Configuring Pipeline Rating and Discounting.

    Note:

    DAT_AccountBatch stores in-memory the list of monitor groups to which an account or service belongs. The module retrieves this information from the BRM database when you first start Pipeline Manager and when you create, modify, or delete a monitor group. For more information, see "About Synchronizing Monitor Data between Real-Time and Pipeline Batch Rating".

  3. The FCT_BillingRecord module generates a monitor packet for each monitor group.

    • When a balance packet impacts the event balance group, FCT_BillingRecord creates a MONITOR_PACKET for each monitor group in the monitor list.

    • When a balance packet does not impact the event balance group (for example, the discount share or charge share event balance groups), FCT_BillingRecord calls DAT_AccountBatch to retrieve the monitor group list for the discount share or charge share owner's balance group.

    The MONITOR_PACKET contains an account POID of the balance monitor, the balance group ID from the monitor group, resource ID, amount, sub-balance impact, and the sub-balance block from the balance packet.

    For information, see "FCT_BillingRecord" in BRM Configuring Pipeline Rating and Discounting.

  4. The pipeline generates an output file that includes any monitor balance impacts.

  5. Rated Event (RE) Loader retrieves the pipeline output file and publishes any monitored balance impact data to the monitor queue.

    See "Understanding the Monitor Queue".

Understanding the Monitor Queue

The monitor queue (/monitor_queue) holds all monitor balance impacts generated by real-time rating and pipeline batch rating. The pin_monitor_balance utility retrieves this information and updates the balances of the associated monitor groups.

For performance reasons, the pin_monitor_balance utility does not delete /monitor_queue objects after they are retrieved from the BRM database. Instead, the utility flags the /monitor_queue objects as "processed" to prevent the objects from being consumed again.

BRM tracks the status of /monitor_queue objects by using the PIN_FLD_STATUS field:

  • When the field is set to 0, the object has not been processed by the pin_monitor_balance utility.

  • When the field is set to a nonzero value, the object has been processed by the utility.

Using pin_monitor_balance to Update Monitored Balances

You use the pin_monitor_balance utility to apply monitor balance impacts to a monitored balance. This utility is a multithreaded application (MTA) that retrieves a list of all /monitor_queue objects in the BRM database and then spawns child threads to process each object individually.

You can configure the utility to run with one thread or multiple threads:

  • One thread enables the utility to process events in the order that they occurred but decreases processing performance.

  • Multiple threads increase performance but may cause the utility to process events out of order. The default is 5 threads.

To configure the number of threads, see "Configuring pin_monitor_balance to Process Events in the Order Created".

You can run pin_monitor_balance manually or configure a scheduler, such as cron, to run it at predefined intervals. For more information, see "Running pin_monitor_balance to Update Monitored Balances".

The pin_monitor_balance utility performs the following tasks:

  1. Retrieves all unprocessed /monitor_queue objects from the BRM database (that is, all objects with the PIN_FLD_STATUS field set to 0).

  2. Retrieves the /event object associated with the /monitor_queue object to obtain the following:

    • Monitor balance impacts

    • Sub-balance impacts

    • Target balance monitors (/balance_group/monitor objects)

    • Event owner

  3. Calls the PCM_OP_BAL_APPLY_MONITOR_IMPACTS opcode, which performs the following:

    • Updates the monitored balance (/balance_group/monitor).

    • Determines whether any balance monitor thresholds have been breached by comparing the monitored balance to the threshold and credit limit values stored in the /config/credit_profile object. If any thresholds or limits were breached, the opcode generates a notification event. See "About Using Event Notification to Alert Customers".

    • Sets the /monitor_queue object's PIN_FLD_STATUS field to a nonzero value to prevent it from being processed again by the utility.

About Synchronizing Monitor Data between Real-Time and Pipeline Batch Rating

Pipeline batch rating and real-time rating determine where to apply balance monitor impacts by accessing each member's list of monitor groups. For real-time rating, this information is stored in each member's /ordered_balgrp object in the BRM database. For pipeline batch rating, this information is stored in memory by the DAT_AccountBatch module.

When you create, modify, or delete a balance monitor, BRM updates each member's /ordered_balgrp object and then uses Account Synchronization to send the updated information to Pipeline Manager, as follows:

  1. BRM updates the member's /ordered_balgrp object and generates one of the business events listed in Table 10-2:

    Table 10-2 Monitor-Related Actions

    Action Event

    Create a new monitor group

    /event/group/sharing/monitor/create

    Modify a monitor group by adding or removing members

    /event/group/sharing/monitor/modify

    Delete a monitor group

    /event/group/sharing/monitor/delete

    For more information on these storable objects, see BRM Storable Class Reference.

  2. Account Synchronization processes these business events and publishes them to the Account Synchronization queue.

    For more information, see "Installing and Configuring the Account Synchronization DM" in BRM Installation Guide.

  3. Pipeline Manager retrieves the data from the queue and updates its internal memory:

    • The DAT_Listener module retrieves the data from the queue and passes it to DAT_AccountBatch.

    • DAT_AccountBatch refreshes the monitor group list for all accounts.

    For more information, see "Pipeline Manager Reference" in BRM Configuring Pipeline Rating and Discounting.

Rerating Events When Members Are Added to Balance Monitors

The account synchronization process produces a small lag between the time a member's /ordered_balgrp object is updated in the BRM database and the time DAT_AccountBatch is updated. During this lag time, the following can occur:

  • Pipeline rating generates balance impacts for new balance monitor members, but does not generate monitor balance impacts.

  • Pipeline-rated events that have not been loaded into the database do not include monitor balance impacts for the new members.

This causes a discrepancy between the amount added to the member's account balance and the amount added to the balance monitor. To capture any missing monitor balance impacts, BRM automatically rerates events that were generated by the new balance monitor members.

When members are added to a balance monitor, the following occurs:

  1. Balance monitoring generates a notification event.

  2. Pipeline Manager suspends any incoming events that are generated by the new balance monitor members.

  3. Rated Event (RE) Loader loads all pipeline output files into the database.

  4. The pin_rerate utility rerates all events that were generated by the new balance monitor members. The utility does the following:

    1. Flushes all monitor balance impacts from the /monitor_queue.

    2. Backs out all events that were rated during the lag time.

    3. Rerates the events and generates monitor balance impacts.

    4. Applies monitor balance impacts to the appropriate balance monitor.

    For more information about pin_rerate, see "About Comprehensive Rerating Using pin_rerate" in BRM Setting Up Pricing and Rating.

  5. Pipeline Manager resumes processing EDRs generated by the new monitor members and recycles all EDRs suspended in step 2.

    Important:

    You must ensure that RE Loader has sufficient time to load all pipeline-rated events into the database before rerating begins. To do this, configure pin_rerate to wait a specified amount of time before starting the rerating process. See "Specifying a Wait Time before Rerating Events".

Configuring Your BRM System for Balance Monitoring

To configure your system for balance monitoring, perform the following tasks:

  1. Enable balance monitoring in BRM.

    See "Enabling Balance Monitoring in BRM".

  2. Enable AMS in BRM.

    See "Enabling AMS in BRM".

  3. Enable balance monitoring in Pipeline Manager.

    See "Enabling Balance Monitoring in Pipeline Manager".

  4. Configure BRM to perform appropriate follow-up operations when limits and thresholds are crossed.

    See "Configuring Event Notification for Balance Monitoring".

  5. Configure pin_rerate to wait a specified amount of time before starting the rerating process.

    See "Specifying a Wait Time before Rerating Events".

  6. (Optional) Configure pin_monitor_balance to process monitor balance impacts in the order that they were created.

    See "Configuring pin_monitor_balance to Process Events in the Order Created".

Enabling Balance Monitoring in BRM

By default, balance monitoring is disabled in BRM. You can enable this feature by modifying a field in the multi-bal instance of the /config/business_params object.

When balance monitoring is enabled, BRM monitors currency resources.

You modify the /config/business_params object by using the pin_bus_params utility (see "pin_bus_params" in BRM Developer's Guide).

To enable balance monitoring:

  1. Use the following command to create 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:

    <BalanceMonitoring>disabled</BalanceMonitoring>

  3. Change disabled to enabled.

    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 balance monitoring configuration.

  4. Save the file and change the file name from bus_params_multi_bal.xml.out to bus_params_multi_bal.xml.

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

    pin_bus_params bus_params_multi_bal.xml

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

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

    For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects by Using Object Browser" in BRM Developer's Guide.

  7. Stop and restart the Connection Manager (CM).

    For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter.

    For more information, see "pin_multidb" in BRM System Administrator's Guide.

Enabling AMS in BRM

By default, AMS is disabled in BRM. You can enable this feature to automate many of the balance monitoring processes by modifying a field in the subscription instance of the /config/business_params object.

You modify the /config/business_params object by using the pin_bus_params utility (see "pin_bus_params" in BRM Developer's Guide).

To enable AMS:

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

    pin_bus_params -r BusParamsSubscription bus_params_subscription.xml

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

  2. Search the XML file for following line:

    <AutomatedMonitorSetup>disabled</AutomatedMonitorSetup>

  3. Change disabled to enabled.

    Caution:

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

  4. Save the file and change the file name from bus_params_subscription.xml.out to bus_params_subscription.xml.

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

    pin_bus_params bus_params_subscription.xml

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

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

    For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects by Using Object Browser" in BRM Developer's Guide.

  7. Stop and restart the Connection Manager (CM).

    For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter.

    For more information, see "pin_multidb" in BRM System Administrator's Guide.

Enabling Balance Monitoring in Pipeline Manager

Pipeline Manager determines whether balance monitoring is enabled by using the BalanceMonitoring entry from the multi-bal instance of the /config/business_params object. See "Enabling Balance Monitoring in BRM".

You must configure Pipeline Manager to use business parameter settings from the BRM database by performing the following:

  • Configuring the DAT_PortalConfig module in your registry file (see "DAT_PortalConfig" in BRM Configuring Pipeline Rating and Discounting). This module must be listed before all other data modules in the registry file.

  • Connecting the DAT_AccountBatch module to DAT_PortalConfig by using the PortalConfigDataModule registry entry (see "DAT_AccountBatch" in BRM Configuring Pipeline Rating and Discounting).

For more information, see "Using Business Parameter Settings from the BRM Database" in BRM System Administrator's Guide.

Important:

You must enable balance monitoring in Pipeline Manager to have notification events generated during the batch rating process.

Configuring Event Notification for Balance Monitoring

When the balance of a monitor group crosses a threshold or a credit limit, BRM generates the following notification events. You must configure the BRM event notification feature to call opcodes that perform the appropriate follow-up operations when these events are generated.

  • /event/notification/threshold: This event indicates that the group's balance reached or exceeded a threshold value; for example, when a purchase causes the balance to go over a 70% threshold.

    By default, when this event occurs, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode is called. You can add custom code to this policy opcode that processes upward threshold breaches, or you can enable this event to trigger a call to a balance monitoring opcode that processes upward threshold breaches (see "Editing the Event Notification List" in BRM Developer's Guide).

  • /event/notification/threshold_below: This event indicates that the group's balance passed below a threshold value; for example, when the customer pays a bill. This event is generated only when the group's balance is less than the threshold value.

    By default, when this event occurs, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode is called. To enable this event to trigger a call to a balance monitoring opcode that processes downward threshold breaches, see "Editing the Event Notification List" in BRM Developer's Guide.

For more information about these events, see "About Notification Events for Balance Monitoring".

To configure the event notification feature for balance monitoring:

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

    See "Merging Event Notification Lists" in BRM Developer's Guide.

  2. Add information to your final event notification list about the appropriate opcodes to call when the /event/notification/threshold and /event/notification/threshold_below events occur.

    See "Editing the Event Notification List" in BRM Developer's Guide.

    Note:

    • The default BRM_Home/sys/data/config/pin_notify file includes the following line, which means that the PCM_OP_ACT_POL_EVENT_NOTIFY (opcode number 301) policy opcode is called whenever an /event/notification/threshold event occurs: 301    0    /event/notification/threshold

    • The number of each balance monitoring opcode is in the balance monitor opcode header file, BRM_Home/include/ops/monitor.h.

  3. If you enabled AMS, ensure that the file includes the following information from the BRM_Home/sys/data/config/pin_notify file:

    # Automated Monitor Setup related event notification
# Uncomment these lines when AMS feature is enabled
7853    0       /event/group/sharing/monitor/create
7854    0       /event/notification/service/pre_purchase
7855    0       /event/notification/service/pre_purchase
7856    0       /event/notification/service/pre_purchase
7857    0       /event/customer/billinfo/modify
7855    0       /event/customer/billinfo/modify
7857    0       /event/group/member
7854    0       /event/group/member
7857    0       /event/notification/bal_grp/modify
7855    0       /event/notification/bal_grp/modify
7854    0       /event/audit/subscription/transfer
3787    0       /event/billing/monitor/update

    Important:

    If the lines associating opcode numbers with events are commented out, uncomment them.

  4. (Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list.

    See "Editing the Event Notification List" in BRM Developer's Guide.

  5. (Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger.

    See "Triggering Custom Operations" in BRM Developer's Guide.

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

    See "Loading the Event Notification List" in BRM Developer's Guide.

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

Specifying a Wait Time before Rerating Events

You must configure pin_rerate to wait a specified amount of time before rerating events. For more information, see "Rerating Events When Members Are Added to Balance Monitors".

To configure a wait time:

  1. Open the pin_rerate configuration file (BRM_Home/apps/pin_rerate/pin.conf) in a text editor.

  2. Add the following entry and specify the delay time in seconds. Make sure to allow enough time for RE Loader to load all of the pipeline-rated data into the database.

    Note:

    The default is 0.
    - pin_rerate        delay        300

  3. Save and close the file.

Configuring pin_monitor_balance to Process Events in the Order Created

To process monitor balance impacts in chronological order, configure the pin_monitor_balance utility to run with only one thread. For more information, see "Using pin_monitor_balance to Update Monitored Balances".

To process monitor balance impacts in chronological order, perform the following tasks:

  1. Open the pin_monitor_balance configuration file (BRM_Home/apps/pin_monitor/pin.conf) in a text editor.

  2. Change the following entry to 1.

    - pin_mta   children   1

  3. Save and close the file.

Running pin_monitor_balance to Update Monitored Balances

To update monitored balances, perform the following:

  1. Go to the BRM_Home/apps/pin_monitor directory.

  2. Run the pin_monitor_balance utility:

    Note:

    To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
    pin_monitor_balance [-d] [-v]

    For more information, see pin_monitor_balance.

Specifying Whether Item Transfers Affect Balance Monitors

BRM updates balance monitor totals when you perform item adjustments, settlements, and disputes. By default, BRM also updates balance monitor totals when you perform item transfers. This can cause BRM to apply double the dispute, adjustment, or settlement amount to a balance monitor total when correcting misapplied charges. For example, when a customer disputes a misapplied charge, BRM reduces the balance monitor total when the charge is disputed and then again when the charge is transferred from the customer's account to another account.

You can configure BRM to not apply balance impacts from item transfers to balance monitor totals by passing the optional PIN_FLD_APPLY_MONITOR input flist field to the PCM_OP_BILL_ITEM_TRANSFER opcode:

  • When PIN_FLD_APPLY_MONITOR is set to 0, balance impacts from item transfers are not added to balance monitor totals.

  • When PIN_FLD_APPLY_MONITOR is set to 1 or not passed, balance impacts from item transfers are added to balance monitor totals. This is the default.

For more information about adjustments, disputes, and settlements, see "Configuring Adjustments, Disputes, and Settlements".

Implementing Balance Monitoring in Custom Client Applications

Before reading the following, you should be familiar with these concepts in BRM:

For information about the balance monitoring interface in Customer Center, see the Customer Center Help.

About Implementing Balance Monitoring in Client Applications

To monitor balances, your Customer Service Representative (CSR) must be able to perform the following tasks:

  • Specify the group of account and service balances to monitor.

  • Update the group by adding or deleting members.

  • View the balance monitors owned by an account.

  • View the current balance of a balance monitor.

  • Receive alerts when a balance monitor's credit limit or threshold is crossed.

    Note:

    For information about the balance monitoring interface in Customer Center, see the Customer Center Help.

To implement balance monitoring in your client application, add the following functionality to your application by using the BRM opcodes:

Your user interface must be designed to collect the information needed for creating or updating the relevant objects and pass the appropriate fields in the input flist to the opcodes.

Creating and Maintaining Balance Monitor Objects

To create or update a balance monitor, you must store the following balance monitor data in the BRM database:

  1. The total rolled-up balance in a /balance_group/monitor object.

    You create only one such object for each balance monitor.

  2. The list of monitor members in a /group/sharing/monitor object.

    You create only one such object for each balance monitor.

  3. The list of monitor groups that each member belongs to in /ordered_balgrp objects.

    You must create or update one such object for each account and service in a balance monitor.

The method you use to create and update these objects depends on whether you are using Automated Monitor Setup (AMS), which is a group of opcodes that automate how BRM creates and maintains balance monitors.

Using AMS to Create and Maintain Balance Monitors Automatically

For more information about AMS, see "About Using AMS to Manage Balance Monitors Automatically".

For information about using the balance monitor interface in Customer Center, see the Customer Center Help.

To use AMS to create and update balance monitors automatically, you must configure your custom client application to call the following opcodes:

  1. PCM_OP_CUST_SET_BAL_GRP: This opcode creates and updates the /balance_group/monitor object.

  2. PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE: This opcode creates the /group/sharing/monitor object.

    You must pass the monitor group type in the input flist. To create and maintain these objects, see "Creating, Modifying, or Deleting /group/sharing/monitor Objects".

When a /group/sharing/monitor object is created or modified, BRM uses the event notification feature to trigger calls to the appropriate AMS opcodes. These opcodes automatically add and remove members from /group/sharing/monitor objects and update each member's /ordered_balgrp object based on the monitor type. See "Adding and Removing Balance Monitor Members Automatically".

Important:

For subscription groups only, create a separate /ordered_balgrp object for any member service that uses a separate /billinfo object than its parent subscription service. You create /ordered_balgrp objects manually by using the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode. See "Adding a Monitor Group to a Member's /ordered_balgrp Object".

Using the Balance Monitor API to Create and Maintain Balance Monitors

For more information, see "Managing Balance Monitors without AMS".

To create or update balance monitors without AMS, you must configure your custom client application to call the following opcodes:

  1. PCM_OP_CUST_SET_BAL_GRP: This opcode creates and updates the /balance_group/monitor object.

  2. PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE: This opcode creates the /group/sharing/monitor object.

    You must pass all group members in the input flist.

  3. PCM_OP_SUBSCRIPTION_ORDERED_BALGRP: This opcode creates and updates /ordered_balgrp objects.

    You must create or update the /ordered_balgrp object associated with each account and service that you want to include in a balance monitor. See "Adding a Monitor Group to a Member's /ordered_balgrp Object".

    For example, assume a balance monitor includes the following account hierarchy shown in Figure 10-4:

Figure 10-4 Example Account Hierarchy with Balance Monitoring

Description of Figure 10-4 follows
Description of ''Figure 10-4 Example Account Hierarchy with Balance Monitoring''

To include in the balance monitor the balance of all three accounts and their services, create or update the /ordered_balgrp object associated with each of the following:

  • /account 1234

  • /service/ip/cable 1234

  • /account 1111

  • /service/ip/cable 1111

  • /service/ip/gprs 1111

  • /account 2222

  • /service/ip 2222

Creating /balance_group/monitor Objects

To create a /balance_group/monitor object, call the PCM_OP_CUST_SET_BAL_GRP opcode with the following information in the input flist:

  • The owner of the balance monitor:

    • When the owner is an account, the POID of the /account object

    • When the owner is a service, the POIDs of the /account and /service objects

  • Monitor name

  • Credit limit

  • Credit floor

  • Credit thresholds

    Note:

    You can also pass this information in the PIN_FLD_ACCTINFO array of the input flist to PCM_OP_CUST_COMMIT_CUSTOMER when creating an account. This opcode automatically calls PCM_OP_CUST_SET_BAL_GRP to create a /balance_group/monitor object when the relevant information is in the input flist and balance monitoring is enabled. For more information, see "Creating Balance Groups".

Modifying /balance_group/monitor Objects

To modify an existing /balance_group/monitor object, call the PCM_OP_CUST_SET_BAL_GRP opcode with the following information in the input flist:

  • The owner of the balance monitor:

    • When the owner is an account, the POID of the /account object

    • When the owner is a service, the POIDs of the /account and /service objects

  • The balance monitor to modify (POID of the /balance_group/monitor object)

  • Monitor name

  • Credit limit

  • Credit floor

  • Credit thresholds

    Note:

    You can also pass this information in the PIN_FLD_ACCTINFO array of the input flist to PCM_OP_CUST_UPDATE_CUSTOMER when modifying an account. This opcode automatically calls PCM_OP_CUST_SET_BAL_GRP to modify the /balance_group/monitor object when the relevant information is in the input flist and balance monitoring is enabled. For more information, see "Managing Balance Groups with Your Custom Application".

Deleting /balance_group/monitor Objects

You cannot delete /balance_group/monitor objects. You can, however, deactivate the monitor group by deleting its associated /group/sharing/monitor object. To do so:

  1. Run the pin_monitor_balance utility to update balances.

  2. Delete the associated group/sharing/monitor object by calling the PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE opcode.

    This opcode removes the reference to the group/sharing/monitor object from corresponding /ordered_balgrp object. See "Creating, Modifying, or Deleting /group/sharing/monitor Objects".

Creating, Modifying, or Deleting /group/sharing/monitor Objects

To create or modify a /group/sharing/monitor object, you must collect the following information in your client application and pass it to the opcodes:

  • Owner of the balance monitor:

    • When the owner is an account, the POID of the /account object

    • When the owner is a service, the POIDs of the /account and /service objects

  • Monitor group type: hierarchy, paying responsibility, or service level

  • List of members you want to add or delete

  • Balance monitor associated with the monitor group

You call the following opcodes from your client application:

  • To create a monitor group, call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE opcode.

  • To modify a monitor group, call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY opcode.

  • To delete a monitor group, call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE opcode.

These opcodes perform the following tasks to add, modify, or delete a monitor group object:

  1. Verify balance monitoring is enabled.

  2. (Create and modify opcodes only) Call the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode to validate the members.

    See "Validating the Members of a Balance Monitor Group".

  3. Create, modify, or delete the /group/sharing/monitor object.

Changing the Owner of a Balance Monitor

To change the owner of a /group/sharing/monitor object, call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT opcode. For information on the fields you must include in the input flist, see "Changing the Owner of a Resource Sharing Group".

Important:

This opcode can be used to change the owner of a balance monitor only if you are performing the change manually. Automated Monitor Setup (AMS) does not support changing owners.

If successful, this opcode returns the POID of the balance monitor that was modified and the event that was generated to record the owner change.

This opcode fails if the new owner that is passed is already a member of the resource sharing group.

To change the owner of a balance monitor, PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT does the following:

  1. Verifies that:

    • AMS is not enabled. See "Enabling AMS in BRM".

    • The input flist contains the /balance_group object and /account object for the new balance monitor owner.

    • The /balance_group object belongs to the new owning account or service.

  2. Sets the /group/sharing/monitor object's owner to the new owner specified in the PIN_FLD_PARENT input field.

  3. Creates an /event/group/sharing/monitor/modify event to record the owner change.

Validating the Members of a Balance Monitor Group

To validate the members of a balance monitor, call the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode. This opcode validates members before they are added or modified based on the monitor type, and returns a list of valid members to the calling opcode.

By default, this opcode validates the hierarchy, paying responsibility, and service level monitor types. You can create any type of monitor and validate it by implementing validation rules in this opcode.

The default implementation of the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS opcode performs the following tasks:

  1. Retrieves the monitor type.

  2. For each member in the input flist, retrieves the account object.

  3. Applies validation rules for the monitor type and returns a list of valid members for the group.

Adding a Monitor Group to a Member's /ordered_balgrp Object

The /ordered_balgrp object stores the list of sharing groups to which an account or service belongs. This object controls the order in which credits and discounts are applied and tracks the balance impacts for the balance groups.

For more information on sharing groups, see the Customer Center Help.

Monitor groups are added to the PIN_FLD_ORDERED_BALGROUPS array of the /ordered_balgrp object. Unlike the charge sharing and discount sharing groups, the order of the monitor groups does not affect the balances. Therefore, the monitor groups are added to the end of the list.

To add a monitor group to the /ordered_balgrp object of an account or service, call the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode. This opcode performs the following tasks, depending on the value passed in the PIN_FLD_ACTION field in the input flist:

  • Creates or deletes an /ordered_balgrp object.

  • Modifies an /ordered_balgrp object by adding or deleting groups.

  • Lists all sharing groups to which the account or service belongs.

This opcode performs the following tasks:

  1. Verifies that the input flist has a /group/sharing/monitor object in the PIN_FLD_ORDERED_BALGROUPS array and that balance monitoring is enabled.

    Note:

    • When the input flist does not contain a /group/sharing/monitor object, the opcode continues with the tasks for processing the /group/sharing/charges and /group/sharing/discounts objects

    • When balance monitoring is not enabled, the opcode returns an error.

  2. Rearranges the PIN_FLD_ORDERED_BALGROUPS array to place the monitor groups at the end of the sequence.

  3. Does one of the following tasks:

    • When the opcode is called to create the object, creates the /ordered_balgrp object for the specified account or service.

    • When the opcode is called to modify the object, modifies the /ordered_balgrp object by adding or deleting monitor group objects.

    • When the opcode is called to delete the object, deletes the /ordered_balgrp object.

  4. Retrieves the current balance for the account or service /balance_group.

  5. Generates an /event/billing/monitor/update or /event/billing/monitor/delete event.

  6. Updates the balance of all associated /balance_group/monitor objects.

For more information about PCM_OP_SUBSCRIPTION_ORDERED_BALGRP, see "Managing Ordered Balance Groups".

Adding and Removing Balance Monitor Members Automatically

Use these AMS opcodes to manage balance monitors automatically.

Important:

Do not call these opcodes directly. Call these opcodes only through the BRM event notification feature. See "Configuring Event Notification for Balance Monitoring".

Adding Members to Newly Created Balance Monitors Automatically

Use the PCM_OP_MONITOR_SETUP_MEMBERS opcode to automatically add members to a balance monitor when it is first created. This opcode is a wrapper opcode that, according to monitor group type, calls other standard MONITOR opcodes to:

  • Find and add members to the monitor group (/group/sharing/monitor object).

  • Update each member's ordered balance group list (/ordered_balgrp object).

  • Add each member's current balance to the group balance (/balance_group/monitor object).

This opcode is triggered by the /event/group/sharing/monitor/create event.

Important:

Do not call this opcode directly. This opcode should be called through the event notification feature only. See "Configuring Event Notification for Balance Monitoring".

This opcode retrieves the monitor type and monitor owner, and then calls one of these opcodes:

  • For hierarchy group types (H_CE): Calls PCM_OP_MONITOR_PROCESS_HIERARCHY_MONITORS. This opcode adds the following members to the balance monitor:

    • The parent account and its services

    • All nonpaying child accounts and their services

    • All paying child accounts and their services

  • For paying responsibility group types (PR_CE): Calls PCM_OP_MONITOR_PROCESS_BILLING_MONITORS. This opcode adds the following members to the balance monitor:

    • The parent account and its services

    • All nonpaying child accounts and their services

  • For service group types (SUB_CE): Calls PCM_OP_MONITOR_PROCESS_SERVICE_MONITORS. This opcode adds the following members to the balance monitor:

    • The parent subscription service

    • All member services

For more information about these opcodes, see "Balance Monitoring FM Standard Opcodes" in BRM Developer's Reference.

Adding Members to Hierarchy-Type Monitors

Use the PCM_OP_MONITOR_PROCESS_HIERARCHY_MONITORS opcode to add members to hierarchy-type balance monitors (see BRM Developer's Reference). This opcode finds and adds the following members to the balance monitor:

  • The parent account and its subscriptions

  • All paying child accounts and their subscriptions

  • All nonpaying child accounts and their subscriptions

This opcode is called directly by the PCM_OP_MONITOR_SETUP_MEMBERS wrapper opcode.

PCM_OP_MONITOR_PROCESS_HIERARCHY_MONITORS performs the following tasks:

  1. Finds all services that are associated with the parent account.

  2. Finds in the hierarchy all paying and nonpaying child accounts that belong to the parent account.

  3. Finds all services that are associated with each child account.

  4. Adds the following members to the balance monitor:

    • The parent account and its services.

    • All child accounts and their services.

    See "Creating, Modifying, or Deleting /group/sharing/monitor Objects".

  5. Updates each account's and service's /ordered_balgrp object.

    See "Adding a Monitor Group to a Member's /ordered_balgrp Object".

Adding Members to Payment Responsibility-Type Monitors

Use the PCM_OP_MONITOR_PROCESS_BILLING_MONITORS opcode to add members to payment responsibility-type balance monitors. This opcode finds and adds the following members to the balance monitor:

  • The parent account and its subscriptions

  • All nonpaying child accounts and their subscriptions

This opcode is called directly by the PCM_OP_MONITOR_SETUP_MEMBERS wrapper opcode.

PCM_OP_MONITOR_PROCESS_BILLING_MONITORS performs the following tasks:

  1. Retrieves the parent's bill unit (billinfo) from either the input flist or searches....

  2. Searches for all the bill_info objects that have PIN_FLD_PARENT_BILLINFO_OBJ as the current billinfo.

  3. Searches for the owning account and all services for each billinfo found.

  4. Adds the following members to the balance monitor:

    • The parent account and its services

    • All nonpaying child accounts and their services.

    See "Creating, Modifying, or Deleting /group/sharing/monitor Objects".

  5. Updates each account's and service's /ordered_balgrp object.

    See "Adding a Monitor Group to a Member's /ordered_balgrp Object".

Updating Hierarchy-Type Monitors Automatically

Use the PCM_OP_MONITOR_ACCOUNT_HIERARCHY opcode to add members to hierarchy-type balance monitors when an account hierarchy changes (see BRM Developer's Reference). For example, this opcode adds members to balance monitors when any of the following actions affect an account hierarchy:

  • An account is added to the account hierarchy

  • A child account adds a service

  • The association between a balance group and a bill unit changes

  • A line is transferred to an account member

This opcode is triggered by the following events:

  • /event/group/member

  • /event/notification/service/pre_purchase

  • /event/audit/subscription/transfer

    Important:

    Do not call this opcode directly. This opcode should be called through the event notification feature only. See "Configuring Event Notification for Balance Monitoring".

PCM_OP_MONITOR_ACCOUNT_HIERARCHY finds all parent accounts at a higher level in the hierarchy than the specified account or service. For each parent account, the opcode performs the following tasks:

  1. Finds all hierarchy-type monitors associated with the parent account.

  2. Adds the account or service to the hierarchy-type monitor groups (/group/sharing/monitor objects).

  3. Adds the monitor group to the account's or service's ordered balance group list (/ordered_balgrp object).

  4. Adds the account or service balance to the monitored balance (/balance_group/monitor objects).

Updating Paying Responsibility-Type Monitors Automatically

Use the PCM_OP_MONITOR_BILLING_HIERARCHY opcode to add members to paying responsibility-type monitors when changes occur in an account hierarchy. For example, this opcode adds members to balance monitors when any of the following actions affect an account hierarchy:

  • A nonpaying child account is added to the account hierarchy

  • A nonpaying child account adds a service

  • A child account changes from a paying to a nonpaying payment type

  • The association between a balance group and a bill unit changes

  • A line is transferred to a nonpaying child account

This opcode is triggered by the following events:

  • /event/notification/service/pre_purchase

  • /event/customer/billinfo/modify

  • /event/notification/bal_grp/modify

    Important:

    Do not call this opcode directly. This opcode should be called through the event notification feature only. See "Configuring Event Notification for Balance Monitoring".

PCM_OP_MONITOR_BILLING_HIERARCHY finds all parent accounts at a higher level in the hierarchy than the specified account or service. For each parent account, the opcode performs the following tasks:

  1. Finds all paying responsibility-type monitors associated with the parent account.

  2. Adds the account or service to the paying responsibility-type monitor groups (/group/sharing/monitor objects).

  3. Adds the monitor group to the account's or service's ordered balance group list (/ordered_balgrp object).

  4. Adds the account or service balance to the balance monitors (/balance_group/monitor objects).

Updating Subscription-Type Monitors Automatically

Use the PCM_OP_MONITOR_SERVICE_HIERARCHY opcode to add members to subscription-type monitors when a subscription group changes. For example, when you add a member service to a subscription, this opcode adds the service to any associated balance monitors.

This opcode is triggered by the /event/notification/service/pre_purchase notification event.

Important:

Do not call this opcode directly. This opcode should be called through the event notification feature only. See "Configuring Event Notification for Balance Monitoring".

PCM_OP_MONITOR_SERVICE_HIERARCHY finds all parent subscription services at a higher level in the group than the specified service. For each parent subscription service, the opcode performs the following tasks:

  1. Finds all subscription-type monitors associated with the parent subscription service.

  2. Adds the service to the subscription-type monitor groups (/group/sharing/monitor objects).

  3. Determines whether the added service is a subscription service:

    • If it is, proceeds to the next step.

    • If it is not, adds the monitor groups to the service's /ordered_balgrp object.

  4. Adds the service balance to the balance monitors (/balance_group/monitor objects).

Removing Members from Hierarchy- and Paying Responsibility-Type Monitors

Use the PCM_OP_MONITOR_HIERARCHY_CLEANUP opcode to remove members from hierarchy-type or paying responsibility-type monitors when an account hierarchy changes. For example, this opcode is called when any of the following actions affect an account hierarchy:

  • An account is removed from the hierarchy

  • A child account changes from a nonpaying to a paying payment type

  • The association between a balance group and a bill unit changes

  • A line is removed from a child account

This opcode is triggered by the following events:

Displaying Balance Monitor Information in Client Applications

You can retrieve and display the following information in your client application:

  • The balances for a monitor group

  • A list of monitor groups owned by an account or service

Retrieving the Balances for a Monitor Group

To retrieve the total rolled-up balance for a monitor group, call the PCM_OP_BAL_GET_MONITOR_BAL opcode. The opcode retrieves either the balance monitor's current balance or the balance total for a specified time period.

The opcode returns one of the following, depending on whether you pass the PIN_FLD_DATE_BALANCES array in the input flist:

  • If you pass the array with a start and end date, the opcode returns the total amount generated by members between those days.

    Note:

    The end date is exclusive. For example, if you enter January 1 as the start date and January 5 as the end date, the opcode sums all balance impacts generated on January 1, 2, 3, and 4.

  • If you do not pass the array, the opcode returns the balance monitor's current rolled-up balance.

This opcode performs the following tasks to retrieve the balances:

  1. Retrieves the POID of the /balance_group/monitor object and, optionally, the dates for which the balances are requested.

  2. Reads the /balance_group/monitor object and retrieves the balance information.

  3. When the input flist contains dates, retrieves the correct bucket for the specified dates from the sub-balances.

  4. Returns the balance for the specified monitor group.

Retrieving the Balance Monitors Owned by an Account or Service

To retrieve a list of balance monitors owned by an account or service, call the PCM_OP_BAL_GET_ACCT_MONITORS opcode.

This opcode takes as input the POID of the /account or /service object and performs the following tasks:

  1. Searches for all the /group/sharing/monitor objects associated with the account or service specified in the input flist.

  2. For each /group/sharing/monitor object associated with the account or service, retrieves the /balance_group/monitor objects.

  3. Returns a list of monitor groups owned by the specified account or service.

Updating Monitor Balances and Sending Credit Limit/Threshold Breach Notifications

When a credit limit or threshold is reached, BRM generates a notification event containing information about the affected account and the reason for the breach. (See "About Using Event Notification to Alert Customers".)

When you run the pin_monitor_balance utility to update monitored balances with the current monitor impacts, it calls the PCM_OP_BAL_APPLY_MONITOR_IMPACTS opcode. This opcode updates the /balance_group/monitor objects and also compares the monitored balance with the credit limit and threshold values stored in the /config/credit_profile object. It generates notification events when the credit limits or thresholds are crossed.

For more information on the pin_monitor_balance utility, see "Running pin_monitor_balance to Update Monitored Balances" and "pin_monitor_balance".

The PCM_OP_BAL_APPLY_MONITOR_IMPACTS opcode generates two kinds of notification events:

  • /event/notification/threshold when the balance crosses above the credit threshold

  • /event/notification/threshold_below when the balance falls below the credit threshold

    Important:

    These are notification events only and are not recorded in the database. See "About Notification Events" in BRM Developer's Guide.

Table 10-3 lists the fields in the notification events.

Table 10-3 Notification Event Fields for Monitoring

Field Name Description

PIN_FLD_RESOURCE_ID

The resource ID.

PIN_FLD_AMOUNT

The balance impact for this event.

PIN_FLD_BAL_GRP_OBJ

The POID of the /balance_group/monitor object.

PIN_FLD_PERCENT

The percentage amount crossed.

PIN_FLD_SOURCE_OBJ

Source of the breach, for example, the POID of the event that caused the breach.

PIN_FLD_ALERT_TYPE

The alert type: credit limit or threshold percentage.

PIN_FLD_MONITOR_TYPE

Type of monitor:

  • Paying responsibility credit exposure

  • Hierarchy credit exposure

  • Service level

  • A type that you have defined.

PIN_FLD_REASON

The reason for the breach:

  • Upward breach

  • Downward breach

  • Upward reset

  • Downward reset

  • Unknown reason

PIN_FLD_THRESHOLD

Tracks when the balance of a monitor group crosses a 5% boundary. For example, it tracks whether the current balance is 5%, 10%, or 15% of the credit limit.

PIN_FLD_CREDIT_THRESHOLDS

An array of credit thresholds and limits breached by this event.

Important:

The opcode generates only one event if multiple thresholds are crossed. However, if multiple monitors cross the thresholds because of a single balance impact, the utility generates an event for each monitor.

You can use the information in the events to notify the CSR through a client application or the customer through email, for example, by writing a custom application.

For more information about using event notification, see the following topics:

Example of Credit Threshold Notification Event Generation

Consider a balance monitor for an account or service with:

  • A credit floor of $0

  • A credit limit of $100

  • Thresholds set at 25%, 75%, and 90%

  • A current balance of $50

When a new event comes in with a balance of $26, the new balance is set to $76, and a notification event with the following information is generated:

PIN_FLD_ALERT_TYPE   Threshold
PIN_FLD_REASON   Upward breach
PIN_FLD_CREDIT_THRESHOLDS   75%