23 Managing Balance Monitoring Groups

Learn how to use balance monitoring to enable your customers to monitor the balance of a group of accounts in near real time in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

• About Balance Monitoring

• About Balance Monitoring Groups

• About the Balances of a Monitor Group

• Alerting Customers When Monitored Balances Cross Limits or Thresholds

• Providing Your Customers with Access to Monitor Balances

• About Creating and Maintaining Balance Monitors

• About Processing Balance Impacts

• Configuring Your BRM System for Balance Monitoring

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:

• All account and service balances they want to include in their balance monitor. This group of accounts and services forms a monitor group.

  See "About Balance Monitoring Groups".

• When to be alerted that the balance total is too high or approaching the maximum.

  See "Alerting Customers When Monitored Balances Cross Limits or Thresholds".

About Balance Monitoring Groups

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

• The owner. Group owners have permission to view group balances, add or remove group members, and add or change threshold and credit limit values.

  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.

• All members. Any of the following can be members of a monitor group:

  • Accounts. Members of a balance monitoring 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 balance monitoring group can include services, such as the GSM service, for a group of accounts. When the member is a service, BRM monitors balances for that service only. For example, a company that pays all GSM services for its employees could create a balance monitoring 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 balance monitoring groups. BRM tracks the groups to which an account or service belongs and then accesses this information during the rating process to determine where to apply balance impacts.

• The monitoring group type. Monitoring group types specify the type of members that the group can contain. 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 23-1 shows the group types supported by balance monitoring.

  Table 23-1 Supported Group Types

  Group Type	Description
  Hierarchy Credit Exposure (H_CE)	Supports near real-time monitoring of the group's balance. Members include paying and nonpaying child accounts and their services.
  Payment Responsible Credit Exposure (PR_CE)	Supports near real-time monitoring of the group's balance. Members include nonpaying child accounts and their services.
  Subscription Credit Exposure (SUB_CE)	Supports near real-time monitoring of the group's balance. Members include services in a subscription group.
  Payment Responsible Real-Time Credit Enforcement (PR_RTCE)	Supports real-time monitoring of the group's balance. Members include nonpaying child accounts and their services. Allows you to change the credit limit settings for the group's owner and members to do the following: Roll up the credit limits from one or more child bill units in the group to the owner's bill unit. For example, assume a group's owner has a $1000 credit limit and the three child group members each have $100 credit limits. If you specify to roll up the credit limits of all three child group members, the group owner's credit limit would change to $1300. Nullify a child's credit limit after it is rolled up to the owner. If you specified to nullify the credit limits in the previous example, BRM would change the credit limit for all three child group members to NULL. If you specified to maintain the credit limits, BRM would keep the credit limit for all three child group members at $100.

When a customer attempts to add a member to a balance monitoring group, BRM validates the member against rules you specify for each monitoring group type. The default implementation contains no validation rules for these monitoring group types, but you can create new 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" in BRM Opcode Guide.

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.

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 "Managing Balances" in BRM Managing 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.

  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.

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

Note:

For PR_RTCE monitor types, you do not need to run pin_monitor_balance. This monitor group balance is updated in real time whenever an events occurs.

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

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

• As a result cycle-fee 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.

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

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.

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 must set a value for each parameter. 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.

Note:

For payment responsibility real-time credit enforcement (PR_RTCE) balance monitoring groups, you can also specify the following:

• Whether to roll up a member's account credit limit to the owner of the PR_RTCE balance monitoring group.

• Whether to set a member's account credit limit to NULL after it is rolled up to the owner of the PR_RTCE balance monitoring group.

You define a balance monitor's credit floor, credit limit, and threshold values when you create the balance monitor in a custom client application. BRM then stores the values in a /config/credit_profile object in the BRM database. See "Managing Balance Monitors" in BRM Opcode Guide for more information.

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

Providing Your Customers with Access to Monitor Balances

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" in BRM Opcode Guide.

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

• Credit limit (optional)

• Credit floor (optional)

