1. Opcode Guide
  2. Opcode Workflows
  3. Group Opcode Workflows

13 Group Opcode Workflows

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

Topics in this document:

Opcodes Described in This Chapter

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

Caution:

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

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

Table 13-1 Opcodes Described in This Chapter

Opcode Topic

PCM_OP_BAL_APPLY_MONITOR_IMPACTS

Updating Monitor Balances and Sending Credit Limit/Threshold Breach Notifications

PCM_OP_BAL_CHANGE_VALIDITY

Modifying the Sub-balance Validity Period

PCM_OP_BAL_GET_ACCT_MONITORS

Retrieving the Balance Monitors Owned by an Account or Service

PCM_OP_BAL_GET_MONITOR_BAL

Retrieving the Balances for a Monitor Group

PCM_OP_BAL_POL_GET_BAL_GRP_AND_SVC

Customizing the Default Balance Group of a Bill Unit

PCM_OP_BILL_GROUP_REMOVE_PAYING_MEMBERS

Removing Members from Sharing Groups

PCM_OP_BILL_SET_LIMIT_AND_CR

Creating Balance Groups

Modifying Sub-balances

PCM_OP_CUST_COMMIT_CUSTOMER

Creating Balance Groups
PCM_OP_CUST_CONVERT_WHOLESALE_HIERARCHY

Converting an Account Hierarchy to Wholesale Billing

PCM_OP_CUST_CREATE_BAL_GRP

Creating Balance Groups

PCM_OP_CUST_DELETE_BAL_GRP

Deleting a Balance Group

Deactivating Balance Monitors

PCM_OP_CUST_MODIFY_BAL_GRP

Creating Balance Groups

PCM_OP_CUST_MODIFY_CUSTOMER

Creating Balance Groups

Moving a Balance Group from One Bill Unit to Another

PCM_OP_CUST_SET_BAL_GRP

Creating Balance Groups

Creating and Updating Balance Monitors

PCM_OP_MONITOR_ACCOUNT_HIERARCHY

Adding and Removing Members Automatically to Sharing Groups

Adding Members to Hierarchy-Type Sharing Groups Automatically

PCM_OP_MONITOR_BILLING_HIERARCHY

Adding and Removing Members Automatically to Sharing Groups

Adding Members to Paying Responsibility-Type Sharing Groups Automatically

PCM_OP_MONITOR_HIERARCHY_CLEANUP

Adding and Removing Members Automatically to Sharing Groups

Removing Members from Balance Monitor Groups

PCM_OP_MONITOR_PROCESS_BILLING_MONITORS

Adding Members to Payment Responsibility-Type Balance Monitors

PCM_OP_MONITOR_PROCESS_HIERARCHY_MONITORS

Adding Members to Hierarchy-Type Balance Monitors

PCM_OP_MONITOR_SERVICE_HIERARCHY

Adding and Removing Members Automatically to Sharing Groups

Updating Subscription-Type Monitors Automatically

PCM_OP_MONITOR_SETUP_MEMBERS

Adding and Removing Members Automatically to Sharing Groups

Adding Members to Newly Created Sharing Groups Automatically

PCM_OP_MONITOR_UPDATE_MONITORS

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

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP

Managing Ordered Balance Groups

Deleting a Sharing Group

Creating an Ordered Balance Group

Adding a Sharing Group to an Ordered Balance Group

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

Deleting a Sharing Group from an Ordered Balance Group

Customizing the Order in Which to Apply Sharing Groups

Deleting an Ordered Balance Group

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY

Managing Ordered Balance Groups

Creating and Modifying Multiple Ordered Balance Groups Simultaneously

PCM_OP_SUBSCRIPTION_POL_GET_SPONSORS

Getting a List of Charges Available for Charge Sharing

PCM_OP_SUBSCRIPTION_POL_ORDERED_BALGRP_PRIORITY

Creating an Ordered Balance Group

Adding a Sharing Group to an Ordered Balance Group

Customizing the Order in Which to Apply Sharing Groups

PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS

Validating the Members of a Balance Monitor Group
PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING

Creating a Charge Sharing Group

Adding Sponsored Charges to a Charge Sharing Group

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE

Creating a Sharing Group

PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE

Deleting a Sharing Group

PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY

Modifying a Sharing Group

PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT

Changing the Owner of a Sharing Group

Changing the Owner of a Balance Monitor

Managing Sharing Groups

To manage balance monitoring groups, charge sharing groups, discount sharing groups, profile sharing groups, and product sharing groups, use the following opcodes:

Creating a Sharing Group

Use PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE to create a sharing group, including balance monitoring groups, charge sharing groups, discount sharing groups, profile sharing groups, or product sharing groups. The members of a sharing group can include individual services, all services of a specific type, or a group of accounts.

Observe the following guidelines when creating sharing groups:

  • Products, discounts, and charges shared by the group owner must be valid, meaning that it has an active or inactive status and has not expired.

  • If a member owns another sharing group, the owner of the sharing group you create cannot belong to the member's group.

  • The name of a sharing group must be unique and cannot be used for another sharing group owned by the group owner.

  • If the member is a service, the service can be either a service type or a specific service instance. When adding a type-only service, all instances of that service type become members. However, the subtypes of the service type do not become members.

  • By default, the parent account and all group members must reside in the same database schema. To enable sharing groups to include members from other database schemas, enable the CrossSchemaSharingGroup business parameter. See "Enabling Group Members to Reside in Multiple Schemas" in BRM Managing Customers.

