5 Creating and Managing Sponsor Groups

This chapter describes how to create and manage sponsored accounts in your Oracle Communications Billing and Revenue Management (BRM) system.

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

About Sponsor Groups

Note:

Sponsor groups are supported for backward compatibility. If you have not set up sponsorship, create resource sharing groups instead. Pipeline Manager discounting is required to set up resource sharing groups. If you do not use Pipeline Manager, you can configure discounts at the deal-level, however, you will not be able to create the various discount configurations that are available with Pipeline Manager discounting. For information about resource sharing groups, See "About Resource Sharing Groups". For information about Pipeline Manager discounting, see "About Discounts" in BRM Configuring Pipeline Rating and Discounting. For information about deal-level discounts, see "Providing Deal-Level Discounts" in BRM Setting Up Pricing and Rating.

You manage sponsored billing by setting up sponsor groups. A sponsor group consists of one sponsor group owner account and one or more member accounts. An owner account can sponsor multiple sponsor groups, and a member account can belong to multiple sponsor groups. A member account does not need to use the same billing cycle as the sponsor owner account.

You can use sponsored billing in the following cases:

• Sponsoring a service. For example, a subscriber pays for Internet access, and the subscriber's grandmother pays for a gaming service as a gift.

• Sponsoring part of a service. For example, a company pays an employee's monthly fee for Internet access, which includes 10 free hours per month. The employee pays an hourly rate for any usage over 10 hours per month.

• Crediting the sponsoring account for sponsored usage. For example, a sponsoring company pays an employee's monthly fee for Internet access. For every hour the employee uses, the sponsoring company receives a credit against its cost of providing the monthly service.

• Crediting one account and charging another account in a single transaction. For example, if you pay a commission to another company for a service that you provide, you can use sponsored rates to convert part of a balance impact into a credit that provides the commission.

Figure 5-1 shows a sponsor group whose owner pays for its members Internet access but not for their email.

Figure 5-1 Sponsorship of Internet Access Charges

Description of ''Figure 5-1 Sponsorship of Internet Access Charges''

Figure 5-2 shows a sponsor group whose owner pays its members' monthly subscription fees but not their usage fees.

Figure 5-2 Sponsorship of Cycle Forward Event Fees

Description of ''Figure 5-2 Sponsorship of Cycle Forward Event Fees''

How Charges Are Sponsored

In Customer Center, you select rate plans for sponsor groups to sponsor. For sponsorship to occur, the appropriate resources in each sponsored rate plan's rates must be set as sponsorable in your company's price list.

For example, sponsor group A sponsors rate plan B from product C, which is associated with an Internet access service. Rate plan B contains three usage rates based on time of day: rate 1 (8 a.m. to 5 p.m.), rate 2 (5 p.m. to 11 p.m.), and rate 3 (11 p.m. to 8 a.m.). Each rate tracks balance impacts in US Dollars and euros. The US Dollar resource is set as sponsorable in rates 2 and 3. In this situation, the owner of sponsor group A pays usage charges for all members of the group whose currency resource is US Dollars when they use the access service any time from 5 p.m. to 8 a.m. The owner of sponsor group A does not pay any charges for members whose currency resource is euros or for any members when they use the service from 8 a.m. to 5 p.m.

If a member account receives charges that should be sponsored, use Pricing Center to verify that the appropriate resources in the rate plan's rates are sponsorable.

For more information about rate plans and rates, see "About Creating a Price List" in BRM Setting Up Pricing and Rating.

When Sponsorship Begins

Sponsorship begins when an account becomes a member of a sponsor group. If the account owned products sponsored by the group before the account was added to the group, those products are sponsored as soon as the account joins the group. Charges incurred before the account was added to the group, however, are not retroactively sponsored.

Creating and Managing Sponsored Groups

Use Customer Center to create and manage sponsored groups. For more information, see the Customer Center Help.

Creating Sponsorship Bill Units

By default, an account is created with one bill unit. When you create sponsor groups in Customer Center, the bill units in the accounts are assigned the same sponsor relationships as the accounts to which they belong.

You can create additional bill units for accounts by writing custom code using the BRM API. For more information, see "Managing Bill Units with Your Custom Application" in BRM Configuring and Running Billing.

When you create additional bill units, you associate an account and a payment method with the new bill unit (/billinfo object). To associate account balances with a bill unit's bill, you must link the account /balance_group objects to the new /billinfo object. To create sponsorship bill units for accounts that have multiple bill units, you specify the sponsorship relationships in fields in the /billinfo objects.

After you have created the bill unit sponsorship associations, you must also pass the appropriate /billinfo objects to the opcodes that process billing and payments.

For accounts that have multiple bill units, bill unit sponsorship becomes more complex. Bill units in an account can be sponsor owners or sponsored members. Sponsor owner accounts can have bill units that do not sponsor any charges, and sponsored member accounts can have bill units that do not have any sponsored charges.