• Threshold settings (optional)

The process that BRM uses to create or modify a balance monitor depends on whether you implement it 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.

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 monitoring group. BRM determines whether the following is true:

   • AMS is enabled.

   • The monitor type is H_CE, PR_CE, SUB_CE, or PR_RTCE.

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

Note:

AMS works only for the default monitor group types: H_CE, PR_CE, SUB_CE, and PR_RTCE. 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 changes, the following occurs:

1. BRM generates a notification event.

2. The BRM event notification system 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 manually 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 "Creating and Maintaining Balance Monitors Manually".

About Processing Balance Impacts

BRM processes balances impacts for balance monitoring as follows:

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

   About Balance Monitoring and Real-Time Rating

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

   See "Understanding the Monitor Queue".

3. The pin_monitor_balance utility retrieves and processes data from the monitor queue. If a balance crosses a credit limit or threshold, the utility generates a threshold breach notification event.

   See "Using pin_monitor_balance to Update Monitored Balances".

4. If a threshold breach notification event is generated, the BRM event notification system calls the specified opcode, which processes the event data and passes information to your custom client application.

   See "About Using Event Notification to Alert Customers".

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)

Understanding the Monitor Queue

Note:

The monitor queue is not applicable to PR_RTCE monitor types, because their balance impacts happen in real time.

The monitor queue (/monitor_queue) holds all monitor balance impacts generated by 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 queue. 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 its 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

Note:

The pin_monitor_balance utility is not applicable for PR_RTCE monitor types, because their balance impacts happen in real time.

