4 Managing Resource Sharing Groups

This chapter describes how to create and manage charge sharing and discount sharing groups in your Oracle Communications Billing and Revenue Management (BRM) system.

For information about different types of groups, see "About Account Groups".

About Resource Sharing Groups

A resource sharing group consists of an owner and one or more members who share resources. A resource sharing group can be one of the following types:

• Discount sharing group. In a discount sharing group, the owner shares its discounts or resources with the members, as shown in Figure 4-1:

Figure 4-1 Discount Sharing Group

Description of ''Figure 4-1 Discount Sharing Group''

For more information, see "About Discount Sharing Groups".

• Charge sharing group. In a charge sharing group, the owner assumes charges that are incurred by the members, as shown in Figure 4-2:

Figure 4-2 Charge Sharing Group

Description of ''Figure 4-2 Charge Sharing Group''

For more information, see "About Charge Sharing Groups".

You can use Customer Center to set up discount and charge sharing groups, or you can customize a third-party client application to set up resource sharing. For information on using Customer Center to create and manage resource sharing groups, see the Customer Center Help. For information on customizing resource sharing, see "Managing Resource Sharing Groups".

Working with Complex Resource Sharing Groups

Networks of resource sharing groups can be complex. An owner can have more than one resource sharing group, and a member can belong to more than one resource sharing group, as shown in Figure 4-3:

Figure 4-3 Complex Resource Sharing Groups

Description of ''Figure 4-3 Complex Resource Sharing Groups''

In this example, Mom owns two charge sharing groups: one for GSM services and one for email services. She assumes charges for all her children; 100% of GSM charges for Louise and Dave, 50% of email charges for Paul and Anika, and both GSM and email charges for her youngest son, Tony. Dad owns a discount sharing group: he shares a 10% discount on GSM charges with his son Tony and brother Jessie. The members have the following benefits:

• When Paul and Anika use email, Mom assumes part of their charges. They have no discounts, shared or owned, so Mom pays 50% of their monthly email charges and they pay the remaining 50%.

• When Louise and Dave use GSM services, Mom assumes their charges. They have no discounts, so Mom pays 100% of their monthly GSM charges.

• When Jessie uses GSM services, he receives a 10% discount from Dad. Jessie is not a member of any charge sharing groups, so he pays the remaining 90% of his GSM charges.

• When Tony uses email, Mom assumes part of his charges. He does not have any email discounts, so Mom pays 50% of his monthly email charges and he pays the remaining 50%.

• When Tony uses GSM services, he receives a 10% discount from Dad. This discount is applied before the charges are applied. Because Tony is a member of charge sharing group A, Mom pays the remaining 90% of his GSM charges.

In more complicated networks, an owner of a resource sharing group can also be a member of another resource sharing group. For example, Mom owns a charge sharing group that assumes email charges for Paul, Anika, and Tony. Mom, in turn, is a member of Grandma's charge sharing group, which also assumes email charges for its members. In this case, Grandma pays the email charges for Mom. In addition, she inherits the email charges for Paul, Anika, and Tony as a result of Mom's charge sharing group.

Important:

When setting up resource sharing groups, you should avoid circular relationships. See "Creating Resource Sharing Groups".

About Discount Sharing Groups

Important:

Subscriber Groups (discount sharing groups) are dependent upon the Advanced Discounting Manager (ADM), an optional feature that requires a separate license.

Discount sharing occurs when an account or service shares its discounts with other accounts' services. The account that shares its discounts is the owner of a discount sharing group. Within the owner's account, one of the balance groups serves as the owning balance group. The owning balance group is determined based on whether the discount sharing group owner is the account or a service in the account:

• If the group owner is the account, the owning balance group is the account's default balance group, and all discounts purchased by the account are shared.

• If the group owner is a service in the account, the owning balance group is the associated service-level balance group, and only the discounts for that service are shared.

When a discount sharing group is created, a discount sharing group object (/group/sharing/discounts) is added to the database. This object contains the owner account or service, the list of discounts that are shared by the owner, and the list of members. The members are the services that use the shared discounts.

When the discount sharing group owner is a service, its service type must match the type of service to which the shared discounts apply.

When events are generated as a result of member activity, discounts belonging to the sharing group owner are typically applied first, followed by any discounts belonging to the member account. After discounting, any remaining balance impact is applied to the member account unless the account also participates in charge sharing.

Note:

You can change the order in which discounts are consumed so that discounts belonging to the member are used before shared discounts.

For members to receive discounts from the owner, the member's ordered balance group must include a reference to the discount sharing group. This reference is created when the member joins the group. For more information, see "How Discounts and Charges Are Applied".

To set up a discount sharing, see "Setting Up Discount Sharing" in BRM Configuring Pipeline Rating and Discounting.

To create a discount sharing group, see "Creating Resource Sharing Groups".

How Account Status Changes Affect Discount Sharing Groups

Changing the status of a discount sharing group's owner account changes the status of all its shared discounts. When the owner account status is changed to inactive or closed, members stop benefiting from the discount sharing group. Members cannot receive any shared currency or percentage discounts. Also, any new events generated by the members impact resources of the member's balance groups only; they can no longer take shared resources from the owner's account.

The way that BRM treats the discount sharing group depends on whether the owner account is deactivated or closed:

• Owner account is deactivated: The status of all the group's shared discounts are changed to inactive. Member services can begin consuming resources from the group's shared pool again as soon as the owner's account is reactivated.

• Owner account is closed: All of the group's shared discounts are removed from the account, and the shared discounts are removed from the discount sharing group.

  Note:

  If keep_cancelled_products_or_discounts is set to 1 in the Connection Manager (CM) pin.conf file, the shared discounts are not removed from the discount sharing group. Instead, their status is set to canceled. For information about deleting canceled discounts, see "Specifying to Delete Canceled Discounts" in BRM Managing Customers.