If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE returns the following:

  • The POID of the sharing object that was created: /group/sharing/products, /group/sharing/discounts, /group/sharing/charges, /group/sharing/monitor, or /group/sharing/profiles.

  • The POID of the event generated to record the creation: /event/group/sharing/products/create, /event/group/sharing/discounts/create, /event/group/sharing/profiles/create, /event/group/sharing/monitor/create, or /event/group/sharing/charges/create.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE fails in the following cases:

  • The owner is also a member of a sharing group owed by one of the members.

  • A product, charge, or discount in the input flist is not valid.

  • The primary currency for any of the members is different from the owner's primary currency.

Creating a sharing group is the first step toward activating sharing. To apply shared discounts, charges, profiles, and products for the group's members, you must also create ordered balance groups for the members. See "Creating an Ordered Balance Group".

Note:

When creating a global charge sharing group, do not create or modify each member's ordered balance group.

Creating a Discount Sharing Group

To create a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE does the following:

  1. Creates a /group/sharing/discounts object and assigns the group owner.

    Note:

    • The owner cannot be a member of its own group.

    • If a member of the group owns a discount or charge sharing group, the owner cannot be a member of that group.

  2. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the /group/sharing/discounts object.

    Each PIN_FLD_MEMBERS array element specifies an /account and a /service object. If the /service object is NULL, the /account object is the member.

    If the PIN_FLD_SERVICE_OBJ field for a member specifies a type-only service, such as GSM, instead of a specific service instance, all instances of that service type become members of the discount sharing group. However, subclass instances of the service type do not become members.

    For example, if the input flist specifies the GSM service type, the opcode adds all /service/telco/gsm instances as members. But, it does not add the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

    If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/discounts object is created. The member account can join the group and purchase the service later. BRM begins discount sharing for the service as soon as the member buys the service and joins the discount sharing group.

  3. Adds the /discount objects in the PIN_FLD_DISCOUNTS array to the DISCOUNTS array of the /group/sharing/discounts object.

    The discounts must be owned by the discount sharing group owner. They must also have validity dates and a valid status (active or inactive). If the PIN_FLD_DISCOUNTS array is empty, all of the owner's discounts are shared. In this case, the PIN_FLD_DISCOUNTS array in the /group/sharing/discounts object contains NULL in the PIN_FLD_DISCOUNT_OBJ and PIN_FLD_OFFERING_OBJ fields.

  4. Generates an /event/group/sharing/discounts/create event to record the creation of the discount sharing group.

Creating a Charge Sharing Group

To create a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE does the following:

  1. Creates a /group/sharing/charges object, and assigns the owner to the group.

    Note:

    The owner cannot be a member of its own group.

  2. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the /group/sharing/charges object.

    Each PIN_FLD_MEMBERS array element specifies an /account and a /service object. If the /service object is NULL, the /account is the member.

    If the PIN_FLD_SERVICE_OBJ field for a member specifies a type-only service, such as GSM, instead of a specific service instance, all instances of that service type become members of the charge sharing group. However, subclass instances of the service type do not become members.

    For example, if the input flist specifies the GSM service type, the opcode adds all /service/telco/gsm instances as members. But, it does not add the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

    If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/charges object is created. The member account can join the group and purchase the service later. BRM begins charge sharing for the service as soon as the member buys the service and joins the charge sharing group. BRM handles future services for charge sharing in the same way that it does for discount sharing.

  3. Validates any product specification attributes on the /sponsorship objects by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.

  4. Adds /sponsor objects in the PIN_FLD_SPONSORS array to the SPONSORS array of the /group/sharing/charges object.

  5. Generates an /event/group/sharing/charges/create event to record the creation of the charge sharing group.

Creating a Product Sharing Group

To create a product sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE does the following:

  1. Creates a /group/sharing/products object and assigns the owner to the group.

    Note:

    The owner cannot be a member of its own group. Also, an account can be the owner of only one product sharing group at a time.

  2. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the /group/sharing/products object.

    Each PIN_FLD_MEMBERS array element specifies an /account and a /service object. If the /service object is NULL, the /account is the member.

    If the PIN_FLD_SERVICE_OBJ field for a member specifies a type-only service, such as GSM, instead of a specific service instance, all instances of that service type become members of the product sharing group. However, subclass instances of the service type do not become members. For example, if the input flist specifies the GSM service type, the opcode adds all /service/telco/gsm instances as members but it does not add the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

    If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/products object is created. The member account can join the group and purchase the service later. BRM begins sharing the product as soon as the member buys the service and joins the product sharing group. BRM handles future services for product sharing in the same way that it does for discount sharing.

  3. Validates any product specification attributes on the /sponsorship objects by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.

  4. Adds /sponsor objects in the PIN_FLD_SPONSORS array to the SPONSORS array of the /group/sharing/products object.

  5. Generates an /event/group/sharing/products/create event.

Creating a Balance Monitor Group

