22 Managing Product Sharing Groups and Discount Offer Sharing Groups

Learn how to use product sharing groups to allow a group of customers to all own the same product in Oracle Communications Billing and Revenue Management (BRM). Discount sharing groups allow a group of customers to all own the same discount offer.

Topics in this document:

• About Product Sharing

• About Discount Offer Sharing

• About Sharing Groups

• About the Sharing Group Creation Process

• Setting Up Automated Sharing Groups

• Setting Up Manual Sharing Groups in Custom Client Applications

About Product Sharing

Product sharing enables your customers to share a product with a group of accounts. For example, a corporate account could purchase a Wireless product with special pricing, and then automatically share the package with all of its employees. In this case, the corporate account and all of its employees would own the same product and enjoy the same special pricing.

Note:

Product sharing is supported only by BRM systems that use Elastic Charging Engine (ECE) for usage charging.

About Discount Offer Sharing

Discount offer sharing enables your customers to share a discount offer with a group of accounts. For example, a corporate account could purchase an Internet discount offer that includes a 15% discount on the monthly fee and three free movie rentals, and then automatically share the discount offer with all of its employees. In this case, the corporate account and each of its employees would receive the 15% monthly fee discount and three free movie rentals.

Note:

Discount offer sharing is supported only by BRM systems that use ECE for usage charging.

About Sharing Groups

You specify the accounts that can share a product or discount offer by creating a sharing group. Each group includes the following:

• The owner. Owners have permission to purchase, modify, or remove the product or discount offer that is shared with members of the group. They can also add or remove group members.

  Note:

  An owner can own only one product sharing group and only one discount offer sharing group at a time. Also, owners cannot be a member of another sharing group.

• All members. Members of a sharing group can include accounts and services.

Note:

By default, all members of a sharing group must reside in the same database schema. To enable sharing groups to include members from multiple schemas, see "Enabling Group Members to Reside in Multiple Schemas".

If you want BRM to automatically create sharing groups for you (called automated sharing groups), also define the group type. Group types specify the type of members in a hierarchy that the group can contain. For example, group membership can be restricted to nonpaying child accounts and their services, or it can include both paying and nonpaying child accounts and their services. Table 22-1 shows the group types supported by automated sharing groups.

Table 22-1 Supported Automated Sharing Group Types

Group Type	Description
Hierarchy	Includes paying and nonpaying child accounts and their services.
Payment Responsibility	Includes nonpaying child accounts and their services. In this case, the charges from all child accounts are rolled up to the group's owner.

About the Sharing Group Creation Process

You create and modify sharing groups by using a third-party customer relationship management (CRM) application. You must configure your CRM application to accept the following information for each product sharing group or discount offer sharing group, and then pass it to the BRM API:

• Sharing group name

• Sharing group owner

• List of group members

• (Automated Sharing Groups Only) The group type:

  • For product sharing: Hierarchy product sharing group (H_PSG) or payment responsibility product sharing group (PR_PSG)

  • For discount offer sharing: Hierarchy discount sharing group (H_DSG) or payment responsibility discount sharing group (PR_DSG)

• (Optional) The product or discount offer to share with all members of the group

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

• With AMS, you can automate many of the group creation and modification processes. AMS automatically adds and removes members from the sharing group for you.

• Without AMS, you add and remove members manually to sharing groups.

BRM creates sharing groups as follows:

1. Takes as input all information about the sharing group.

2. Adds members to the sharing group. BRM determines whether the following is true:

   • AMS, automated sharing groups, and currency resource monitoring are enabled.

   • The group type is H_PSG, PR_PSG, H_DSG, or PR_DSG.

   If both are true, BRM uses AMS to add members. See "About Using AMS to Create Automated Sharing Groups".

   If either one is false, BRM adds members without AMS. See "About Manually Creating Sharing Groups".

About Using AMS to Create Automated Sharing Groups

You configure BRM to automatically add and remove members from sharing groups, based on the group type, by using AMS. AMS is a group of opcodes that automate many of the processes for creating and updating sharing groups.

AMS creates and updates automated sharing groups by following the account hierarchy or billing hierarchy associated with accounts and services. This synchronizes the membership between the hierarchy and the automated sharing group. AMS uses the owner and group type to find all appropriate child accounts and services in the hierarchy, and then adds them to the automated sharing group. When the owner purchases a product or discount offer, it automatically adds the product or discount offer to all members.