How Group Owner Changes Affect Discount Sharing Groups

If you use a third-party client application, you can customize the application to enable a customer service representative (CSR) to change the owner of a discount sharing group. For information on how to implement this, see "Changing the Owner of a Discount Sharing Group".

Note:

Customer Center does not support changing group owners.

When the owner of a discount sharing group changes, the discounts shared by the previous owner are deleted from the group, and discounts shared by the new owner are added.

Member-generated events, including delayed events, that occur after a group owner is changed impact the new owner's resource balances.

Members and Discount Sharing Groups

When you set up a discount sharing group, the members of the group must be services (the service-level balance groups). Account-level balance groups can only be members in balance monitoring groups (see "About Balance Monitoring").

If the owner of a shared discount is a service, the discount sharing group member service is typically the same service type as, or a subclass of, the discount owner service. For example, if the discount sharing group owner is /service/telco, the discount sharing group member might be /service/telco/gsm. This parent and subclass relationship is the standard way you set up subscription services to offer a discount based on the total usage of all subscription services in an account group.

If the owner of a shared discount is a service, Customer Center requires that the owner and member services be of the same type. You can specify different service types for the owner and members by implementing the relevant subscription opcodes in your custom code (see "Managing Resource Sharing Groups"). However, if the owner and member services are different types, the member service must match one of the shared discount's permitted service types (specified in the PIN_FLD_PERMITTEDS array in the /discount object).

If the owner and a member of the discount sharing group have different service types, to apply the discount to the member service, the member's usage event type must match the event type to which the shared discount applies.

For example, you use Pricing Center to set up a subscription discount that applies to /service/telco usage. In the Discount Attributes dialog box, you map the discount model to the monthly cycle forward event. You then create a discount sharing group in which you share the telco discount that you created. You add an account to the discount sharing group and specify the account's /service/telephony service as the member. In this case, the subscription discount is applied to the member account only when the member account generates a monthly cycle forward event for its telephony service.

When you set up a discount sharing group, you can specify that the member service be a service type or a service instance:

• Specify a service type as the member: When you specify a service type (for example, GSM) as a member, the events generated by all service instances within that service type are considered for discount sharing. Adding members by service type is appropriate when:

  • You are adding multiple member accounts to the group and you want them all to take advantage of discounts for a service type (for example, an aunt who wants to share her GSM discounts with all her nieces and nephews). In this case, each niece and nephew has a different service instance, so instead of specifying each service instance individually, you specify the member accounts and the service type. This captures all of the nieces' and nephews' service instances under the umbrella of the GSM service type.

  • You want a member account that has not yet purchased a service of that type to be automatically eligible for participation in discount sharing if the member buys the service in the future. With future sharing, even though a member becomes automatically eligible, you must track the member's purchases and, when the service is purchased, manually intervene to join discount sharing for the new service instance.

    For information about how future services work in Customer Center, see the Customer Center Help.

• Specify a service instance as the member: When you specify a service instance (for example, an employee's work phone) as a member, only the events generated by that instance are eligible for discounting. Specify membership using a specific service instance to exclude other services of that type from discount sharing.

  For example, John's account includes work email ([e-mail]) and home email ([e-mail]). John's employer wants to share a 10% discount for monthly fees incurred only by work email. Because John's account has both home and work services, you designate the service instance for [e-mail] as the member to prevent discount usage by [e-mail].

Currency Requirements of Discount Sharing Groups

The discount sharing group's owner account and member accounts must use the same currency. If the accounts use two currencies, they must use the same primary currency.

Billing for Discount Sharing Groups

A discount sharing group's owner account and member accounts can have different accounting and billing cycles. Member-generated events that qualify for discounts always consume the available resources from the discount sharing group's shared resource pool.

In the example illustrated in Figure 4-4, the owner's accounting and billing cycles begin on the 1st of the month, and the member's accounting and billing cycles begin on the 15th of the month. The owner receives 100 free monthly minutes that are shared.

Figure 4-4 Discount Sharing between Accounts with Different Accounting Cycles

Description of ''Figure 4-4 Discount Sharing between Accounts with Different Accounting Cycles''

When a member generates an event that lasts 30 minutes on January 20, it consumes the available 20 free minutes from the shared resource pool. The member's account receives a balance impact for the remaining 10 minutes of the event.

When another member generates an event that lasts 15 minutes on February 20, there are no available free resources in the shared pool to consume, and the member account receives a balance impact for the entire 15 minutes.

Configuring the Start and End Times for Discount Sharing

By default, discount sharing start and end times are based on the date of the next billing cycle. Therefore:

• When you create a discount sharing group, add a discount to an existing group, or add a member to the group, discount sharing starts at the beginning of the owner's next billing cycle.

• When you delete a discount sharing group, delete a discount from a group, or remove a member from the group, discount sharing is effective up to the end of the owner's billing cycle.

For example, if you create a discount sharing group on January 15 but the next billing cycle does not start until February 1, the members of the group do not receive any of the owner's shared discounts until February 1, as shown in Figure 4-5:

Figure 4-5 Effective Date of Discount Sharing Group Created Mid-Cycle

Description of ''Figure 4-5 Effective Date of Discount Sharing Group Created Mid-Cycle''

Conversely, if you delete a discount sharing group on January 15 but the next billing cycle does not start until February 1, the members of the group receive shared discounts based on the entire month of January, not just the first 15 days.

You can configure BRM to start and end discount sharing as soon as the group is created or deleted, a discount is added or deleted, or a member is added or removed. To do so, you modify an entry in the Connection Manager (CM) pin.conf file.

When you configure discount sharing this way, BRM prorates the shared discounts according to where the start or end date falls within the billing cycle. For example, if you delete a discount sharing group on April 15 and the owner's billing cycle starts on the first day of each month, the members receive 50% of the discount, equivalent to the portion of the month in which discount sharing existed.

To change the discount sharing start time:

1. Open the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf).