To create a balance monitor group (/group/sharing/monitor object), call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE opcode and pass the following information in the opcode's input flist:

  • 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

  • Sharing group type set to the type-only POID for /group/sharing/monitor

  • Balance monitor (/balance_group/monitor object) to associate with the monitoring group

  • List of members you want to add or delete

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE does the following:

  1. Verifies that balance monitoring is enabled.

  2. Calls the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode to validate the members.

    See "Validating the Members of a Balance Monitor Group" for more information.

  3. Creates a /group/sharing/monitor object and assigns the owner to the group.

    Note:

    The owner cannot be a member of its own group. Also, an account can be the owner of only one balance monitor group at a time.

  4. If the PIN_FLD_TYPE_STR input flist field is set to PR_RTCE and the PIN_FLD_ROLL_UP_CREDIT_LIMIT input flist field is set to 1, does the following:

    1. Rolls up each member's credit limit to the owner's billing account.

    2. If the ResetMemberCreditLimit business parameter is enabled, sets each member's credit limit to NULL. See "Nullifying Credit Limits for PR_RTCE Child Members" in BRM Managing Customers.

  5. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the /group/sharing/products object.

    Each PIN_FLD_MEMBERS array element specifies an /account and a /service object. If the /service object is NULL, the /account is the member.

    If the PIN_FLD_SERVICE_OBJ field for a member specifies a type-only service, such as GSM, instead of a specific service instance, all instances of that service type become members of the balance monitor group. However, subclass instances of the service type do not become members. For example, if the input flist specifies the GSM service type, the opcode adds all /service/telco/gsm instances as members but it does not add the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

    If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/products object is created. The member account can join the group and purchase the service later. BRM begins sharing the product as soon as the member buys the service and joins the balance monitor group. BRM handles future services for balance monitoring in the same way that it does for discount sharing.

  6. Validates any product specification attributes on the /sponsorship objects by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.

  7. Adds /sponsor objects in the PIN_FLD_SPONSORS array to the SPONSORS array of the /group/sharing/monitor object.

  8. Generates an /event/group/sharing/monitor/create event.

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.

Modifying a Sharing Group

Use PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY to modify a product sharing group, discount sharing group, profile sharing group, or charge sharing group. You can modify sharing groups by:

  • Adding members to an existing group.

  • Adding discounts or charges to an existing group.

If successful, it returns the POID of the group that was modified and the POIDs of the events generated by PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY to record the group modification.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY fails in the following cases:

  • If the owner is a member of its own group or a group owned by a group member.

  • If a discount offer in the input flist is not valid.

Adding a member to a sharing group is the first step toward activating sharing. For the new member to benefit from shared products, profiles, discounts, and charges, you must also create an ordered balance group for the member. See "Creating an Ordered Balance Group".

Note:

You do not need to create ordered balance groups for members of global charge sharing groups.

Adding Members to a Discount or Charge Sharing Group

To add members to a discount or charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY does the following:

Caution:

The element ID for each member in the input flist must be unique within the membership. If an element ID is already being used by an existing member in the group object you are modifying, the opcode overwrites the existing member. If you do not know the element IDs of each member in the object, you can prevent member loss by making sure the flist includes both existing and new members.

  1. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the group object:

    • The /group/sharing/charges object for a charge sharing group.

    • The /group/sharing/discounts object for a discount sharing group.

    Each PIN_FLD_MEMBERS array element specifies an /account and a /service object. If the /service object is NULL, the /account is the member.

    Note:

    • The owner cannot be a member of its own group.

    • If a member of the group owns a discount or charge sharing group, the owner cannot be a member of that group.

    • If the PIN_FLD_MEMBERS array is empty, this opcode calls PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE to delete all members from the group.

    If the PIN_FLD_SERVICE_OBJ field for a member specifies a type-only service, such as GSM, instead of a specific service instance, all instances of that service type become members of the discount sharing group. However, subclass instances of the service type do not become members.

    For example, if the input flist specifies the GSM service type, this opcode adds all /service/telco/gsm instances as members. But, it does not add the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

    If you specify a service type as a member, the member account does not need to own the service when the group object is modified. The member account can join the group and purchase the service later. BRM begins discount or charge sharing for the service as soon as the member buys the service and joins the discount or charge sharing group.

  2. Generates an event to record member changes:

    • An /event/group/sharing/discounts/modify event for a discount sharing group.

    • An /event/group/sharing/charges/modify event for a charge sharing group.

Adding Discounts to a Discount Sharing Group

To add discounts for a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY does the following:

  1. Adds the /discount objects in the PIN_FLD_DISCOUNTS array to the /group/sharing/discounts object's discounts array.

    • The discount instance must be owned by the group owner. They must also have validity dates and a valid status (active or inactive).

    • If the PIN_FLD_DISCOUNTS array is empty, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE is called to delete all /discount objects from the /group/sharing/discounts object's discounts array.

  2. Generates an /event/group/sharing/discounts/modify event to record the event.

Adding Sponsored Charges to a Charge Sharing Group

To add sponsored charges to a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY does the following:

  1. Validates any product specification attributes on the /sponsorship object by calling the PCM_OP_SUBSCRIPTION_POL_VALIDATE_OFFERING policy opcode. By default, this policy opcode is an empty hook, but you can customize it to validate product specification attributes. See "Configuring Product Specification Attributes for Pricing Components" in PDC Creating Product Offerings or "Defining Product Specification Attributes for Pricing Components" in Configuring Pipeline Rating and Discounting.

  2. Adds the /sponsorship objects in the PIN_FLD_SPONSORS array to the /group/sharing/charges object's SPONSORS array.

    Note:

    If the PIN_FLD_SPONSORS array is empty, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE is called to delete all /sponsor objects from the /group/sharing/charges object's SPONSORS array.

  3. Generates an /event/group/sharing/charges/modify event to record the event.

Deleting a Sharing Group

Use PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE to delete a discount sharing group, charge sharing group, profile sharing group, or product sharing group. You can also use this opcode to delete shared discounts, sponsored charges, shared profiles, shared products, and group members.

  • For a discount sharing group, this opcode deletes shared discounts, group members, or the sharing group itself.

  • For a charge sharing group, this opcode deletes sponsored charges, group members, or the sharing group itself.

  • For a profile sharing group, this opcode deletes shared profiles, group members, or the sharing group itself.

  • For a product sharing group, this opcode deletes shared products, group members, or the sharing group itself.