AMS automatically adds and removes members from sharing groups when the following occur:

• A sharing group is created. AMS takes as input the owner and the group type, and then searches through the owner's lineage to find accounts and services that match the criteria for the group type. All subordinate accounts and services in the hierarchy that meet the criteria are added as members.

  For example, when users create a payment responsibility-type sharing group, AMS adds to the group the owner's account and its services and all subordinate nonpaying child accounts and their services.

• An account or billing hierarchy is changed. AMS automatically adds or removes members from a sharing group, based on the group type. For example, when you add a nonpaying child account to a hierarchy, AMS automatically:

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

  • Finds all automated sharing groups associated with each parent account.

  • Adds the child account and its services to each sharing group.

When an automated sharing group is created or a hierarchy changes, the following occurs:

1. BRM generates a notification event.

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

3. The AMS opcodes add or remove members from the automated sharing group and adds the product or discount offer to all member accounts.

To configure your system to create or update automated sharing groups, see "Setting Up Automated Sharing Groups".

About Manually Creating Sharing Groups

When creating or updating a product sharing group or a discount offer sharing group without AMS, you are responsible for adding and removing members manually. BRM does not verify that the groups include all appropriate child accounts and services in a hierarchy nor does it check whether the hierarchy changes over time.

You must manually add or remove members when the following occur:

• A sharing group is created. You specify the individual accounts and services to add to the sharing group.

• An account or billing hierarchy is changed. You must manually update the sharing group associated with the hierarchy. When an account is added to a hierarchy, you must manually add the account to the sharing group. Likewise, when an account is removed from a hierarchy, you must manually remove the account from the sharing group.

To configure your custom client application to manually create or update sharing groups, see "Setting Up Manual Sharing Groups in Custom Client Applications".

Setting Up Automated Sharing Groups

To set up BRM to create automated product sharing groups and automated discount offer sharing groups for you, do the following:

1. Enable AMS and automated sharing groups in BRM.

   See "Enabling AMS and Automated Sharing Groups in BRM".

2. Enable currency resource monitoring in BRM.

   See "Enabling Currency Resource Monitoring".

3. Specify the type of organization hierarchy that BRM synchronizes with for each group type.

   See "Mapping Organization Hierarchy Types to Automated Sharing Group Types".

4. (Optional) Configure sharing groups to allow members from other database schemas.

   See "Enabling Group Members to Reside in Multiple Schemas".

5. Configure BRM event notification to call the AMS opcodes.

   See "Configuring Event Notification for Automated Sharing Groups".

6. Configure your custom client application to call the appropriate API for managing automated sharing groups.

   See "Implementing Automated Sharing Groups in Custom Client Applications".

7. Create the products or discount offers that can be shared with members of an automated sharing group.

   • For automated product sharing groups, see "Creating Charge Offers with Automatic Sharing Enabled".

   • For automated discount offer sharing groups, see "Creating Discount Offers with Automatic Sharing Enabled".

After your system is set up, you can use your custom client application to create automated sharing groups and then have the group owner purchase one of the charge offers or discount offers created in step 6.

Enabling AMS and Automated Sharing Groups in BRM

To enable AMS and automated sharing groups in BRM, run the pin_bus_params utility to modify the following business parameters in the subscription instance of the /config/business_params object:

• AutomatedGroupSharingSetup: Enables automated sharing groups in BRM.

• AutomatedMonitorSetup: Enables AMS.

See "pin_bus_params" in BRM Developer's Guide for information about the utility's syntax and parameters.

To enable automated sharing groups:

1. Go to BRM_home/sys/data/config.

2. Create an XML file from the /config/business_params object:

   pin_bus_params -r -c "Subscription" bus_params_subscription.xml

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

3. Open the XML file.

4. Set AutomatedGroupSharingSetup to one of the following:

   • 0: Disables both automated product sharing groups and automated discount offer sharing groups.

   • 1: Enables automated discount offer sharing groups

   • 2: Enables automated product sharing groups.

   • 3: Enables both automated product sharing groups and automated discount offer sharing groups.

   For example, this enables both automated product sharing groups and automated discount offer sharing groups:

   <AutomatedGroupSharingSetup>3</AutomatedGroupSharingSetup>

5. Set AutomatedMonitorSetup to enabled:

   <AutomatedMonitorSetup>enabled</AutomatedMonitorSetup>