In Figure 5-3, the member account has two bill units, but only one of them is handled by the sponsor account.

Figure 5-3 Complex Sponsorship

Description of ''Figure 5-3 Complex Sponsorship''

Guaranteed Sponsorship

You can specify that the sponsor guarantees to pay the sponsored charges, even if the balance of the sponsor's account exceeds the credit limit. Guaranteed sponsorship applies to all the rate plans a group sponsors.

For more information, see the Customer Center Help.

How Account Status Changes Affect Sponsor Groups

When a sponsor group owner account is inactivated, sponsorship is suspended.

When an inactive sponsor owner account is reactivated, it automatically resumes paying its member accounts' sponsored charges.

When a sponsor group owner is closed, sponsored charges no longer affect the owner account's balance, and one of the following occurs:

• All members are removed from the owner's sponsor groups, and the groups are deleted. Member accounts begin paying all charges for the formerly sponsored products.

• All members are removed from the owner's sponsor groups, the groups are deleted, and the sponsored products are canceled.

  • This operation can be time-consuming. BRM checks all products owned by each member account, determines whether the products belong to the owner account's sponsor groups, and then cancels those that do.

  • Member accounts pay all cancellation fees for sponsored rate plans.

• All sponsor groups owned by the closed account are assigned to a new sponsor owner account. All groups are assigned to the same new owner. Sponsored fees accrued before the old owner is closed are charged to the old owner. After closure, all fees are charged to the new owner.

  Caution:

  When groups are assigned to a new owner, the following members (if they exist) are deleted from the groups:

  • The new owner account

  • Accounts that sponsor the new owner

  After being deleted, the preceding accounts begin paying all charges formerly sponsored by the groups. For example, in the following figure, sponsor owner Grandma pays monthly content service charges for members Anne, Dad, and Mom. Sponsor owner Mom pays monthly short message service charges for members Anne and Dad:

  
  Description of the illustration ''pay_groups_cyclic_mem1.gif''

  If you close Grandma's account and reassign her sponsor group to Dad's account, Dad is deleted from the group because he is the group's new owner. Mom is deleted from the group because Dad is a member of a group she sponsors. Dad and Mom now pay their own content service charges:

  
  Description of the illustration ''pay_groups_cyclic_mem2.gif''

  Important:

  If a member account purchases a sponsored product while owned by account A and then cancels the product while owned by account B, all refunds or cancellation fees are applied to account B. Thus, account B might get a refund for a fee it did not pay, or it might be charged a cancellation fee for a product it did not purchase.

When a closed sponsor owner account is reactivated, former sponsor relationships between owner and member accounts must be manually re-created.

When a member accounts is closed, the cancellation fees for sponsored rate plans are applied to the sponsor owner account, not to the member account.

By default, when a member account is closed, it is removed from all the sponsor groups where it is a member. To specify whether to remove the member account from the sponsor groups, you modify the billing instance of the /config/business_params object.

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

To specify whether to remove a member account from sponsor groups:

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

   pin_bus_params -r BusParamsBilling bus_params_billing.xml 
     
   

   This command creates the XML file named bus_params_billing.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:

   <RemoveSponsoree>disabled</RemoveSponsoree>
     
   

3. Change disabled to enabled. For this parameter:

   • disabled means that BRM keeps the member account in the sponsor groups.

   • enabled means that BRM removes the member account from the sponsor groups.

     Caution:

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

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

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

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

   For general instructions on using testnap, see "Using 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.

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

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

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

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

Currency Requirements of Sponsor Groups

The sponsor group owner account and all accounts it sponsors must use the same currency. If the accounts use two currencies, they must use the same primary account currency.

To determine the currency or currencies an account uses, in Customer Center, open the account and look on the toolbar. The first currency in the selector list is the primary currency as shown in Figure 5-4:

Figure 5-4 Primary Currency in Customer Center

Description of ''Figure 5-4 Primary Currency in Customer Center''

Product Ownership Requirements of Sponsor Groups

The sponsor group owner account does not need to own the sponsored products.

Brand Requirements of Sponsor Groups

If your company supports Branded service management, group owners and members must belong to the same brand.

Troubleshooting Sponsorship

• The resources in all rates in sponsored rate plans should be set as sponsorable in your company's price list. If a member account receives charges associated with a sponsored rate plan, use Pricing Center to verify that all the rate plan's resources are sponsorable.

• Your billing setup must be configured to bill member accounts before owner accounts. If it is not, the members' sponsored charges might not be included in the owner's bill for the current billing cycle. Instead, they are added to the owner's bill for the next billing cycle.

  See "Setting Up Billing for Sponsorship" in BRM Configuring and Running Billing.

• Each product in a member account should have only one sponsor.

  See "One Sponsor per Product" in BRM Setting Up Pricing and Rating.

• Sponsorship is suspended when the status of the sponsor owner account is inactive.