Deleting a Discount Sharing Group

To delete a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

  1. For each member in the group, it calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to delete the /group/sharing/discounts object from the member's /ordered_balgrp object.

  2. Deletes the /group/sharing/discounts object.

  3. Generates an /event/group/sharing/discounts/delete event to record the deletion.

Deleting a Charge Sharing Group

To delete a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

  1. For each member in the group, it calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to delete the /group/sharing/charges object from the member's /ordered_balgrp object.

  2. Deletes the /group/sharing/charges object.

  3. Generates an /event/group/sharing/charges/delete event.

Deleting a Member from a Discount Sharing Group

To delete a member from a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

Caution:

The element ID for each member in the /group/sharing/discounts object is unique. If you use an incorrect element ID for the member you want to delete, this opcode deletes the wrong member.

  1. Calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to delete the /group/sharing/discounts object from the member's /ordered_balgrp object.

  2. Deletes the member from the /group/sharing/discounts members array.

  3. Generates an /event/group/sharing/discounts/delete event.

Deleting a Member from a Charge Sharing Group

To delete a member from a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

Caution:

The element ID for each member in the /group/sharing/charges object is unique. If you use an incorrect element ID for the member you want to delete, this opcode deletes the wrong member.

  1. Calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to delete the /group/sharing/charges object from the member's /ordered_balgrp object.

  2. Deletes the member from the /group/sharing/charges members array.

  3. Generates an /event/group/sharing/charges/delete event.

Deleting a Shared Discount from a Discount Sharing Group

To delete a shared discount from a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

Caution:

The OFFERING_OBJ uniquely identifies each shared discount in the /group/sharing/discounts object. If you use an incorrect OFFERING_OBJ for the discount you want to delete, this opcode deletes the wrong discount.

  1. Deletes the /discount objects specified in the PIN_FLD_DISCOUNTS array from the DISCOUNTS array of the /group/sharing/discounts object.

  2. Generates an /event/group/sharing/discounts/delete event to record the deletion.

Deleting a Sponsored Charge from a Charge Sharing Group

To delete a sponsored charge from a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

Caution:

The element ID for each shared charge in the /group/sharing/charges object is unique. If you use an incorrect element ID for the charge you want to delete, this opcode deletes the wrong charge.

  1. Deletes the /sponsor objects specified in the PIN_FLD_SPONSORS array from the SPONSORS array of the /group/sharing/charges object.

  2. Generates an /event/group/sharing/charges/delete event to record the deletion.

If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE returns the POID of the sharing group object that was modified and the POID of the event that was generated.

Changing the Owner of a Sharing Group

Use PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT to change the owner of a discount sharing group, charge sharing group, profile sharing group, or product sharing group.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT takes the following input:

  • PIN_FLD_POID: The /account object of the current owner.

  • PIN_FLD_GROUP_OBJ: The sharing group object that is being changed: /group/sharing/discounts, /group/sharing/charges, /group/sharing/profiles, or /group/sharing/products.

  • PIN_FLD_ACCOUNT_OBJ: The /account object of the new owner.

    Note:

    If you are changing the ownership of a discount or charge sharing group from one service to another in the same account, the object passed in this field matches the one in the PIN_FLD_POID field.

  • PIN_FLD_PARENT: The new owner, which is either an /account object or a /service object.

  • PIN_FLD_BAL_GRP_OBJ: The /balance_group object used to track sharing activities for the new owner.

  • The list of discounts, profiles, or products associated with the new owner.

If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT returns the POID of the sharing group that was modified and the event that was generated to record the owner change.

This opcode fails if the new owner is a member of the sharing group.

Changing the Owner of a Discount Sharing Group

To change the owner of a discount sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT does the following:

  1. Verifies the following:

    • The input flist contains the /balance_group object and /account object for the new discount sharing group owner.

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

    • The currency of the new owner is the same as the currency of the old owner.

    • There are no circular relationships. For example, the owner cannot be a member of its own group. Also, if a member of the group owns a sharing group, the owner cannot be a member of that group.

  2. Deletes the current owner's discounts from the /group/sharing/discounts object.

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

  4. Adds the new owner's shared discounts to the /group/sharing/discounts object.

  5. Generates an /event/group/sharing/discounts/modify event to record the owner change.

Changing the Owner of a Charge Sharing Group

To change the owner of a charge sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT does the following:

  1. Verifies the following:

    • The input flist contains the /balance_group object and /account object for the new charge sharing group owner.

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

    • The currency of the new owner is the same as the currency of the old owner.

    • There are no circular relationships. For example, the owner cannot be a member of its own group.

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

  3. Updates the sponsor flags in the old owner's and new owner's bill units (/billinfo objects).

  4. Generates an /event/group/sharing/charges/modify event to record the owner change.

Changing the Owner of a Balance Monitor

To change the owner of a balance monitor (/group/sharing/monitor object), call the PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT opcode.

Note:

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

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

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.

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. Calls PCM_OP_MONITOR_UPDATE_MONITORS to generate an /event/billing/monitor/update event (when an /ordered_balgrp object is created or modified) or an /event/billing/monitor/delete event (when an /ordered_balgrp object is deleted).

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

Getting a List of Charges Available for Charge Sharing

To get a list of all charges available for charge sharing, use PCM_OP_SUBSCRIPTION_POL_GET_SPONSORS.