6. Save the file and change its file name to bus_params_subscription.xml.

7. Load the XML file into the BRM database:

   pin_bus_params bus_params_subscription.xml

8. Stop and restart the CM.

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

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

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

Enabling Currency Resource Monitoring

Automated sharing groups rely upon the currency resource monitoring functionality included with the balance monitoring feature. Therefore, you must enable the balance monitoring feature. To do so, use the pin_bus_params utility to modify the BalanceMonitoring business parameter in the multi-bal instance of the /config/business_params object.

To enable currency resource monitoring:

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

   pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml

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

2. Set BalanceMonitoring to enabled:

   <BalanceMonitoring>enabled</BalanceMonitoring>

3. Save the file and change its name to bus_params_multi_bal.xml.

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

   pin_bus_params bus_params_multi_bal.xml

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

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

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

6. Stop and restart the CM.

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

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

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

Mapping Organization Hierarchy Types to Automated Sharing Group Types

When creating or modifying an automated sharing group, BRM searches through an account's hierarchy lineage, based on the group type, to find the owner or members in the group. You specify the type of organization hierarchy to synchronize with an automated sharing group type by using business profiles. For automated sharing groups, create business profiles that map:

• Account hierarchies (CorporateAutoSharingGroupType) to hierarchy product sharing groups (H_PSG) and hierarchy discount sharing groups (H_DSG).

• Billing hierarchies (PostpaidAutoSharingGroupType) to payment responsibility product sharing groups (PR_PSG) and payment responsibility discount sharing groups (PR_DSG).

To map organization hierarchy types to automated sharing groups types:

1. Open the pin_business_profile.xml file in an XML editor or a text editor.

   By default, the file is in the BRM_home/sys/data/config directory.

2. In the CorporateAutoSharingGroupType business profile, set the H_PSG and H_DSG keys to enabled (1):

   <BusinessProfilename="CorporateAutoSharingGroupType" >
      <Desc> Description of the business profile. </Desc>
      <!-- List key values -->
      <NameValue key="H_DSG" value="1"/>
      <NameValue key="PR_DSG" value="0"/>
      <NameValue key="H_PSG" value="1"/>
      <NameValue key="PR_PSG" value="0"/>
   </BusinessProfile>

3. In the PostpaidAutoSharingGroupType business profile, set the PR_PSG and PR_DSG keys to enabled (1):

   <BusinessProfilename="PostpaidAutoSharingGroupType" >
      <Desc> Description of the business profile. </Desc>
      <!-- List key values -->
      <NameValue key="H_DSG" value="0"/>
      <NameValue key="PR_DSG" value="1"/>
      <NameValue key="H_PSG" value="0"/>
      <NameValue key="PR_PSG" value="1"/>
   </BusinessProfile>

4. Save and close the file.

5. Use this command to load the pin_business_profile.xml file into the database:

   load_pin_business_profile pin_business_profile.xml

   Note:

   • When you run the utility, the pin_business_profile.xml and business_configuration.xsd files must be in the same directory. By default, both files are in BRM_home/sys/data/config.

   • This utility needs a configuration (pin.conf) file in the directory from which you run the utility.

   • If you do not run the utility from the directory in which pin_business_profile.xml is located, include the complete path to the file.

   See "load_pin_business_profile".

6. To verify that the business profile and validation template information was loaded, display the /config/business_profile objects and /config/template subclass objects by using one of the following features:

   • Object Browser

   • robj command with the testnap utility

   For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

7. Stop and restart the CM.

Enabling Group Members to Reside in Multiple Schemas

By default, all members of a sharing group must reside in the same database schema. If you want to include a member from a different schema, you must first use pin_amt to migrate the member to the same schema as all other sharing group members.

Alternatively, you can enable sharing groups to include members from other database schemas. To do so, use the pin_bus_params utility to modify the CrossSchemaSharingGroup business parameter in the system instance of the /config/business_params object.

To enable group members to reside in multiple schemas:

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

   pin_bus_params -r BusParamsSystem bus_params_system.xml

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

2. Set CrossSchemaSharingGroup to enabled:

   <CrossSchemaSharingGroup>enabled</CrossSchemaSharingGroup>

3. Save the file and change its name to bus_params_system.xml.

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

   pin_bus_params bus_params_system.xml

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

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

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

6. Stop and restart the CM.

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

Configuring Event Notification for Automated Sharing Groups