2. Change the discount sharing startup from the beginning of the next billing cycle to the time when the discount sharing group is created or a member is added by changing the 0 to 1 in the following line:

   -fm_subscription propagate_discount 1
     
   

3. Stop and restart the CM and, if necessary, your client application.

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

Creating a Discount Sharing Group for Accounts That Use a Custom Payment Method

If accounts use a custom payment method, you must edit the Customer Center CustomizedResources.properties file if you want accounts to own a discount sharing group.

Add the following entry to the Customer Center CustomizedResources.properties file:

object.payinfo.payinfo_subclass_name.mapping=payment_type_name
  

For example, if the payment type is named Custom Direct Debit and the payment information subclass is /payinfo/ddebit, the properties file entry is:

object.payinfo.ddebit.mapping=Custom Direct Debit

About Charge Sharing Groups

Important:

Subscriber Groups (charge sharing groups) is an optional feature that requires a separate license.

Charge sharing enables a customer to sponsor the charges of other accounts or services in the system. For example, it enables a company to pay for all of its employees' GSM telephony services, or a parent to pay for his child's SMS and email services.

You set up charge sharing by creating a charge sharing group, which consists of the following:

• Charge sharing group owner: The account or service responsible for all or a portion of the charges incurred by the charge sharing group members.

• Charge sharing group members: The accounts and services that the owner sponsors.

• Chargeshare: The chargeshare specifies how and when to apply charges. It includes a usage map that links particular event types to chargeshare models. Chargeshare models determine whether events qualify for charge sharing and apply rules to calculate charge sharing amounts.

When a member incurs charges sponsored by the owner, the charges are applied to the owner's balance group first. Any charges that remain afterward impact the member's balance group.

Information about charge sharing groups is stored in /group/sharing/charges objects in the BRM database.

To set up charge sharing, see "Setting Up Charge Sharing" in BRM Configuring Pipeline Rating and Discounting.

To create a charge sharing group, see "Creating Resource Sharing Groups".

About Charge Sharing Group Owners

The account that sponsors the charges is the owner of a charge sharing group. Within the owner's account, one of the balance groups serves as the owning balance group. The owning balance group is the one that receives the balance impact of any shared charges incurred by the members.

The owning balance group is determined based on whether the charge sharing group owner is the account or a service in the account:

• If the group owner is the account, the owning balance group is the account's default balance group.

• If the group owner is a service in the account, the owning balance group is the associated service-level balance group.

About Serviceless Accounts as Charge Sharing Owners

Charge sharing group owners can be accounts that have no services. This enables you to bypass purchasing specific services for corporate accounts that are used exclusively to pool employee charges. For example, you can create a corporate account that assumes telephone, email, and IP charges for all employees in the marketing group. But, you do not have to purchase GSM, email, or IP services for that corporate account. If you set up a serviceless account as a charge sharing group owner, BRM applies the member charges to that account's default balance group.

Pipeline Manager uses the create, modify, and delete sharing group events to determine the owner of the sharing group. If the owner is an account without services, the PIN_FLD_SERVICE_OBJ value is NULL. If the owner is a service, the PIN_FLD_SERVICE_OBJ value is the POID of the service.

To create a charge sharing owner that is a serviceless account, perform the following:

1. Enable Pipeline Manager to accept serviceless accounts by setting the DAT_AccountBatch LoadAccountForSharingOnly registry entry to True. This prevents the pipeline from rejecting serviceless accounts if they are owners of resource sharing groups. By default, this entry is set to False.

   For more information about DAT_AccountBatch, see "DAT_AccountBatch" in BRM Configuring Pipeline Rating and Discounting.

2. Create a serviceless account. First use Pricing Center to create a plan that has no deals. Then, purchase the plan when you create the account in Customer Center. When you create a charge sharing group for this account, the result is an account-level charge sharing group not associated with any specific services.

How Owner Account Status Changes Affect Charge Sharing

By default, changing the status of a charge sharing group's owner account changes the status of all its shared charges. When the owner account is deactivated or closed, members stop benefiting from the charge sharing group. The owner no longer assumes any of the charges incurred by the members. Any new events generated by the members are charged to the member's balance groups only.

The way that BRM treats the charge sharing group depends on whether the owner account is deactivated or closed:

• Owner account is deactivated: All of the group's sponsored charges are suspended, and no new member charges are added to the owning balance group. Member services can begin benefiting from charge sharing again as soon as the owner's account is reactivated.

• Owner account is closed: All of the group's shared charges are suspended, and no new member charges are added to the owning balance group. The shared charges are removed from the charge sharing group.

  Note:

  If keep_cancelled_products_or_discounts is set to 1 in the Connection Manager (CM) pin.conf file, the shared charges are not removed from the charge sharing group. Instead, their status is set to canceled. For information about deleting canceled discounts, see "Specifying to Delete Canceled Discounts" in BRM Managing Customers.

About Changing Charge Sharing Group Owners

If you use a third-party client application, you can customize the application to enable a CSR to change the owner of a charge sharing group. For information on how to implement this, see "Changing the Owner of a Charge Sharing Group".

Note:

Customer Center does not support changing group owners.

When the owner of a charge sharing group changes, the charges that were sponsored by the previous owner are deleted from the group, and charges sponsored by the new owner are added.

Member-generated events, including delayed events, that occur after a group owner is changed impact the new owner's resource balances.

About Charge Sharing Group Members

When you set up a charge sharing group, the members of the group must be services (the service-level balance groups). Account-level balance groups can be members only in balance monitoring groups (see "About Balance Monitoring").

If the owner of a charge sharing group is a service, the group member service is typically the same service type as, or a subclass of, the charge share owner service. If the owner and a member of the charge sharing group have different service types, to share charges, the member's usage event type must match the event type to which the charge share applies.

Note:

Customer Center requires that the owner and member services be of the same type. You can specify different service types for the owner and members by implementing the relevant subscription opcodes in your custom code. See "Managing Resource Sharing Groups".

When you set up a charge sharing group and specify the member services, you can:

• Specify a service type for a group of accounts as members: When you specify multiple account instances and a service type (for example, Account 1, Account 2, and GSM) as members, only the service instances for each account are considered members. Adding members by service type is appropriate when:

  • You are adding multiple member accounts to the group and you want them all to take advantage of charge sharing for a service type (for example, an aunt who wants to pay the GSM charges for all of her nieces and nephews). In this case, each niece and nephew has a different service instance, so instead of specifying each service instance individually, you specify the member accounts and the service type. This captures all of the nieces' and nephews' service instances under the umbrella of the GSM service type.

  • You want a member account that has not yet purchased a service of that type to be automatically eligible for participation in charge sharing if the member buys the service in the future. With future sharing, even though a member becomes automatically eligible, you must track the member's purchases and, when the service is purchased, manually intervene to join charge sharing for the new service instance.

    For information about how future services work in Customer Center, see the Customer Center Help.

• Specify a service instance as the member: When you specify a service instance (for example, an employee's work phone) as a member, only the events generated by that instance are eligible for charge sharing. Specify membership by using a specific service instance to exclude other services of that type from charge sharing.

  For example, John's account includes work email ([e-mail]) and home email ([e-mail]). John's employer wants to pay for monthly fees incurred by work email only. Because John's account has both home and work services, you designate the service instance for [e-mail] as the member to prevent the employer from paying for usage charges from [e-mail].

• Specify all accounts in the system as members: When you specify a type-only account POID as the member, events generated by any account in your system are eligible for charge sharing.

  See "About Global Charge Sharing Groups".

• Specify all services of a specific type as members: When you specify a type-only service POID as the member, events generated for that service type are eligible for charge sharing.

  See "About Global Charge Sharing Groups".

For member charges to be applied to the owner's account, the member's ordered balance group must include a reference to the charge sharing group. This reference is created when the member joins the group. For more information, see "How Discounts and Charges Are Applied".

Note:

This requirement does not apply to global charge sharing groups. See "About Global Charge Sharing Groups".

Currency Requirements for a Charge Sharing Group

The charge sharing group's owner account and member accounts must use the same currency or primary currency.

Note:

The currency requirement does not apply for global charge sharing groups. See "About Global Charge Sharing Groups".

Billing for a Charge Sharing Group

A charge sharing group's owner and member accounts are not required to have the same accounting or billing cycles. Sponsored charges are always applied to the owner account, regardless of when the member-generated events occurred.

In the example illustrated in Figure 4-6, the owner's accounting and billing cycles begin on the 1st of the month, and the member's accounting and billing cycles begin on the 15th. Charge sharing starts on January 10 and ends on February 20, so between those dates, the owner sponsors 50% of all charges incurred by a member.

Figure 4-6 Effective Dates of Charge Sharing Groups Created Mid-Cycle

Description of ''Figure 4-6 Effective Dates of Charge Sharing Groups Created Mid-Cycle''

The member generates an event on January 20 for 30 minutes at $0.10 per minute, for a total cost of $3.00. The owner's account receives a balance impact of $1.50 and the amount appears on the owner's bill on February 1. The member's account receives a balance impact of $1.50, and the amount appears on the member's bill on February 15.

If the member generates an event on February 10 for 10 minutes, the owner is billed $0.50 on March 1 and the member is billed $0.50 on February 15.

The member receives the balance impacts for all charges incurred after February 20.

About Global Charge Sharing Groups

You can create a charge sharing group that includes all accounts in your system or all services of a specific type, such as GSM telephony. This type of charge sharing group is called a global charge sharing group. This enables one account to pay for all or a portion of the charges incurred by anyone in your system.

You specify which events the group owner pays for and how to split charges between the owner and members by creating a chargeshare. For information, see the Pricing Center Help.

For example, you can configure BRM to charge a company for all or a portion of any call to a toll free number or any text message sent to a specified number. For an example of how to set up global charge sharing groups for toll free numbers, see "Global Charge Sharing Configuration Example" in BRM Configuring Pipeline Rating and Discounting.

Global charge sharing groups differ from charge sharing groups in these ways:

• Global charge sharing groups are not listed in a member's ordered balance group. Therefore, the order in which charges are applied to global charge sharing groups is set by the system.

• Members in the global charge sharing group are indicated by a type-only POID.

About the Order in Which Charges Are Applied to Groups

The order in which BRM applies charges to the different types of resource sharing groups is built into the system. BRM automatically applies charges to global charge sharing groups after applying any discounts from discount sharing groups but before applying charges to any charge sharing groups. The order in which BRM applies discounts and charges is shown below:

1. Discount sharing groups as listed in the member's ordered balance group

2. Global charge sharing groups having type-only services

3. Global charge sharing groups having type-only accounts

4. Charge sharing groups as listed in the member's ordered balance group

   Note:

   Only charge sharing groups and discount sharing groups are listed in a member's ordered balance group. Global charge sharing groups are not included in the list.

About Creating Global Charge Sharing Groups

Global charge sharing groups, like charge sharing groups, consist of an owner, members, and the chargeshare that defines when and how to apply charges. However, instead of listing every group member, the global charge sharing group indicates all accounts in the system or all services of a specific type as members by using a type-only POID.

Important:

Charge sharing group members must be either a type-only POID or a list of member POIDs; members cannot include both types.

Any existing account or service in your system is automatically considered a part of the group. Likewise, when you create a new account or service in the system, BRM automatically considers the account or service as part of the global charge sharing group.

To create global charge sharing groups, perform the following:

1. Make sure the global charge sharing search is enabled for real-time rating.

   See "Enabling Global Charge Sharing Searches during Discounting".

2. Use Customer Center or a custom client application to create global charge sharing groups:

   • To create global charge sharing groups by using Customer Center, see the Customer Center Help.

   • To create global charge sharing groups by using a custom client application, see "Using Third-Party Client Applications to Create, Modify, and Delete Global Charge Sharing Groups".

Enabling Global Charge Sharing Searches during Discounting

By default, the global charge sharing search is disabled. You can enable global charge sharing searches by changing the EnableGlobalChargeSharing field in the rating instance of the /config/business_params object from disabled to enabled. You can disable the feature by changing the field back to disabled.

• With this feature enabled, BRM searches for global charge sharing objects during the discounting process.

• With this feature disabled, rating does not search for global charge sharing objects during the discounting process, thereby resulting in better performance.

You modify the /config/business_params object by using the pin_bus_params utility. For information on this utility, see "pin_bus_params" in BRM Developer's Guide.

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 full path as part of the file name.

2. Search the XML file for following line:

   <EnableGlobalChargeSharing>disabled</EnableGlobalChargeSharing> 
     
   

3. Change disabled to enabled:

   Caution:

   BRM uses the XML in this file to overwrite the existing rating 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 rating configuration.

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

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

   pin_bus_params bus_params_rating.xml  
      
   

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

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

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

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

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

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

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

Using Third-Party Client Applications to Create, Modify, and Delete Global Charge Sharing Groups

To set up your third-party client application to manage global charge sharing groups, you must customize it to accept the following information and pass it in the input flist to the Subscription Management FM opcodes:

• Name of the global charge sharing group

• Owner of the group

• Members of the group

• The chargeshare associated with the group

To add all accounts in the system as members, you pass a type-only account POID and a NULL service POID in the input flist's PIN_FLD_MEMBERS array. For example:

0 PIN_FLD_MEMBERS            ARRAY [0] allocated 2, used 2
1   PIN_FLD_ACCOUNT_OBJ       POID [0] 0.0.0.1 /account -1 0
1   PIN_FLD_SERVICE_OBJ       POID [0] 0.0.0.0 /service 0 0
  

To add all services of a specific type in the system as members, you pass a type-only account POID and a type-only service POID in the input flist's PIN_FLD_MEMBERS array. For example:

0 PIN_FLD_MEMBERS            ARRAY [0] allocated 2, used 2
1   PIN_FLD_ACCOUNT_OBJ       POID [0] 0.0.0.1 /account -1 0
1   PIN_FLD_SERVICE_OBJ       POID [0] 0.0.0.1 /service/email -1 0

Note:

In both cases, you pass a type-only account POID in the PIN_FLD_ACCOUNT_OBJ field. The field cannot be NULL.

You pass the information from your client application to the following Subscription Management FM opcodes:

• To create a global charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE.

• To modify a global charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY.

• To delete a global charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE.

  Note:

  For global charge sharing groups, do not call the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode.

For more information about these opcodes, see "Managing Resource Sharing Groups".

About Creating, Deleting, and Modifying Resource Sharing Groups

You create, delete, and modify a charge sharing group in a similar manner to the way you perform these tasks for a discount sharing group.

Creating Resource Sharing Groups

To create a resource sharing group, you specify a group owner account or service, member services, and the list of group owner's resources that will be shared by the members.

• For discount sharing, the list consists of the discount objects purchased by the group owner.

• For charge sharing, the list consists of all the chargeshares in the database.

See "Setting Up Discount Sharing" or "Setting Up Charge Sharing" in BRM Configuring Pipeline Rating and Discounting.

Be aware of the following restrictions:

• Discounts or charges selected for resource sharing must be valid. A valid discount or charge is one that has an active or inactive status and has not expired.

• The owner of a resource sharing group cannot also belong to a member-owned resource sharing group of the same type.

  For example, Anna is the owner of discount sharing group DG1 and wants Sam to be a member. But, Sam is the owner of a different discount sharing group, DG2. Anna can have Sam as a member of DG1 only if she is not a member of DG2.

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

• When adding a service as a member, you can add the service as either a service type or a specific service instance.

  If you add a service type as a member, all instances of that service type become members. However, the subtypes of the service type do not become members. For example, if you specify the GSM service type as a member, all instances of GSM become members, but GSM fax, GSM telephony, and so forth do not.

• All members must have the same primary currency as the owner.

  Note:

  This restriction does not apply to global charge sharing groups.

After you create a resource sharing group, members can join the group. When they join the group, an ordered balance group is created. The ordered balance group determines which resource sharing groups the member can use and the order in which the groups are used. See "How Discounts and Charges Are Applied".

You create resource sharing groups in Customer Center. For more information, see the Customer Center Help.

If you are implementing resource sharing through a third-party client application, see "Creating a Resource Sharing Group".

When creating a discount sharing group, the moment when sharing starts is determined by a pin.conf entry. See "Configuring the Start and End Times for Discount Sharing".

Deleting Resource Sharing Groups

A resource sharing group is deleted when the group's owner account is closed or when the sharing group is deleted by a CSR. When a discount sharing group is deleted, members can no longer use the discounts that had been shared by the owner. When a charge sharing group is deleted, members charges are no longer assumed by the owner.

When a resource sharing group is deleted, BRM also deletes the resource sharing group from each member's ordered balance group; in effect ending the membership. For more information about ordered balance groups, see "How Discounts and Charges Are Applied".

You delete resource sharing groups in Customer Center. For more information, see the Customer Center Help.

If you are implementing resource sharing through a third-party client application, see "Deleting a Resource Sharing Group".

When deleting a discount sharing group, the moment when sharing ends is determined by a pin.conf entry. See "Configuring the Start and End Times for Discount Sharing".

Modifying Resource Sharing Groups

You can modify a resource sharing group in the following ways:

• Delete members from the group.

  When a member is deleted from the group, the member can no longer consume resources from the shared resource pool. Deleting a member removes the member from the group's members list. It also removes the group from the member's ordered balance group list. See "How Discounts and Charges Are Applied".

• Delete shared discounts or sponsored charges.

  When a shared discount is deleted, members can no longer apply that discount and any owner resource pools for that discount cannot be touched by the members. When a shared charge is deleted, the owning balance group no longer receives balance impacts for member-generated events that are part of that charge.

  Deleting a shared discount or charge removes it from the group's discounts or sponsors list. It also removes the group from the members' ordered balance group lists.

• Add members to the group.

  When a member is added to the group, that member can begin benefiting from resource sharing by joining the group. Adding new members updates the group's members list.

  After you add members to the group, they can join the group. When they join the group, an ordered balance group is created and sharing for that member can begin. See "How Discounts and Charges Are Applied".

• Add shared discounts or charges.

  When discounts are added to a discount sharing group, members can begin to use the discounts for the events generated by their accounts. When charges are added to a charge sharing group, the owner account begins to receive the balance impact of those charges from the member services.

  Adding new discounts or charges updates the group's discounts or sponsors list. The discounts must be owned by the group owner, and the charges must be defined as chargeshares in the database. The discounts and charges must have an active or inactive status and have valid dates.

• Change the owner of the resource sharing group.

  When the owner of a discount sharing group changes, members use discounts from the new owner's shared pool rather than from the old owner's pool. When the owner of a charge sharing group changes, the new owner assumes charges generated by the members and the old owner stops assuming the charges.

  Changing the owner assigns a new group owner, deletes the discounts or sponsors list belonging to the previous owner, and creates a new discounts or sponsors list containing the discounts or charges shared by the new owner.

You modify resource sharing groups in Customer Center. For more information, see the Customer Center Help.

Note:

You cannot change the owner of a discount sharing group in Customer Center.

If you are implementing discount sharing through a third-party client application, you customize the application to invoke BRM opcodes. See the following sections:

• Deleting a Resource Sharing Group

• Modifying a Resource Sharing Group

• Changing the Owner of a Resource Sharing Group

When adding or deleting members or discounts in a discount sharing group, the moment when sharing starts and ends is determined by a pin.conf entry. See "Configuring the Start and End Times for Discount Sharing".

How Discounts and Charges Are Applied

An account can purchase discounts, share discounts, and have charges that are sponsored. For events generated by a member service, the shared discounts are used before the sponsored charges are applied to the owning balance group. This way, sponsored charges are applied after usage charges have been discounted. To control the sequence in which shared discounts and charges are applied for member-generated events, BRM maintains an ordered balance group for each member.

About Ordered Balance Groups

Each member of a discount sharing or charge sharing group has an ordered balance group (/ordered_balgrp object). Ordered balance groups are created when members first join resource sharing groups and are updated each time members join new resource sharing groups or leave resource sharing groups.

An ordered balance group contains links to the groups that the member has joined, listed in order by rank. The ordered list determines the sequence in which the group's resource balances are impacted by the member-generated events.

Note:

Ordered balance groups do not include any global charge sharing groups to which the member belongs. For more information, see "About Global Charge Sharing Groups".

The following example, as illustrated in Figure 4-7, shows how BRM applies discounts and charges for a member's ordered balance group that references discount sharing group X1 and charge sharing group X2.

Figure 4-7 BRM Application of Discounts and Charges to Ordered Balance Group

Description of ''Figure 4-7 BRM Application of Discounts and Charges to Ordered Balance Group''

Note:

In this example, the entry indicated by -1 references discounts owned by the member.

As shown in Figure 4-7, when the ordered balance group contains both discount and charge sharing groups, the discount sharing group's resources are used first. This enables discounts to be applied before usage charges are determined for charge sharing. If multiple discount or charge sharing groups are configured, they are applied in the order of their rank.

Also, BRM always references any charges owned by the member after referencing the ordered balance group. That way, members receive charge sharing benefits before having to use their own charges.

The following example, as illustrated in Figure 4-8, shows how a member's ordered balance group is used to impact the resource balances of the resource sharing groups. In this example, Account A is the owner of discount sharing group X1. Account B is the owner of charge sharing group X2. Service A is a member of both X1 and X2. Account A shares a discount that grants 20 free minutes of telephone calls monthly. Account B sponsors 50% of usage charges. Service A has two discounts, one for 30 free minutes monthly and another that discounts 10% of the charges.

Figure 4-8 Ordered Balance Group Impact on Resource Sharing Groups

Description of ''Figure 4-8 Ordered Balance Group Impact on Resource Sharing Groups''

Here, BRM applies shared discounts and charges for events generated by Service A as follows:

1. Service A generates an event for 100 minutes of telephone calls at $0.10 per minute.

   Before any discounts or sponsored charges are applied, Service A owes $10.00.

2. Account A's discounts are consumed first.

   After consuming 20 free minutes, Service A owes $8.00 for 80 minutes of telephone calls at $0.10 per minute.

3. Service A's discounts are consumed next.

   After consuming 30 free minutes, Service A owes $5.00 for 50 minutes of calls at $0.10 per minute. After the 10% usage discount, Service A owes $4.50 for 50 minutes of calls.

4. Account B's charges are consumed last.

   After a 50% of usage sponsored by Account B, Account B owes $2.25 and Service A owes $2.25.

How Discounts Are Applied When a Member Belongs to the Group Owner Account

When a member of a discount sharing group belongs to the discount sharing group owner account, the discount at the account level is applied twice for the member.

For example, Account A is the owner of discount sharing group X. Account A owns Service A and Service A is also a member of the discount sharing group X. Account A shares a discount that grants 20 free minutes. When Service A generates an event for 100 minutes, the event is discounted as follows:

• Service A is granted 20 free minutes as a member of the discount sharing group X.

• Because Service A also belongs to the account and any discount purchased at the account level applies to its services, the account-level discount is applied and Service A is granted an additional 20 free minutes.

Creating, Deleting, and Modifying Ordered Balance Groups

Ordered balance groups are created for a member service that participates in resource sharing. A member account can have multiple ordered balance groups depending on how many services are included in resource sharing groups. For example, if a member account participates in resource sharing for its IP, email, and GSM services, it has ordered balance groups for each of these services.

Creating Ordered Balance Groups

To create an ordered balance group, you specify the discount and charge sharing groups that provide resource pools for the service or account.

You create ordered balance groups in Customer Center when a member first joins resource sharing groups for a service. See the Customer Center Help.

If you are implementing resource sharing through a third-party client application, see "Creating an Ordered Balance Group".

Deleting Ordered Balance Groups

To delete an ordered balance group, you specify the ordered balance group that you want to remove from the database.

You cannot delete an ordered balance group in Customer Center. But, when a member decides to end membership in all resource sharing groups for a service, Customer Center deletes all the groups from the ordered balance group list, leaving only the member's own discounts. See the Customer Center Help.

You can delete an ordered balance group if you are implementing resource sharing through a third-party client application. See "Deleting an Ordered Balance Group".

Modifying Ordered Balance Groups

Modifying an ordered balance group consists of adding or deleting resource sharing groups:

• Adding a resource sharing group: A link to the resource sharing group is added to the ordered balance group list.

• Deleting a resource sharing group: The link to the resource sharing group is removed from the ordered balance group list.

  Important:

  If you add or delete resource sharing groups, you may need to rearrange the ordered balance group list. See "Modifying the Order in Which Resource Sharing Groups Are Used".

You modify ordered balance groups in Customer Center when a member decides to join a resource sharing group or end membership in a resource sharing group. For information on joining a resource sharing group or on ending membership in a resource sharing group, see the Customer Center Help.

If you are implementing resource sharing through a third-party client application, see "Managing Ordered Balance Groups".

Modifying the Order in Which Resource Sharing Groups Are Used

The sequence of the ordered balance group list determines which shared resource pools will be used first. You can change the order of this list to reprioritize resource sharing for a member.

You modify the order of the ordered balance group list in Customer Center when you join resource sharing groups or if a member decides to use one resource sharing group before another. See the Customer Center Help.

If you are implementing resource sharing through a third-party client application, see "Modifying the Order in Which Sharing Is Applied".

Creating or Modifying Multiple Ordered Balance Groups Simultaneously

To create or modify multiple ordered balance groups simultaneously, you specify the discount and charge sharing group that provides the resource pool. You also specify a list of member services you want to have share this resource pool.

You can create or modify multiple ordered balance groups simultaneously in Customer Center provided it is configured to enable automatic ordered balance group creation. By default, an owner creates a group and adds members to the group. Members, in turn, must explicitly join the group. If, instead, you configure Customer Center to automatically add members, the need for members to explicitly join the group is eliminated. See "Sharing Configurator" in BRM Developer's Guide.

If you are implementing resource sharing through a third-party client application, see "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Managing Resource Sharing Groups

There are two types of resource sharing groups; discount sharing groups and charge sharing groups. For general information about discount sharing or charge sharing groups, see "About Resource Sharing Groups".

To manage charge and discount sharing groups, use the following opcodes:

• PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE

  See "Creating a Resource Sharing Group".

• PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY

  See "Modifying a Resource Sharing Group".

• PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE

  See "Deleting a Resource Sharing Group".

• PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT

  See "Changing the Owner of a Resource Sharing Group".

• PCM_OP_SUBSCRIPTION_POL_GET_SPONSORS

  See "Getting a List of Charges Available for Charge Sharing".

• PCM_OP_SUBSCRIPTION_ORDERED_BALGRP

  See "Managing Ordered Balance Groups".

• PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY

  See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Creating a Resource Sharing Group

For general information about discount sharing and charge sharing groups, see "About Resource Sharing Groups".

To create a discount or charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE. Customer Center calls this opcode when you create a sharing group.

The members of a charge sharing group can include individual services, all services of a specific type, or all accounts in the system.

Observe the following guidelines when creating sharing groups:

• Discounts and charges that are shared by the group owner must be valid. A valid discount is one that 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 the resource sharing group must be unique and cannot be used for another resource 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.

If successful, this opcode returns the POID of the resource sharing group object created and the POID of the event generated to record the creation.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE fails in the following cases:

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

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

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

Creating a discount or charge sharing group is the first step toward activating discount or charge sharing for the group. For BRM to apply shared discounts and charges 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, you 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:

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

   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. See "Members and Discount Sharing Groups".

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/billing/group/sharing/discount 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:

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

   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. See "Members and Discount Sharing Groups".

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

4. Generates an /event/billing/group/sharing/charges event to record the creation of the charge sharing group.

Modifying a Resource Sharing Group

For general information about discount sharing or charge sharing groups, see "About Resource Sharing Groups".

To modify a discount or charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY. Customer Center calls this opcode when you modify a resource sharing group and when you add members to a group.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY can perform the following modifications:

• 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 this opcode 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 object in the input flist is not valid.

Adding a member to a discount or charge sharing group is the first step toward activating discount or charge sharing for the new member. For the new member to benefit from shared 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 resource sharing group, the owner cannot be a member of that group.

   • If the PIN_FLD_MEMBERS array is empty, the 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, 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 forth.

   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. See "Members and Discount Sharing Groups".

2. Generates an event to record member changes:

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

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

   Note:

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

2. Generates a /group/sharing/charges/modify event to record the event.

Deleting a Resource Sharing Group

For general information about discount sharing or charge sharing groups, see "About Resource Sharing Groups".

To delete a discount or charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE. You can also use this opcode to delete shared discounts, sponsored charges, and group members.

Customer Center calls this opcode when:

• You delete a resource sharing group.

• You delete members from a group.

• You delete discounts or charges from the resource sharing group.

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/billing/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/billing/group/sharing/charges/delete event to record the deletion.

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, the 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/billing/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, you will delete 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/billing/group/sharing/charges/delete event.

Deleting a Shared Discount from a Discount Sharing Group

To delete a shared discount from the 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, you will delete 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/billing/group/sharing/discounts/delete event to record the deletion.

Deleting a Sponsored Charge from a Charge Sharing Group

To delete a sponsored charge from the 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, you will delete 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/billing/group/sharing/charges/delete event to record the deletion.

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

Changing the Owner of a Resource Sharing Group

For general information about discount sharing or charge sharing groups, see "About Resource Sharing Groups".

To change the owner of a discount or charge sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT. This opcode takes as input:

• PIN_FLD_GROUP_OBJ: The sharing group (/group/sharing/discounts or /group/sharing/charges) whose owner is being changed.

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

• PIN_FLD_PARENT: The new owner. This field identifies the /service object designated as the new owner of the resource sharing group. The /service object can be in the account that currently owns the resource sharing group or it can be in a different account.

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

  Note:

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

• PIN_FLD_BAL_GRP_OBJ: The balance group used to track sharing activities for the new owner.

• PIN_FLD_DISCOUNTS: An array of discounts that the new owner will share with the group members. This field is optional but should be included if the shared discounts for the new owning service are different from those for the current owning service.

  Note:

  Include this array only if you are using the opcode to change the owner of a discount sharing group.

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

PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT fails in the following cases:

• If the new owner that is passed is a member of the resource sharing group.

This opcode can also be used to change the owner of a balance monitor, provided you are changing the owner manually and not through Automated Monitor Setup (AMS). For details on balance monitoring and AMS, see "About Balance Monitoring". For information on changing the owner of a balance monitor, see "Changing the Owner of a Balance Monitor".

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 that:

   • 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 resource 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/discount/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 that:

   • 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 /billinfo objects.

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

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 this opcode to filter or return a subset of /sponsorship objects from the list of all available /sponsorship objects. For example, you can customize the opcode to get a list of the chargeshares that include a particular set of events.

Managing Ordered Balance Groups

For general information about ordered balance groups, see "About Ordered Balance Groups".

To create, modify, or delete an ordered balance group (/ordered_balgrp object) for an account or service, use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP. Customer Center calls this opcode whenever a member joins or leaves a resource sharing group.

Note:

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP lets you create or modify 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 resource sharing group. You can modify an ordered balance group by:

• Adding a resource sharing group.

• Deleting a resource sharing group.

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

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP uses the element IDs in the ORDERED_BALGRPS array to determine the order in which to apply the shared discounts and shared charges. The array has two segments; one for discount sharing groups and one for charge sharing groups. The segment for discount sharing groups is independent of the segment for charge sharing groups; BRM does not intermingle the two groups. Discount sharing groups always precede charge sharing groups within the array.

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

• 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 the resource sharing group objects and their ranks in the /ordered_balgrp object.

After you have created an /ordered_balgrp object, you can modify the sequence of the groups in the ordered balance group list. See "Modifying the Order in Which Sharing Is Applied".

PCM_OP_SUBSCRIPTION_ORDERED_BALGRP fails in the following cases:

• If there is more than one instance of a resource sharing group in the PIN_FLD_ORDERED_BALGROUPS array.

• If the PIN_FLD_ACTION is Create but there is already an /ordered_balgrp object for the account or service.

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 resource sharing group objects specified in the input flist to the /ordered_balgrp object.

   The opcode arranges the sharing groups in the order defined by the element IDs in the input flist. The /group/sharing/discounts objects always come before the /group/sharing/charges objects so that shared discounts are applied before the shared charges impact the owning balance group.

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

You can also use the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY opcode to create one or more ordered balance groups. See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Adding a Resource Sharing Group to an Ordered Balance Group

To add a resource sharing group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

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

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

   Important:

   You can also use the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY opcode to add a resource sharing group to one or more ordered balance groups. See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

Deleting a Resource Sharing Group from an Ordered Balance Group

To delete a resource sharing group, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

Caution:

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

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

   Note:

   If the action is Delete but there is no PIN_FLD_ORDERED_BALGROUPS array in the input flist, 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.

Modifying the Order in Which Sharing Is Applied

To modify the order in which BRM applies shared discounts and shared charges, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP does the following:

1. Replaces the resource sharing group objects in the /ordered_balgrp object with the set of resource sharing group objects specified in the input flist.

   The replacement set of sharing group objects can reference the same resource sharing groups as before, but the element IDs used to establish the order are different.

   Caution:

   When you use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP to re-order the list, it overwrites the /ordered_balgrp object, so you must include all the resource sharing groups in the input flist.

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

You can also use the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY opcode to add a resource sharing group to one or more ordered balance groups.

See "Creating and Modifying Multiple Ordered Balance Groups Simultaneously".

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 create multiple ordered balance groups individually or add a resource sharing group to multiple ordered balance groups simultaneously. To do so, use PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY.

Customer Center calls this opcode to automatically add members to a resource sharing group if so configured. See "Sharing Configurator" in BRM Developer's Guide and "Creating or Modifying Multiple Ordered Balance Groups Simultaneously".

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

If a service identified in the PIN_FLD_MEMBERS array specifies a type-only service, such as GSM, this opcode 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. But, it does not create or modify /ordered_balgrp objects for any the /service/telco/gsm/data instances, /service/telco/gsm/sms instances, and so forth.

If successful, PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY returns the POID of the resource sharing group and an array of the /event/billing/ordered_balgrp/create and /event/billing/ordered_balgrp/modify 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:

• If there is more than one instance of an ordered balance group in the PIN_FLD_MEMBERS array.

• If the discount or charge 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. 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".

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

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

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