3 Creating and Managing Hierarchical Account Groups

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

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

Before working with account and bill unit groups, you should be familiar with BRM rating and billing. See "About Creating a Price List" in BRM Setting Up Pricing and Rating and "About Billing" in BRM Configuring and Running Billing.

About Hierarchical Account Groups

A hierarchical account group is a set of accounts organized according to their positions in relation to each other. The relationships among accounts in a hierarchical group are similar to parent-child relationships. A hierarchical group is headed by a parent account with child accounts beneath it. At each level above the bottom of the hierarchy, the child accounts themselves can be parent accounts.

You can set up account groups for billing purposes. For example, a corporate customer might have several accounts for corporate employees, but the corporation itself pays all the employees' bills. In this case, the corporation's account is the parent account with the paying bill unit, and the employees' accounts are child accounts with nonpaying bill units.

An account's position in a hierarchy does not necessarily indicate whether it pays its own bills. Any account, either a parent or child, can have a paying bill unit or a nonpaying bill unit.

Note:

The top-level parent account must have a paying bill unit. For example, in Figure 3-1, Peter Jones must have a paying bill unit. (In Customer Center, the wallet icon identifies the account with a paying bill unit.)

Figure 3-1 Top-Level Parent Account with Paying Bill Unit

Description of Figure 3-1 follows
Description of ''Figure 3-1 Top-Level Parent Account with Paying Bill Unit''

For more information about paying and nonpaying bill units in accounts, see "A/R and Hierarchical Account Groups".

For more information about paying and nonpaying bill unit hierarchies, see "About Hierarchical Bill Units".

How Account Status Changes Affect Hierarchies

By default, changing the status of the parent account in a hierarchical account group changes the status of all subordinate bill units in the group. For more information, see "How Bill Unit Status Changes Affect Hierarchies".

Brand Requirements of Hierarchies

If your company supports Branded service management, parent and child accounts must belong to the same brand.

Performance Impact of Account Hierarchies

To maintain reliable data consistency, many operations lock an account at the beginning of the transaction. Therefore, in an account hierarchy, many of the associated accounts are also locked. While this provides reliable data consistency, it can cause a lot of serialization which decreases the throughput of the system.

If, with account hierarchies, this problem affects your system, you may choose to lock specific balance groups instead of the whole account.

Important:

Balance Group locking may enable separate contexts to attempt to lock the same object causing a system halt. Whenever balance group locking is used, every feature that uses balance group locking should be examined for overlap.

For more information on Balance Group Locking feature, see "Locking Specific Objects" in BRM Developer's Guide.

About Hierarchical Bill Units

Hierarchical bill units are a set of bill units organized according to their positions in relation to each other and the accounts to which they belong. A hierarchical bill unit group is headed by a parent bill unit with child bill units beneath it. A parent bill unit belongs to a parent account and a child bill unit belongs to a child account. At each level above the bottom of the hierarchy, the child bill units themselves can be parent bill units.

For billing purposes, child accounts can have nonpaying bill units or paying bill units:

  • A nonpaying bill unit's bill is paid by the paying bill unit in the parent account.

  • A paying bill unit in a child account pays its own bill.

A bill unit's position in a hierarchy does not necessarily indicate whether it pays its own bills. Any bill unit, either a parent or child, can be a paying bill unit or a nonpaying bill unit.

Figure 3-2 shows a simple hierarchical group. There are three bill units, one in each account, but because the paying bill unit in the parent account pays the bill for the nonpaying bill unit in the child account, there are only two bills for the three accounts:

Figure 3-2 Simple Hierarchical Group

Description of Figure 3-2 follows
Description of ''Figure 3-2 Simple Hierarchical Group''

When accounts have multiple bill units, the bill unit hierarchy becomes more complex. A child account can have both nonpaying bill units and paying bill units. The parent account is not required to pay all of the child account's bills.

Figure 3-3 shows two accounts with two bill units each, but only one of the child account's bill units is subordinate to the parent account:

Figure 3-3 Complex Bill Unit Hierarchy

Description of Figure 3-3 follows
Description of ''Figure 3-3 Complex Bill Unit Hierarchy''

At each level above the bottom of a hierarchy, the child bill units themselves can be parent bill units.

Figure 3-4 shows a three-level account hierarchy for accounts with multiple bill units. Because there are only three paying bill units, there are only three bills. The top parent account receives two bills and the bottom child account receives one bill:

Figure 3-4 Three-Level Account Hierarchy for Accounts with Multiple Bill Units

Description of Figure 3-4 follows
Description of ''Figure 3-4 Three-Level Account Hierarchy for Accounts with Multiple Bill Units''

A hierarchical bill unit group can contain bill units of accounts that do not belong to the same hierarchical account group.

Figure 3-5 shows two account hierarchies with multiple bill units. Because there are only three paying bill units, there are only three bills. Each parent account receives one bill and only one of the child account receives a bill:

Figure 3-5 Multiple Account Hierarchies with Multiple Bill Units

Description of Figure 3-5 follows
Description of ''Figure 3-5 Multiple Account Hierarchies with Multiple Bill Units''

To create multiple bill unit hierarchies, see "Creating Hierarchical Bill Units".

How Bill Unit Status Changes Affect Hierarchies

Changing the status of a parent account in a hierarchical group does not affect the status of child accounts; it only affects the status of the subordinate (nonpaying) bill units in the child accounts.

By default, changing the status of the parent account changes the status of all the parent's bill units and those of its child accounts. If a child account is also the parent of another account, the status of all subordinate bill units in each subsequent child account is also changed.

A bill unit's status can be active, inactive, or accounting only. The accounting only status indicates that limited billing is provided, without generating a bill.

For example, Figure 3-6 shows the bill units that are changed to inactive in a multilevel hierarchy when the parent account status is changed to inactive:

Figure 3-6 Impact of Parent Account Inactivation on Bill Units

Description of Figure 3-6 follows
Description of ''Figure 3-6 Impact of Parent Account Inactivation on Bill Units''

When the status of the parent bill unit is changed to accounting only, the status of all its child bill units are also changed to accounting only.

Changing the status of an individual bill unit within a parent account only changes the status of bill units in child accounts that are subordinate to the parent bill unit.

For example, Figure 3-7 shows the bill units that are changed to inactive in a multilevel hierarchy when the status of an individual bill unit in the parent account is inactivated:

Figure 3-7 Impact of Parent Account Inactivating One Bill Unit

Description of Figure 3-7 follows
Description of ''Figure 3-7 Impact of Parent Account Inactivating One Bill Unit''

Currency Requirements of Hierarchies

Nonpaying bill units in child accounts must have the same currency as their parent account. If the parent and child accounts use two currencies, their primary and secondary currencies must match.

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 drop-down list is the primary currency as shown in Figure 3-8:

Figure 3-8 Account Currencies

Description of Figure 3-8 follows
Description of ''Figure 3-8 Account Currencies''

Billing Setups in Hierarchies

Because paying bill units in parent accounts handle the billing for nonpaying bill units in child accounts, nonpaying bill units must have the same billing day of month, billing frequency, accounting cycle, and language as their parent account.

Paying bill units in child accounts, however, do not need to have the same billing setup and language as their parent account.

A/R and Hierarchical Account Groups

An account group consists of one parent account and one or more child account. When accounts are set up in a hierarchical relationship, each bill unit in the accounts are also assigned the status of parent or child. When accounts are billed, the bill units, not the accounts, are the paying and nonpaying entities.

Child accounts can have a subordinate bill unit (a paying bill unit) or nonsubordinate bill unit (a nonpaying bill unit).

A/R is billed differently for accounts that have nonpaying bill units and paying bill units:

  • The A/R for a paying bill unit is billed to itself.

  • The A/R for a nonpaying bill unit is billed to the A/R bill unit of the A/R account.

All accounts, both A/R and children with nonpaying bill units, are billed. Billing, however, involves two different processes:

  • Changing bills and bill items to open status, and creating new pending bills and bill items for the next bill. This occurs for all accounts.

    Note:

    If a bill unit in a child account is billed before its parent bill unit, Customer Center displays the nonpaying bill unit's items for the child account as pending until the paying bill unit in the parent account has been billed.
  • Requesting a payment for the bill, for example, initiating a credit card transaction. This occurs for paying bill units only. A nonpaying bill unit in a child account never receives a payment request.

BRM creates bills and bill items for all account bill units, including parent, child, nonpaying, and paying bill units. Each bill unit includes a pending bill, and one or more pending bill items. As an account incurs balance impacts, such as usage fees, the amount due accumulates in the pending bill items.