To configure the BRM event notification system to call AMS opcodes when creating and maintaining automated sharing groups:

1. In your BRM_home/sys/data/config/pin_notify file, ensure that the following lines in bold are uncommented:

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

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

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

3. Load your final pin_notify file into the BRM database.

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

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

      load_pin_notify configFileName

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

      See "load_pin_notify" for information about the utility's syntax and parameters.

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

Implementing Automated Sharing Groups in Custom Client Applications

You can configure a custom client application to manage automated product sharing groups and automated discount offer sharing groups in BRM by calling either BRM opcodes or Billing Care REST API endpoints. Table 22-2 lists the API to call for managing automated sharing groups.

Table 22-2 Implementation Using BRM API

Action	BRM Opcode	Billing Care REST API Endpoint
Create product or discount offer sharing groups	PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE	Create a Sharing Group
Modify product or discount offer sharing groups	PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY	Update a Sharing Group
Delete product or discount offer sharing groups	PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE	Delete a Sharing Group

When a product sharing group or discount offer sharing group is:

• Created successfully, BRM generates an /event/group/sharing/products/create or /event/group/sharing/discounts/create event

• Modified successfully, BRM generates an /event/group/sharing/products/modify or /event/group/sharing/discounts/modify event

• Deleted successfully, BRM generates an /event/group/sharing/products/delete or /event/group/sharing/discounts/delete event

These events trigger the BRM event notification system to call the AMS opcodes, which automatically add and remove members from product sharing groups and discount offer sharing groups (/group/sharing/products or /group/sharing/discounts objects) and then update each member's /ordered_balgrp object.

For more information, see the following:

• For Billing Care REST API: See the Sharing REST endpoints in REST API Reference for Billing Care

• For opcodes: See "Managing Sharing Groups" in BRM Opcode Guide

Creating Charge Offers with Automatic Sharing Enabled

To be able to automatically share a product with members of an automated product sharing group, you must create charge offers in Pricing Design Center (PDC) with automatic sharing enabled.

The way you enable automatic sharing depends on the method you use to create your product offerings:

• Using the PDC UI. When creating a charge offer, select the Share charge offer with members of billing hierarchy check box. For more information, see "Specifying Charge Offer Settings" in PDC Online Help.

• Using the ImportExportPricing utility. When creating a charge offer in your XML file, set the <groupSharingEnabled> element under the <chargeOffering> element. See "Sharing Products Automatically with Group Members" in PDC Creating Product Offerings.

Creating Discount Offers with Automatic Sharing Enabled

To be able to automatically share a discount offer with members of an automated discount sharing group, you must create discount offers in PDC with automatic sharing enabled.

The way you enable automatic sharing depends on the method you use to create your product offerings:

• Using the PDC UI. When creating a discount offer, select the Share discount offer with members of billing hierarchy check box. For more information, see "Specify Discount Offer Settings" in PDC Online Help.

• Using the ImportExportPricing utility. When creating a discount offer in your XML file, set the <groupSharingEnabled> element under the <alterationOffering> element. See "Sharing Discount Offers Automatically with Group Members" in PDC Creating Product Offerings.

Setting Up Manual Sharing Groups in Custom Client Applications

To create or update sharing groups manually, you must configure your custom client application to do the following:

1. Create product sharing groups (/group/sharing/products objects) and discount offer sharing groups (/group/sharing/discounts objects). To do so, call one of the following:

   • The PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE opcode. See "Creating a Product Sharing Group" in BRM Opcode Guide for more information.

   • Create a Sharing Group endpoint. See the Sharing endpoints in REST API Reference for Billing Care.

2. Modify an existing product sharing group or discount offer sharing group by adding members or changing the owner. To do so, call one of the following:

   • The PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY opcode. See "Modifying a Sharing Group" in BRM Opcode Guide for more information.

   • Modify a Sharing Group endpoint. See the Sharing endpoints in REST API Reference for Billing Care.

3. Add product sharing groups and discount offer sharing groups to each member's list of sharing groups (in /ordered_balgrp objects). You must create or update the /ordered_balgrp object associated with each account and service that you want to include in a sharing group. To do so, call one of the following:

   • The PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode. See "Managing Ordered Balance Groups" in BRM Opcode Guide for more information.

   • Update Shared Services for a Member endpoint. See the Sharing endpoints in REST API Reference for Billing Care.