When you create a charge sharing group, you select the charges, or chargeshares, that you want the owner to assume for the members. Chargeshares are stored in /sponsorship objects in the BRM database. By default, this opcode retrieves all the /sponsorship objects.

You can customize PCM_OP_SUBSCRIPTION_POL_GET_SPONSORS to filter or return a subset of /sponsorship objects from the list of all available /sponsorship objects. For example, you can customize this opcode to get a list of the chargeshares that include a particular set of events.

PCM_OP_SUBSCRIPTION_POL_GET_SPONSORS is not called by any opcode.

Managing Ordered Balance Groups

Use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to create, modify, or delete an ordered balance group (/ordered_balgrp object) for an account or service that is a member of a sharing group.

The ordered balance group contains links to the sharing groups that the member has joined, listed in order by rank. For discount sharing groups, charge sharing groups, and product sharing groups, the rank controls the order in which the group's balances are impacted by events. For profile sharing groups, the rank is not significant.

Note:

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP creates or modifies one ordered balance group at a time. To create or modify more than one ordered balance group at time, use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY. See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

An ordered balance group object is created when an account or service joins a sharing group. You can modify an ordered balance group as follows:

  • Add a sharing group

  • Delete a sharing group

The /ordered_balgrp object stores the sharing groups that the member has joined in its PIN_FLD_ORDERED_BALGRPS array so that balance impacts are applied to the owning balance group for each sharing group. If the array contains no sharing groups, all balance impacts are applied to the member's balance group.

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP uses the element IDs in the PIN_FLD_ORDERED_BALGRPS array to determine the order in which to apply the shared discounts, charges, and products. The array has separate segments for discount sharing groups, charge sharing groups, and product sharing groups. The segment for each one is independent of the segment for the others; BRM does not intermingle the groups. In the array, product sharing groups are always first, followed by discount sharing groups, and then charge sharing groups.

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP takes as input an /ordered_balgrp object and a string that specifies whether to create, modify, delete, or list the ordered balance group object.

Note:

The /ordered_balgrp object must be specified if the action is to modify or delete the object.

If successful, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP returns the POID of the /ordered_balgrp object and the POID of the event generated as a result of the creation, modification, or deletion.

If the action is List, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP returns all sharing group objects and their ranks in the /ordered_balgrp object.

After you create an /ordered_balgrp object, you can modify the sequence of the groups in the ordered balance group list. See "Customizing the Order in Which to Apply Sharing Groups".

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP fails in the following cases:

  • When the PIN_FLD_ORDERED_BALGROUPS array contains more than one instance of a sharing group.

  • When the PIN_FLD_ACTION is Create, but an /ordered_balgrp object for the account or service already exists.

Creating an Ordered Balance Group

To create an ordered balance group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

  1. Creates an /ordered_balgrp object for the /account or /service object specified in the input flist.

  2. Adds the sharing group objects specified in the input flist to the /ordered_balgrp object.

    This opcode arranges the sharing groups in the order defined by the element IDs in the input flist. The default order is:

    1. Automated product sharing groups

    2. Automated discount offer sharing groups

    3. Discount sharing groups

    4. Charge sharing groups

  3. Calls the PCM_OP_SUBSCRIPTION_POL_ORDERED_BALGRP_PRIORITY policy opcode to customize the order. By default, this policy opcode does nothing.

  4. Generates an /event/billing/ordered_balgrp/create event to record the object creation.

Alternatively, you can use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY to create one or more ordered balance groups. See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Adding a Sharing Group to an Ordered Balance Group

To add a sharing group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

  1. Adds the sharing group objects specified in the input flist to the /ordered_balgrp object.

    This opcode arranges the sharing groups in the order defined by the element IDs in the input flist. The default order is:

    1. Automated product sharing groups

    2. Automated discount offer sharing groups

    3. Discount sharing groups

    4. Charge sharing groups

  2. Calls the PCM_OP_SUBSCRIPTION_POL_ORDERED_BALGRP_PRIORITY policy opcode to customize the order. By default, this policy opcode does nothing.

  3. Generates an /event/billing/ordered_balgrp/modify event to record the object modification.

Alternatively, you can use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY to add a sharing group to one or more ordered balance groups. See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Deleting a Sharing Group from an Ordered Balance Group

To delete a sharing group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

Caution:

The element ID for each sharing group in the /ordered_balgrp object is unique. If you use an incorrect element ID for the sharing group you want to delete, this opcode deletes the wrong sharing group.

  1. Deletes the sharing group objects specified in PIN_FLD_ORDERED_BALGROUPS array from the /ordered_balgrp object.

    Note:

    If the action is Delete but the input flist does not contain a PIN_FLD_ORDERED_BALGROUPS array, the /ordered_balgrp object is deleted. See "Deleting an Ordered Balance Group".

  2. Generates an /event/billing/ordered_balgrp/modify event to record the object modification.

Customizing the Order in Which to Apply Sharing Groups

Use the PCM_OP_SUBSCRIPTION_POL_ORDERED_BALGRP_PRIORITY policy opcode to customize the order in which BRM applies a member's sharing groups. By default, the policy opcode does nothing and returns the same output as input.

This policy opcode is called by PCM_OP_SUBSCRIPTION_ORDERED_BALGRP.

Deleting an Ordered Balance Group

To delete an ordered balance group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

  1. Deletes the /ordered_balgrp object specified in the input flist.

  2. Generates an /event/billing/ordered_balgrp/delete event to record the object deletion.