Each bill item includes these fields:

  • The account that the item belongs to. This field always points to the account that owns the item.

  • The balance group that the item belongs to.

  • The bill unit that the item belongs to.

  • The bill that the item belongs to. This field always points to the account's own bill.

  • The A/R bill unit that the item belongs to.

  • The A/R bill that the item belongs to.

The A/R fields determine which account, bill unit, and bill handles billing for the items. If the account has a nonpaying bill unit, the A/R bill unit field points to the parent account's paying bill unit, and the A/R bill field points to a bill in the parent account. In a multilevel hierarchy, the A/R belongs to the top-level, paying bill unit and bill.

Figure 3-9 shows a parent account, a child account with a nonpaying bill unit, and a child account with a paying bill unit. Notice that in the child account with the nonpaying bill unit, the A/R bill field (AR_BILL_OBJ) and A/R bill unit field (AR_BILLINFO_OBJ) point to the parent account.

Figure 3-9 A/R Bill Unit Differences for Child Accounts

Description of Figure 3-9 follows
Description of ''Figure 3-9 A/R Bill Unit Differences for Child Accounts''

A/R for Open Items and Pending Items

An account might have open items and pending items. This might happen if the customer hasn't paid an open bill, or has paid only part of it. In that case, there would be an open item and a pending item.

When the account's bill unit changes from a nonpaying to paying, or from paying to nonpaying, the A/R responsibility only for pending items is affected. A/R responsibility for open items is not changed.

Figure 3-10 shows a child account with a nonpaying bill unit that was once a parent account with a paying bill unit, so it has a pending item and an open item. Notice that the open item points to the child account as the owner of the A/R bill unit (AR_BILLINFO_OBJ) but the pending item points to the parent account as the owner of the A/R bill unit.

Figure 3-10 Account with Pending and Open Items

Description of Figure 3-10 follows
Description of ''Figure 3-10 Account with Pending and Open Items''

In some cases, an account can accumulate balance impacts for part of a billing cycle before becoming a child account with a nonpaying bill unit. When the account becomes a child account, the parent account becomes responsible for pending charges accumulated before the child account's bill unit became nonpaying.

Figure 3-11 shows an account that is billed on the 5th day of each month. The account becomes a child account with a nonpaying bill unit on the 10th day of the month, but since it has already incurred balance impacts that are recorded in a pending item, the parent account's bill unit is billed for the A/R for the 5th through the 15th.

Figure 3-11 Child Account Charges before Becoming a Subordinate Account

Description of Figure 3-11 follows
Description of ''Figure 3-11 Child Account Charges before Becoming a Subordinate Account''

Table 3-1 summarizes changes to A/R responsibilities:

Table 3-1 Effect of Changes to Account Hierarchy

Change to Account Open Items Pending Items

Parent account with paying bill unit becomes child account with nonpaying bill unit.

Nonpaying bill unit in the child account is responsible for its open item A/R.

Paying bill unit in the parent account is responsible for the pending item A/R of the child account's nonpaying bill unit.

Nonpaying bill unit in a child account becomes a paying bill unit.

Paying bill unit in the parent account is responsible for the open item A/R of the former child account's nonpaying bill unit.

Paying bill unit in the child account is responsible for its pending item A/R.

Child account with nonpaying bill unit changes parent account.

Paying bill unit in the old parent account is responsible for the open item A/R of the child account's nonpaying bill unit.

Paying bill unit in the new parent account is responsible for the pending item A/R of the child account's nonpaying bill unit.


To close all of an account's open items before you make the account a nonpaying child, use the Bill Now feature in Customer Center. For more information, see the Customer Center Help.

Multiple Levels of Parent Accounts

You can have child accounts with nonpaying bill units that are also parent accounts. In this case, the A/R for pending items is always handled by the top parent account in the hierarchy.

In Figure 3-12, account 300, which has a nonpaying bill unit, is a child to account 200, which is in turn a child to account 100. Notice that the A/R for account 300 is handled by account 100, not by account 200.

Figure 3-12 Multiple Levels of Parent Accounts

Description of Figure 3-12 follows
Description of ''Figure 3-12 Multiple Levels of Parent Accounts''

Hierarchy Changes and Billing Dates

A nonpaying bill unit in a child account must have the same billing day of month as the parent account. When you make an account a child account, the BRM system changes its billing day of month to match the parent account's billing day of month.

When an account becomes a child, its next billing date for the nonpaying bill unit might not be the same as the next billing date of the parent account. This happens because a change to a billing day of month always occurs after the end of the current cycle.