You use the pin_monitor_balance utility to apply balance impacts to a balance monitor. 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 five 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 queue (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:

   1. Updates the monitored balance (/balance_group/monitor). See "Using pin_monitor_balance to Update Monitored Balances".

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

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

   For more information about the opcode, see "Updating Monitor Balances and Sending Credit Limit/Threshold Breach Notifications" in BRM Opcode Guide.

About Using Event Notification to Alert Customers

BRM uses event notification to alert monitor owners when balances cross a threshold or credit limit. After an /event/notification/threshold or /event/notification/threshold_below event occurs, the BRM event notification system does the following:

1. Calls the opcode associated with the event in your system's event notification list. By default, the event notification system calls the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode.

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

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

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

Configuring Your BRM System for Balance Monitoring

To set up your BRM system for balance monitoring, do the following:

1. Enable balance monitoring in BRM.

   See "Enabling Balance Monitoring in BRM".

2. Enable AMS in BRM.

   See "Enabling AMS in BRM".

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

   See "Configuring Event Notification for Balance Monitoring".

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

   See "Specifying a Wait Time before Rerating Events".

5. For H_CE, PR_CE, and SUB_CE monitoring group types only, do the following:

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

   • Run pin_monitor_balance on a regular basis.

     See "Running pin_monitor_balance to Update Monitored Balances".

6. Configure your custom client application to call the appropriate opcodes for managing balance monitoring.

   See "Implementing Balance Monitoring in Custom Client Applications".

7. For payment responsible real-time credit enforcement (PR_RTCE) balance monitoring groups only, configure the following:

   • For each child group member, whether to roll up its credit limit to the group's owner.

     See "Rolling Up Child Credit Limits to Owners in PR_RTCE Groups".

   • Whether to nullify the credit limits of child group members after their credits are rolled up to the group's owner.

     See "Nullifying Credit Limits for PR_RTCE Child Members".

After your system is set up, you can use a custom client application to create balance monitors and balance monitoring groups for your customers.

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. Set BalanceMonitoring to enabled:

   <BalanceMonitoring>enabled</BalanceMonitoring>

   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.

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

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

   pin_bus_params bus_params_multi_bal.xml

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

5. 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 the testnap Utility to Test BRM" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects" in BRM Developer's Guide.

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

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

7. (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. Set AutomatedMonitorSetup to enabled:

   <AutomatedMonitorSetup>enabled</AutomatedMonitorSetup>

   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.

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

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

   pin_bus_params bus_params_subscription.xml

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

5. 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 the testnap Utility to Test BRM" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects" in BRM Developer's Guide.

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

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

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

Configuring Event Notification for Balance Monitoring

When the balance of a monitoring 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.

• /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 these events occur, the event notification system calls the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode (opcode number 301). The policy opcode then sends a message to your customers using the Email Data Manager (DM). However, you can customize this policy opcode to perform other actions.

Note:

To find an opcode's number, see the opcode header files in BRM_home/include/ops.

To configure the event notification feature for balance monitoring:

1. Open your BRM_home/sys/data/config/pin_notify file.

2. Add the following lines:

   301    0       /event/notification/threshold
   301    0       /event/notification/threshold_below

   Note:

   If you want the events to trigger calls to other opcodes, change the opcode number. 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 following lines in bold are uncommented:

   # 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

   Note:

   If the event is configured to trigger opcodes 7853 and 1301 (PCM_OP_PUBLISH_GEN_PAYLOAD), list the events in this order:

   1301    /event/group/sharing/monitor/create
   7853    /event/group/sharing/monitor/create

4. Save and close your pin_notify file.

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

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

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

   1. Go to the directory that contains your final pin_notify file.

   2. Run the following command to run the load_pin_notify utility:

      load_pin_notify configFileName

      where configFileName is the name of your final pin_notify file. If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file.

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

Specifying a Wait Time before Rerating Events

You must configure pin_rerate to wait a specified amount of time before rerating events.

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.

   - pin_rerate        delay        300

   The default is 0.

3. Save and close the file.

Configuring pin_monitor_balance to Process Events in the Order Created

Note:

This step is not required for PR_RTCE monitor group types.

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

Note:

This step is not required for PR_RTCE monitor group types.

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

   pin_monitor_balance [-d] [-v]

   For more information, see "pin_monitor_balance".

Implementing Balance Monitoring in Custom 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 monitoring group

• Receive alerts when a balance monitoring group's credit limit or threshold is crossed

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

1. Create or update balance monitors and balance monitoring groups.

   • To have BRM create them automatically for you, see "Creating and Maintaining Balance Monitors Automatically".

   • To create them manually, see "Creating and Maintaining Balance Monitors Manually".

2. Display the balances for a balance monitoring group or a list of monitors owned by an account or service.

   See "Displaying Balance Monitor Information in Client Applications" in BRM Opcode Guide.

3. Send notifications when a group's credit limit or threshold is crossed.

   See "Updating Monitor Balances and Sending Credit Limit/Threshold Breach Notifications" in BRM Opcode Guide.

4. (Optional) Specify whether to include item transfers in the balances of monitor groups.

   See "Specifying Whether Item Transfers Affect Balance Monitors".

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 Monitors Automatically

You can configure a custom client application to automatically manage balance monitors by calling BRM opcodes. To do so, add the following functionality to your custom client application:

1. Manage balance monitors.

   To create and modify balance monitors (/balance_group/monitor objects), call PCM_OP_CUST_SET_BAL_GRP. See "Creating and Updating Balance Monitors" in BRM Opcode Guide.

   Note:

   You cannot delete /balance_group/monitor objects. However, you can deactivate the monitor group by deleting its associated /group/sharing/monitor object. See "Deactivating Balance Monitors" in BRM Opcode Guide.

2. Manage balance monitoring groups:

   • To create balance monitoring groups, call PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE.

     When the balance monitor group is created successfully, the opcode generates an /event/group/sharing/monitor/create event.

   • To modify balance monitoring groups, call PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY.

     When the balance monitor group is modified successfully, the opcode generates an /event/group/sharing/monitor/modify event.

   • To delete balance monitoring groups, call PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE.

     When the balance monitor group is deleted successfully, the opcode generates an /event/group/sharing/monitor/delete event.

   The generated events trigger the BRM event notification system to call the AMS opcodes, which automatically add and remove members from balance monitoring groups (/group/sharing/monitor objects) and update each member's /ordered_balgrp object.

   For more information about these opcodes, see "Managing Sharing Groups" in BRM Opcode Guide.

Creating and Maintaining Balance Monitors Manually

To create and maintain balance monitors manually (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 balance monitors (/balance_group/monitor objects).

   See "Managing Balance Monitors" in BRM Opcode Guide.

2. PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE: This opcode creates balance monitoring groups (/group/sharing/monitor objects).

   You must pass all group members in the input flist.

   • To create, modify, or delete a balance monitoring group, see "Managing Sharing Groups" in BRM Opcode Guide.

   • To validate potential members before adding them to a balance monitoring group, see "Validating the Members of a Balance Monitor Group" in BRM Opcode Guide.

3. PCM_OP_SUBSCRIPTION_ORDERED_BALGRP: This opcode creates and updates each member's list of sharing groups to which they belong (in /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 monitoring group. See "Managing Ordered Balance Groups" in BRM Opcode Guide.

   For example, assume a balance monitor includes the following account hierarchy shown in Figure 23-1.

   Figure 23-1 Example Account Hierarchy in a Balance Monitor

   
   

   
   Description of "Figure 23-1 Example Account Hierarchy in a Balance Monitor"

   
   

   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

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 "Making Adjustments" in BRM Managing Accounts Receivable.

Rolling Up Child Credit Limits to Owners in PR_RTCE Groups

PR_RTCE balance monitoring groups allow you to roll up the credit limits from one or more child bill units in the group to the owner's bill unit.

To configure BRM to roll up the credit limit from a child's bill unit to a parent's bill unit in a balance monitoring group:

• Using Billing Care: Use the Roll Up Credit Limit check box when creating a child account, modifying a child account's credit limit, adding a nonpaying child to a billing hierarchy, or adding a paying parent to a billing hierarchy.

  See "Working with Credit Limits, Credit Floors, and Thresholds" and "Billing Hierarchies" in Billing Care Online Help.

• Using a custom client application calling opcodes: Setting PIN_FLD_TYPE_STR set to PR_RTCE and PIN_FLD_ROLL_UP_CREDIT_LIMIT set to 1 when creating a balance monitoring group, creating a child member's account, or modifying a child member's account.

  See "Creating a Balance Monitor Group" and "How BRM Handles Consumption Rules and Credit Limits" in BRM Opcode Guide.

  When creating or modifying a child member's account

• Using a custom client application calling the Billing Care REST API: Setting the rollUp field in the request payload of the following endpoints: Calling the Add a Bill Unit to a Hierarchy, Create Credit Limits for a Balance Group, Create a Bill Unit, or Update a Bill Unit for an Account.

  See REST API Reference for Billing Care.

Nullifying Credit Limits for PR_RTCE Child Members

For PR_RTCE balance monitoring group types, you can configure whether each child member's credit limit is set to NULL or remains unchanged after their credit limit is rolled up to the group's owner. By default, their credit limit is nullified.

You configure this functionality by modifying the rating instance of the /config/business_params object using the pin_bus_params utility (see "pin_bus_params" in BRM Developer's Guide).

To configure whether to nullify child member credit limits in PR_RTCE groups, do the following:

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

   pin_bus_params -r BusParamsRating bus_params_rating.xml 

   This command creates the XML file named bus_params_rating.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. Set ResetMemberCreditLimit to the appropriate value:

   <ResetMemberCreditLimit>value</ResetMemberCreditLimit>

   where value is:

   • enabled specifies that after a member's credit limit is rolled up to the group's owner, to set the member's credit limit to NULL. This is the default value.

   • disabled specifies to not change the member's credit limit after it is rolled up to the group's owner.

3. Save the file and change the file name from bus_params_rating.xml.out to bus_params_rating.xml.

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

   pin_bus_params bus_params_rating.xml

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

5. 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 the testnap Utility to Test BRM" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects" in BRM Developer's Guide.

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

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

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