Creating and Modifying Multiple Ordered Balance Groups Simultaneously

You can add a sharing group to multiple ordered balance groups simultaneously. To do so, use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY.

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY creates one or more ordered balance groups (/ordered_balgrp objects) for an account or service.

You can also use this opcode to modify the priority of the sharing groups included in one or more existing ordered balance groups. For discount sharing groups, charge sharing groups, and product sharing groups, the rank controls the order in which the group's balances are impacted by events. For profile sharing groups, the rank is not significant.

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY takes as input the POID of the sharing group, an array of one or more members, and a field indicating whether to add the sharing group to the beginning or end of the appropriate segment in the ordered balance group list.

If a service identified in the PIN_FLD_MEMBERS array specifies a type-only service, such as GSM, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY creates or modifies /ordered_balgrp objects for all instances for that service type. However, it does not create or modify /ordered_balgrp objects for any of the subclass instances. For example, if the input flist specifies the GSM service type, the opcode creates or modifies /ordered_balgrp objects for all /service/telco/gsm instances. However, it does not create or modify /ordered_balgrp objects for any of the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so on.

If successful, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY returns the POID of the sharing group and an array of the events that record the action taken for each ordered balance group in the input flist.

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY fails in the following cases:

  • When the PIN_FLD_MEMBERS array contains more than one instance of an ordered balance group.

  • When the sharing group (PIN_FLD_POID) is already included in some existing /ordered_balgrp objects in the PIN_FLD_MEMBERS array.

To create or modify ordered balance groups, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY does the following:

  1. Verifies that the input flist contains a PIN_FLD_ORDERED_BALGROUPS array with at least one member.

  2. Selects a member in the PIN_FLD_MEMBERS array and determines whether the database already contains an /ordered_balgrp object for that member.

    If not, it calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to create the object. See "Creating an Ordered Balance Group".

  3. Calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to modify the /ordered_balgrp object so that it includes the new sharing group.

    See "Adding a Sharing Group to an Ordered Balance Group".

  4. Repeats steps 2 through 3 for each remaining /ordered_balgrp in the PIN_FLD_MEMBERS array.

Adding and Removing Members Automatically to Sharing Groups

Caution:

Do not call these opcodes directly. Call these opcodes only through the BRM event notification feature. See the following:

BRM uses the following AMS opcodes to manage automated sharing groups:

Adding Members to Newly Created Sharing Groups Automatically

Caution:

Do not call this opcode directly. This opcode should be called through the event notification feature only.

The PCM_OP_MONITOR_SETUP_MEMBERS opcode automatically adds members to a balance monitor group, product sharing group, or discount sharing group when it is first created. This opcode is triggered by the following events:

  • /event/group/sharing/monitor/create

  • /event/group/sharing/products/create

  • /event/group/sharing/discounts/create

PCM_OP_MONITOR_SETUP_MEMBERS is a wrapper opcode that, according to the group type, calls other standard PCM_OP_MONITOR_* opcodes to:

  • Find and add members to the appropriate sharing group (/group/sharing/monitor, /group/sharing/products, or /group/sharing/discounts object).

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

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

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

Adding Members to Hierarchy-Type Balance Monitors

Use the PCM_OP_MONITOR_PROCESS_HIERARCHY_MONITORS opcode to add members to hierarchy-type balance monitors. 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.

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

Adding Members to Payment Responsibility-Type Balance 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).

  2. Searches for all /billinfo objects that have PIN_FLD_PARENT_BILLINFO_OBJ as the current bill unit.

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

  4. Adds the following members to the balance monitor:

    • The parent account and its services

    • All nonpaying child accounts and their services.

    See "Adding Members to Hierarchy-Type Sharing Groups Automatically".

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

    See "Adding a Sharing Group to an Ordered Balance Group".

Adding Members to Hierarchy-Type Sharing Groups Automatically

Caution:

Do not call this opcode directly. This opcode should be called through the event notification feature only.

The PCM_OP_MONITOR_ACCOUNT_HIERARCHY opcode finds and adds the following members to hierarchy-type product sharing groups and discount sharing groups:

  • The parent account and its subscriptions

  • All paying child accounts and their subscriptions

  • All nonpaying child accounts and their subscriptions

PCM_OP_MONITOR_ACCOUNT_HIERARCHY also adds members to hierarchy-type balance monitors when an account hierarchy changes, such as when:

  • 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

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 sharing groups associated with the parent account.

  2. Adds the account or service to the sharing group (/group/sharing/monitor, /group/sharing/products, or /group/sharing/discounts objects).

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

  4. (For Balance Monitor Groups Only) Adds the account or service balance to the monitored balance (/balance_group/monitor objects).

Adding Members to Paying Responsibility-Type Sharing Groups Automatically

Caution:

Do not call this opcode directly. This opcode should be called through the event notification feature only.

The PCM_OP_MONITOR_BILLING_HIERARCHY opcode adds members to payment responsibility-type sharing groups, including payment responsible product sharing groups (PR_PSG), payment responsible discount sharing groups (PR_DSG), and payment responsible real-time credit enforcement groups (PR_RTCE).

The opcode adds members to sharing groups when changes occur in an account hierarchy, such as when:

  • A nonpaying child account is added to an 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

  • The credit enforcement changes

This opcode is triggered by the following events:

  • /event/notification/service/pre_purchase

  • /event/customer/billinfo/modify

  • /event/notification/bal_grp/modify

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 payment responsibility-type sharing groups associated with the parent account.

  2. Adds the account or service to the group (/group/sharing/products, /group/sharing/monitor, or /group/sharing/discounts object).

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

  4. (Balance Monitor Groups Only) Adds the account or service balance to the balance monitor (/balance_group/monitor object).