The result can be that the parent account's bill unit is billed, but the nonpaying bill unit in the child account is not billed. Therefore, the A/R for the nonpaying bill unit in the child account is not included in the parent account bill.

For example:

  1. You create Account A on June 8.

    The billing day of month is 8.

  2. You create Account B on June 20 and then change its billing day to 8.

    The next billing date is August 8. This happens because the current billing cycle, from June 20 through July 20, must be completed before the billing day of month changes. A long billing cycle; from June 20 through August 8, is created.

  3. You make Account B a child account to Account A, changing Account B's bill unit to subordinate (nonpaying).

  4. On July 8, Account A is billed, but Account B is not because Account B's next billing date is August 8.

    Therefore, the bill only includes the A/R for Account A, the parent account.

  5. On August 8, both accounts are billed.

    The bill includes A/R from both accounts, including:

    • Parent account A/R from July 8 to August 8.

    • Child account A/R from June 20 to August 8.

  6. On all subsequent billing dates, both accounts are billed.

Figure 3-13 shows a timeline for the billing dates for two accounts in a parent-child relationship where the child account has a nonpaying bill unit.

Figure 3-13 Hierarchy Changes and Billing Dates

Description of Figure 3-13 follows
Description of ''Figure 3-13 Hierarchy Changes and Billing Dates''

Examples of Changes to Account Group Hierarchy

These examples show who is responsible for A/R for different account hierarchy changes.

An Account Becomes a Child Account with a Paying Bill Unit

In this case, there is no change to how A/R is handled. The parent account handles its own A/R, the child account handles its own A/R.

An Account Becomes a Child Account with a Nonpaying Bill Unit When It Is Created

In this case, all the A/R is handled by the parent account, and the billing date of the child account is the same as the parent account.

An Account Becomes a Child Account with a Nonpaying Bill Unit Immediately After It Is Created

In this case, the account has not been billed yet, so all of its items are pending. Therefore, all of its A/R is handled by the parent account.

Note:

By default, for customers who pay by credit card, BRM charges purchase fees and the first cycle forward fee at registration. The A/R for these fees is stored in open items and is charged to the child account's bill unit. You can turn off credit card collection at account creation by editing the cc_collect entry in the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf, where BRM_Home is the directory in which BRM is installed). See "Charging Customers at Registration" in BRM Managing Customers.

An Account Becomes a Child Account with a Nonpaying Bill Unit Several Months After It Is Created

In this case, the A/R for all of the pending items in the nonpaying bill unit of the child account are handled by the parent account. Any open items are handled by the child account. The billing date of the nonpaying bill unit in the child account is changed to match the billing date of the parent account.

A Child Account with a Nonpaying Bill Unit Changes Parent Accounts

In this case, the A/R for all pending items in the nonpaying bill unit of the child account is now handled by a different parent account. Any open items are the responsibility of the former parent account. The billing date of the child account is changed to match the billing date of the new parent account.

A Child Account with a Nonpaying Bill Unit Becomes a Child Account with a Paying Bill Unit

In this case, the fields in pending items that specify the A/R bill unit in the A/R account and the bill both point to the paying bill unit in the child account. If the parent account's bill unit has any open items that include A/R from the child account, the parent account's bill unit is responsible for that A/R even when the child account's bill unit is no longer nonpaying (subordinate).

Creating Hierarchical Groups

By default, accounts are created with one bill unit. When you create account hierarchies in Customer Center, the bill units are automatically assigned the same hierarchical position as the accounts to which they belong. To create account hierarchies, see "Creating Hierarchical Account Groups".

If you want your customers to be able to receive multiple bills for different services, you can create additional bill units per account. When accounts in a hierarchy have multiple bill units, you must also create bill unit hierarchies. See "Creating Hierarchical Bill Units".

Creating Hierarchical Account Groups

There are two ways to create a child account:

  • While creating an account in Customer Center, designate an existing account to be its parent. For information about creating accounts, see the Customer Center Help.

    Note:

    In the Customer Center Account Creation wizard, you can create either paying or nonpaying child accounts. The paying and nonpaying designation is assigned to the account's default bill unit when the account is created.
  • After creating a standalone account, make it a child account. For more information, see the Customer Center Help.

Creating Hierarchical Bill Units

You create a bill unit hierarchy when you set up account hierarchies in Customer Center. You specify which of an account's bill unit is the paying and non-paying bill unit.