• Sponsorship may end when the status of the sponsor owner account is closed.

  See "How Account Status Changes Affect Sponsor Groups".

Managing Sponsor Groups in Your Custom Application

For information about sponsored billing, see "About Sponsor Groups".

Use the following opcodes to manage sponsor groups:

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_CREATE

  See "Creating a Sponsor Group".

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_MODIFY

  See "Modifying a Sponsor Group".

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT

  See "Setting the Parent of a Sponsor Group".

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_ADD_MEMBER

  See "Adding a Member to a Sponsor Group".

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE_MEMBER

  See "Deleting a Member from a Sponsor Group".

• PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE

  See "Deleting a Sponsor Group".

Creating a Sponsor Group

To create a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_CREATE. This opcode takes the POID of the sponsor's account as input and performs the following functions:

• Creates the /group/sponsor object

• Initializes the sponsor group object by using the name for the sponsor group specified in the input flist

• Initializes the sponsor group object with the sponsored product and rate information, if specified in the input flist

• Creates an /event/group/parent object to record the creation of the sponsor group

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_CREATE returns these values:

• The POID of the /group/sponsor object created.

• The POID of the /event/group/parent object created to record the creation of the sponsor group.

Modifying a Sponsor Group

To modify a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_MODIFY.

This opcode takes the POID of the sponsor group and sponsored product and rate information as input and updates the sponsor group object by adding or removing the product and rate specified.

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_MODIFY returns the POID of the /group/sponsor object passed in the input flist.

Setting the Parent of a Sponsor Group

To set the parent of a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT.

This opcode takes the account POID of the new sponsor group owner and the POID of the sponsor group as input, and performs the following functions:

• Verifies that the currencies of the existing sponsor group owner and the proposed new sponsor group owner are the same.

• Checks whether any members of the sponsor group are already sponsoring the proposed new sponsor group owner in another group.

  Important:

  A sponsor group owner cannot, be sponsored by a member of its sponsor group. If any of the existing members of the sponsor group form such a cyclic relationship with the proposed new sponsor group owner, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT drops the member from the /group/sponsor object.

• Sets the sponsor group owner field of the /group/sponsor object.

  /parent 204438794022169271 0
    
  

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT returns the POID of the event /group/member/parent that is created.

If the currency of the new sponsor parent does not match the currency of the existing sponsor parent, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT logs an error in the CM pinlog file with the error code PIN_ERR_CURRENCY_MISMATCH.

If any members of the sponsor group form a cyclic relationship with the new sponsor group owner (that is, if any members are sponsoring the new sponsor group owner in another group), PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_SET_PARENT logs a message in the CM pinlog file that indicate the POIDs of those members.

Adding a Member to a Sponsor Group

To add a member to a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_ADD_MEMBER.

This opcode takes the POID of the sponsor group object and the POID of the member's account object as input and performs the following operations:

• Verifies that the member account uses the same currency as the sponsor group owner account.

  Important:

  The PIN_FLD_CURRENCY field in the input flist is optional. Set PIN_FLD_CURRENCY to specify the currency for the member and for the sponsor owner. If currency information is not provided in the input flist, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_ADD_MEMBER queries the database for this information; as a result, the opcode takes slightly longer to finish.

• Verifies that the member account does not have the sponsor owner account as its member in a cyclic relationship. For example, where account A sponsors account B, and Account B attempts to sponsor account A. This is a cyclic relation.

• Adds the member to the sponsor group.

• Creates an /event/group/member object to record the addition of a sponsor group member.

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_ADD_MEMBER returns these values:

• The POID of the /group/sponsor object to which the member was added

• The POID of the /event/group/member object created to record adding the member to the sponsor group

PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_ADD_MEMBER fails in the following cases:

• If the member has the same currency as the sponsor

• If a cyclic relation exists between the member account and the sponsor account

Deleting a Member from a Sponsor Group

To delete a member from a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE_MEMBER.

This opcode takes the POID of the sponsor group and the POID of the member's account as input, and performs the following functions:

• Verifies if the member is sponsored by the sponsor group

• Removes the member from the sponsor group

• Creates an /event/group/member object to record the deletion of the sponsor group member

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE_MEMBER returns these values:

• The POID of the /group/sponsor object passed in the input flist

• The POID of the /event/group/member object created to record the deletion of the sponsor group member

PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE_MEMBER fails if the member is not sponsored by the sponsor group passed in the input flist.

Deleting a Sponsor Group

To delete a sponsor group, use PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE.

This opcode takes the POID of the sponsor group as input and performs these functions:

• Deletes the sponsored accounts from the sponsor group

• Deletes the /group/sponsor object

• Creates an /event/group/member object to record the deletion of the sponsor group

If successful, PCM_OP_SUBSCRIPTION_SPONSOR_GROUP_DELETE returns the POID of the /group/sponsor object that was passed in the input flist.