Updating Subscription-Type Monitors Automatically

Note:

Do not call this opcode directly. This opcode should be called through the event notification feature only.

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.

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 Balance Monitor Groups

Note:

Do not call this opcode directly. This opcode should be called through the event notification feature only.

Use the PCM_OP_MONITOR_HIERARCHY_CLEANUP opcode to remove members from balance monitor groups 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

  • The credit enforcement changes

This opcode supports hierarchy credit exposure monitor groups (H_CE), payment responsible real-time credit enforcement monitor groups (PR_RTCE), subscription credit exposure monitor groups (SUB_CE), and payment responsibility credit exposure monitor groups (PR_CE).

This opcode is triggered by the following events:

  • /event/customer/billinfo/modify

  • /event/group/member

  • /event/notification/bal_grp/modify

Removing Members from Sharing Groups

Use the PCM_OP_BILL_GROUP_REMOVE_PAYING_MEMBERS opcode to remove all members from a sharing group when its owner is removed.

This opcode supports only hierarchy product sharing groups (H_PSG) and hierarchy discount sharing groups (H_DSG).

PCM_OP_BILL_GROUP_REMOVE_PAYING_MEMBERS takes as input the /account POID of the group's owner and then does the following:

  1. Reads the /group/sharing/products or /group/sharing/discounts object to verify that its PIN_FLD_TYPE_STR field is set to H_PSG or H_DSG. If the field has another value or is missing, the opcode exits.

  2. For each member in the group, calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to delete the sharing group(/group/sharing/products or /group/sharing/discounts object) from the member's ordered balance group list (/ordered_balgrp object).

  3. Deletes the sharing group (/group/sharing/products or /group/sharing/discounts object).

  4. Generates an /event/group/sharing/products/delete or /event/group/sharing/discounts/delete event to record the deletion.

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

PCM_OP_BAL_APPLY_MONITOR_IMPACTS performs the following actions:

  1. Updates the specified /balance_group/monitor object.

  2. Compares the monitored balance in /balance_group/monitor with the credit limit and threshold values stored in the /config/credit_profile object.

  3. If a credit limit or threshold has been breached, generates one of these 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

    Note:

    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.

Table 13-2 lists the fields in the notification events.

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

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%

Managing Balance Monitors

To manage balance monitors (/balance_group/monitor objects), BRM uses the following opcodes:

Creating and Updating Balance Monitors

Use PCM_OP_CUST_SET_BAL_GRP to create or update a balance monitor (/balance_group/monitor object). PCM_OP_CUST_SET_BAL_GRP is a wrapper opcode that performs all necessary tasks to set up the balance monitor and create a link to the customer account.

PCM_OP_CUST_SET_BAL_GRP is called by the PCM_OP_CUST_COMMIT_CUSTOMER opcode during the account creation process, and by the PCM_OP_CUST_MODIFY_CUSTOMER opcode during the account modification process.

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

  • Whether to ignore the account's credit limit

    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.

PCM_OP_CUST_SET_BAL_GRP does the following:

  1. Verifies that balance monitoring is enabled and that, in the PIN_FLD_BAL_INFO input flist array, PIN_FLD_POID is set to a type-only POID for /balance_group/monitor.

  2. Checks the value of the PIN_FLD_TYPE_STR input flist field in the PIN_FLD_BAL_INFO array:

    • If set to PR_RTCE, the opcode creates or updates the balance monitor group (/group/sharing/monitor object).

    • If set to PR_CE or H_CE, the opcode publishes the balance monitor impacts to the monitor queue (/monitor_queue object).

Deactivating Balance Monitors

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.

Managing Balance Groups

To manage balance groups, BRM uses the following opcodes:

Creating Balance Groups

You create balance groups when you create product offerings in PDC or Pricing Center. To create a balance group, BRM uses PCM_OP_CUST_SET_BAL_GRP. This is a wrapper opcode that performs all necessary tasks to set up the /balance_group object and create a link to the customer account.

PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_SET_BAL_GRP when creating a customer account.

PCM_OP_CUST_MODIFY_CUSTOMER calls PCM_OP_CUST_SET_BAL_GRP when modifying customer account information.

If the PIN_FLD_SERVICE_OBJ field in the input flist has a NULL value, PCM_OP_CUST_SET_BAL_GRP creates a balance group associated with the account. If the PIN_FLD_SERVICE_OBJ field specifies a service object POID, a balance group is created and associated with the service.

PCM_OP_CUST_SET_BAL_GRP calls the following opcodes:

  • PCM_OP_BILL_SET_LIMIT_AND_CR to set the credit limit in the balance group.

  • PCM_OP_CUST_CREATE_BAL_GRP to create the /balance_group object.

  • PCM_OP_CUST_MODIFY_BAL_GRP to modify an existing /balance_group object.

    Based on which field PCM_OP_CUST_MODIFY_BAL_GRP is modifying, the following fields are either mandatory or optional:

    • PIN_FLD_NAME

    • PIN_FLD_BILLINFO_OBJ

    While modifying the balance group, PCM_OP_CUST_SET_BAL_GRP checks if there are any pending bill items. If there are pending bill items and if the billing information has changed, PCM_OP_CUST_SET_BAL_GRP changes the billing information with the new billing information.

Customizing the Default Balance Group of a Bill Unit