The bill units of accounts that do not belong to the same hierarchical account group can form a bill unit hierarchy. Bill units in a child account can be subordinate to bill units in a different parent account.

For information on using BRM opcodes to create bill unit hierarchies in custom code, see "Managing Bill Units with Your Custom Application" in BRM Configuring and Running Billing.

Managing Hierarchical Groups

To manage hierarchies, you can do the following:

  • Display hierarchical groups in Customer Center.

    You can see the structure of a hierarchical group in the Hierarchy tab of the parent account of the group. Initially, this tab shows the direct lineage of an account, not its siblings or the siblings of its parent.

    For information, see the Customer Center Help.

  • Change the parent of an account.

    You can use Customer Center to change an account's parent at any time. You change an account's parent by adding the account to a group, removing it from a group, or moving it from one group to another.

    For information, see the Customer Center Help.

  • Defer account group changes until a later date.

    In Customer Center, you can schedule a parent change for a future date. You can then use a daily billing utility, pin_deferred_act, to execute the change automatically on the scheduled date.

    For information, see the Customer Center Help and "Managing Deferred Actions" in BRM Managing Customers.

Moving Closed Accounts into or out of Hierarchies

By default, BRM does not allow moving closed accounts into or out of account hierarchies. To allow moving of closed accounts into or out of hierarchies, configure the allow_move_close_acct entry in the Connection Manager (CM) configuration file.

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

  2. Set the allow_move_close_acct entry to 1.

    By default, this entry is set to 0.

    - fm_bill allow_move_close_acct 1
      
    
  3. Save and close the file.

To remove an account from a hierarchy, see the Customer Center Help.

Managing Hierarchical Account Groups by Using Your Custom Application