In general, BRM applies balance impacts of events to the balance group of the service for which the event was generated. However, some events are not generated for any service. For example, bill adjustment and dispute, payment, payment incentive, and payment fee events are generated for a specific bill unit. In such instances, BRM applies the balance impact of the event to the default balance group of the bill unit and assigns the event to an item belonging to the default service of the default balance group.

BRM chooses a random balance group to be the default for new bill units during account creation and account maintenance.

To create a custom algorithm to select the default balance group of a bill unit, use PCM_OP_BAL_POL_GET_BAL_GRP_AND_SVC. You can also use this opcode to select the default service for the default balance group.

This opcode is not called by any opcode. This opcode is an empty hook.

BRM selects a default service using the same algorithm for selecting the default balance group. It selects the service object in the default balance group with the earliest create time (PIN_FLD_CREATED_T). If more than one service object is selected, the service object with the smallest Portal Object ID (POID) is selected as the default service of the default balance group.

Note:

By overriding the BRM algorithm, you change the system behavior that could impact other functionality. For example, if you choose to use only the object creation time or the object POID as the selection criterion, multiple balance group objects might qualify. You should have a good understanding of the default implementation before you customize this opcode.

Moving a Balance Group from One Bill Unit to Another

To move a balance group from one bill unit to another in the same account, BRM uses PCM_OP_CUST_MODIFY_CUSTOMER.

Important:

  • You cannot move an account default balance group to a different bill unit.

  • You should never move a balance group to a bill unit in a different account. To have a different account be responsible for the charges in a balance group, you must create a bill unit hierarchy that includes the appropriate bill units from both accounts. See "Setting Up Sharing Relationships among Bill Units".

You cannot move a balance group to another bill unit if the balance group's bill unit has unallocated payments or adjustments, open refunds, or unresolved disputes. All disputes must be settled, refunds paid, and payments and adjustments allocated before the balance group can be moved.

A bill unit must have at least one balance group. When a bill unit has only one balance group and that balance group is moved to another bill unit, PCM_OP_CUST_MODIFY_CUSTOMER automatically creates a new balance group not associated with any service for the bill unit from which the balance group was moved.

Deleting a Balance Group

To delete a balance group, use PCM_OP_CUST_DELETE_BAL_GRP.

The POID of the object is checked to ensure that the object can be deleted and that the user has permission to delete the object.

Modifying Sub-balances

Sub-balances are modified when balances are granted or consumed. BRM uses the following opcodes to modify sub-balances. Specify the /balance_group object that contains the sub-balance to modify on the input flist:

  • PCM_OP_BAL_CHANGE_VALIDITY changes a sub-balance validity period.

    For more information, see "Modifying the Sub-balance Validity Period".

  • PCM_OP_BILL_DEBIT debits or credits a noncurrency sub-balance.

  • PCM_OP_AR_ACCOUNT_ADJUSTMENT debits or credits a currency sub-balance.

  • PCM_OP_BILL_TRANSFER_BALANCE transfers a positive balance from one /balance_group. The source and destination balance groups can be in different accounts.

  • PCM_OP_BILL_SET_LIMIT_AND_CR sets the credit limit for currency and noncurrency sub-balances.

Modifying the Sub-balance Validity Period

Sub-balance validity periods define when a granted balance is available for consumption. PCM_OP_BAL_CHANGE_VALIDITY updates the valid dates for sub-balances in /balance_group objects.

To change the validity period of balances, specify the following fields in the PIN_FLD_SUB_BALANCES array on the input flist:

  • If you are changing the validity period of more than one sub-balance:

    • Specify the balance element ID in PIN_FLD_RESOURCE_ID.

    • Specify the sub-balance array index in PIN_FLD_ELEMENT_ID.

  • If you are setting fixed dates:

    • Specify the new start time in PIN_FLD_VALID_FROM.

    • Specify the new end time in PIN_FLD_VALID_TO.

Converting an Account Hierarchy to Wholesale Billing

Use the PCM_OP_CUST_CONVERT_WHOLESALE_HIERARCHY opcode to convert existing individual account hierarchies to use wholesale billing. See "Converting Existing Bill Unit Hierarchies to Wholesale Billing" for more information about the conversion.

You set the paying parent bill unit by providing the information in the input flist.

The PCM_OP_CUST_CONVERT_WHOLESALE_HIERARCHY opcode does the following:

  1. Validates the mandatory parameters in the input flist.

  2. Checks for the wholesale configuration, either system-wide or through the business profile configuration.

  3. Checks the PARENT_FLAG for the flag indicating wholesale conversion.

  4. Checks to ensure that the parent account does not have multiple parent bill units.

  5. Calls a stored procedure that does the following:

    1. Finds all the billable item types for the subordinate accounts and creates a corresponding item at the parent level if necessary.

    2. For each item type, gets the POID of the parent-level item and update that value in the PIN_FLD_AR_ITEM_OBJ of the subordinate accounts.

  6. Calls the opcode PCM_OP_BILL_UPDATE_JOURNAL with a new flag value PIN_BILL_PROCESS_ONLY_CHILD_JOURNALS. This finds the journals for the subordinate accounts for the current bill cycle, rolls them up into the parent account, and deletes the journals from the subordinate accounts.

Note:

The conversion steps will only consider the current cycle. This feature is not supported for items that have already been billed or AR actions that have already been taken.

When an event-level dispute is completed before the conversion to wholesale billing, and settlement is completed after the conversion to wholesale billing, then the /tmp_ar_item_to_roll_up item will not be generated for the settlement. Instead, an item transfer will be done to transfer the settlement amount to the corresponding billable item.