To create and manage account groups, use the PCM_OP_BILL_GROUP opcodes, for example, PCM_OP_BILL_GROUP_CREATE (see BRM Developer's Reference). These opcodes call the PCM_OP_GROUP opcodes to preform the functionality. Your custom application should use the PCM_OP_BILL_GROUP opcodes instead of calling the PCM_OP_GROUP opcodes directly.

Creating an Account Group

To create an account group, use PCM_OP_BILL_GROUP_CREATE.

This opcode creates a /group object for use in the account group hierarchy, and sets any /group object attributes necessary for account billing. When account groups are created for billing purposes, the PIN_FLD_TYPE_STR in the /group object is set to Billing Hierarchy, and the storable object POIDs created are type /group/billing.

The required input fields for PCM_OP_BILL_GROUP_CREATE are:

  • The name of the /group object

  • The parent /account object to own the group

To create a /group object, PCM_OP_BILL_GROUP_CREATE calls PCM_OP_GROUP_CREATE_GROUP. After the group is created, the new POID is written to the /account object of the group's parent (set with the PIN_FLD_PARENT field). PIN_FLD_GROUP_OBJ is the field set in the account record. The output of PCM_OP_GROUP_CREATE_GROUP is returned as the output of this call.

This operation is performed inside a transaction.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_CREATE includes:

  • The POID of the group that was created

  • A PIN_FLD_RESULTS array with a single event element

  • The results array returns the POID of an event storable object entry that holds the old value of the parent storable object and the new value respectively. Since a storable object is being created and an old value did not exist, the old value is always returned as NULL. The old and new parent values are kept in EVENT_GROUP_PARENTS_T table, which is linked to the EVENT_T table.

If an error occurs, a NULL flist is returned.

Adding a Member to an Account Group

To add a member to an account group, use PCM_OP_BILL_GROUP_ADD_MEMBER.

This opcode adds accounts to an account group for billing purposes, when the accounts' bill units (/billinfo objects) are to be set up in a billing hierarchy.

The input to PCM_OP_BILL_GROUP_ADD_MEMBER includes:

  • The /group object being changed

  • A set of account POIDs identifying the accounts to be added

Any account can be added to a given account group, including the parent of another group. PCM_OP_BILL_GROUP_ADD_MEMBER calls PCM_OP_GROUP_ADD_MEMBER to actually add the new member. After accounts are successfully added, an /event object is created that contains a list of the new accounts. The POID of the new /event object is returned.

Only new members are actually added to an account group. If the add members list contains accounts that are already in the account group, they are ignored. All accounts being added to a account hierarchy must:

  • Be unique in that they are not already members of a account group

  • Have the same bill time information (NEXT_BILL_T field in the /billinfo object) as the parent /billinfo object in the parent account for the group

This operation is performed inside a transaction.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_ADD_MEMBER includes:

  • The POID of the modified group

  • A PIN_FLD_RESULTS array with a single event element

The results array returns the POID of an event storable object entry that holds the list of new accounts added to the account group. The list of new accounts added are kept in EVENT_GROUP_MEMBERS_T table which is linked to the EVENT_T table.

If an error occurs, a NULL flist is returned.

Deleting a Member from an Account Group

To delete a member from an account group, use PCM_OP_BILL_GROUP_DELETE_MEMBER.

This opcode deletes accounts from account groups that are set up for billing purposes.

The input to PCM_OP_BILL_GROUP_DELETE_MEMBER is:

  • The group POID

  • A set of account POIDs identifying the members to be deleted

The deletion operation is performed using a call to PCM_OP_GROUP_DELETE_MEMBER. After accounts are successfully deleted from the group, an /event object is created that contains the list of the accounts deleted. The POID of that /event object is returned.

The list of members to delete can contain account POIDs that do not exist in the account group; these members are ignored. Only existing members are deleted from the account group.

A member cannot be deleted from an account group if it has a subordinate bill unit (/billinfo object) as subordinate /billinfo objects must always be linked to a parent account.

This operation is performed inside a transaction.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_DELETE_MEMBER includes:

  • The POID of the group

  • A PIN_FLD_RESULTS array with a single event element

The results array returns the POID of an event storable object entry that holds the list of accounts deleted from the account group. The list of accounts deleted are kept in EVENT_GROUP_MEMBERS_T table which is linked to the EVENT_T table.

If an error occurs, a NULL flist is returned.

Moving a Group Member

To move an account from one group to another, use PCM_OP_BILL_GROUP_MOVE_MEMBER.

This opcode is the recommended way to perform this action. It is a wrapper for the other BILL_GROUP opcodes.

When a member is moved, PCM_OP_BILL_GROUP_MOVE_MEMBER calls PCM_OP_BILL_GROUP_DELETE. If the member being moved is the last member of a group, PCM_OP_BILL_GROUP_MOVE_MEMBER also calls PCM_OP_BILL_GROUP_DELETE to remove the group.

The PIN_FLD_FLAGS field in the PCM_OP_BILL_GROUP_MOVE_MEMBER opcode's input flist controls the type of information returned in the output flist. The settings for this flag are the following:

  • 1: If a bill unit (/billinfo object) of the account to be moved is a member of a collections group, the opcode returns the details of the collections group for all the bill units of the account. In this case, the account will not be moved to billing hierarchy.

  • 2: If a bill unit (/billinfo object) of an account to be moved is a member of a collections group, the opcode calls the PCM_OP_COLLECTIONS_DELETE_GROUP_MEMBER opcode to delete the collections group member and then continues with moving the bill group member.

If the member is being moved into an existing group, PCM_OP_BILL_GROUP_MOVE_MEMBER also calls PCM_OP_BILL_GROUP_ADD_MEMBER to add it to the target group.

If the member is being moved into a group that does not already exist, PCM_OP_BILL_GROUP_MOVE_MEMBER calls PCM_OP_BILL_GROUP_CREATE to create it.

If the target account (the account heading the nonexistent target group) also does not exist, PCM_OP_BILL_GROUP_MOVE_MEMBER attempts to remove the source member from its group and leave it as a standalone account. If the source member is has a subordinate bill unit (/billinfo object), nothing is done and an error is returned.

Note:

Any accounts that have bill units that are subordinate to bill units in the moved account are moved with it.

Deleting an Account Group

To delete an account group, use PCM_OP_BILL_GROUP_DELETE.

This opcode deletes account groups that were set up for billing purposes. It performs the following actions:

  • Deletes the /group object specified.

  • Deletes the members list for that account group.

  • Clears the PIN_FLD_GROUP_OBJ field in the group parent's /account object.

To delete a /group object, call PCM_OP_GROUP_DELETE_GROUP. The input to PCM_OP_BILL_GROUP_DELETE is the POID of the account group to be deleted. After successfully deleting the group, it returns the old group POID.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_DELETE includes the POID of the group that was deleted.

If an error occurs, a NULL flist is returned.

Getting a List of Child Accounts in an Account Group

To get a list of child accounts in an account group, use PCM_OP_BILL_GROUP_GET_CHILDREN.

This opcode returns a members list holding the children account POIDs for an account group set up for billing purposes. Specific account fields may be read for each account (for example, account name) by passing the /account object fields of interest in the input list along with the POID of the /group object. If the input list only contains the /group object POID, all the fields in the ACCOUNT table for each child is returned.

This operation is performed inside a transaction.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_GET_CHILDREN includes:

  • The POID of the group that was modified.

  • An array of PIN_FLD_MEMBERS, where each array element holds an account POID along with one or more account fields for that entry.

If an error occurs, a NULL flist is returned.

Finding the Parent of an Account Group

To find the parent of an account group, use PCM_OP_BILL_GROUP_GET_PARENT.

PCM_OP_BILL_GROUP_GET_PARENT retrieves the parent account of a given /group object. The input to PCM_OP_BILL_GROUP_GET_PARENT is a account group POID. The account POID identifying the group's parent account is returned.

This operation is performed inside a transaction.

Additional Return Information

The output flist for PCM_OP_BILL_GROUP_GET_PARENT includes the POID of the account that is the parent of the group.

If an error occurs, a NULL flist is returned.

About the PCM_OP_GROUP Opcodes

The Group FM includes the following standard opcodes. These opcodes are called by other opcodes, for example, the wrapper opcode PCM_OP_BILL_GROUP_CREATE calls the PCM_OP_GROUP_CREATE_GROUP opcode to create a group. Whenever possible, use the wrapper opcode, not the GROUP opcode.

Creating a Group

To create a new group storable object, use PCM_OP_GROUP_CREATE_GROUP.

After successfully creating the group, the new group POID is returned.

This operation is performed inside a transaction.

PCM_OP_GROUP_CREATE_GROUP first initializes the group to be created. Then this opcode uses PCM_OP_GROUP_SET_PARENT to set any parent information specified on input. If a members list is also passed in, PCM_OP_GROUP_ADD_MEMBER is called to add those members. PCM_OP_GROUP_CREATE_GROUP does not generate an event storable object. However, if new members are specified and added to the group, they will create an /event object. The output of PCM_OP_GROUP_SET_PARENT and PCM_OP_GROUP_ADD_MEMBER are attached to the return flist.

Adding Members to a Group

To add members to a group, use PCM_OP_GROUP_ADD_MEMBER.

The input to this opcode is a set of member POIDs identifying the members to be added. After members are successfully added, an /event object is created containing a list of new members added. The POID of the /event object is returned.

This operation is performed inside a transaction.

The add members list may contain member POIDs that already exist in the group. These members are ignored; only new members are added to the group.

Deleting Members from a Group

To delete members from a group, use PCM_OP_GROUP_DELETE_MEMBER.

The input to this opcode is a set of member POIDs identifying the members to be deleted. After successfully deleting members, an /event object is created containing a list of the members deleted. The POID of the /event object is returned. This operation is performed inside a transaction.

The delete-members list may contain member POIDs that do not exist in the group. These elements are ignored and not processed; only existing members are deleted from the group.

Setting a Group Parent

To set the parent storable object of a group, use PCM_OP_GROUP_SET_PARENT.

This opcode sets the parent storable object for the given group. The input to PCM_OP_GROUP_SET_PARENT includes the group POID to be modified and the new parent storable object to be set. After successfully setting the parent field, the group POID id is returned.

This operation is performed inside a transaction.

The parent field is specified using a POID id, which is similar to a member element of a group. However, a parent is considered the storable object that has ownership of this group. If this group represents accounts, then the members elements refer to accounts that belong to this group and the parent storable object would then be an account that is responsible for all the member accounts in the group.

The results array returns the POID of an /event object entry that holds the old value of the parent storable object, and the new value, respectively. The old and new parent values are kept in the EVENT_GROUP_PARENTS_T table, which is linked to the EVENT_T table.

Deleting a Group

To delete an existing group storable object, use PCM_OP_GROUP_DELETE_GROUP.

PCM_OP_GROUP_DELETE_GROUP removes the specified /group object and all members linked to it. The input to this opcode is the POID of the group to be deleted. After successfully deleting the group, the old group POID id is returned.

This operation is performed inside a transaction.

Updating the Inheritance Fields in a Group

To update the inheritance fields of an existing group, use PCM_OP_GROUP_UPDATE_INHERITED.

The input to this opcode is the group POID to be updated, followed by the inheritance information. The inheritance information is passed as a substructure flist and must have space allocated for it as a separate storable object, independent of the /group storable object.

This operation is performed inside a transaction.