9 Customer Management Opcode Workflows

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

Topics in this document:

• Opcodes Described in This Chapter

• About Account Locking

• Transaction Handling During Account Creation

• Creating Accounts

• Managing Name and Address Information

• Authenticating and Authorizing Customers

• Managing and Customizing Profiles

• Modifying an Account

• Creating Services

• Modifying Services

• Finding Accounts

• Deleting Accounts

• Customizing Customer Payment Information

• Setting Account, Service, and Bill Unit Status

• Getting Life Cycle States

• Amending Creditor Information

• Amending a Mandate

• Canceling a Mandate

• Managing Deferred Actions

• Managing Service Groups

• Managing Profile Sharing Groups

• Using Access Control Lists

• Customizing the Account Dump Utility (ADU)

• Business Profile Opcode Workflows

• Creating and Managing Account Hierachies

Opcodes Described in This Chapter

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

Caution:

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

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

Table 9-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_FIND	Finding a Customer's Account Information Authenticating User Actions
PCM_OP_ACT_FIND_VERIFY	Authenticating User Actions Customizing Authentication Checks
PCM_OP_ACT_LOGIN	Customizing Authentication Checks
PCM_OP_ACT_POL_EVENT_LIMIT	Inactivating Accounts that Exceed a Specified Limit
PCM_OP_ACT_POL_EVENT_NOTIFY	Inactivating Accounts that Exceed a Specified Limit Scheduling Deferred Actions
PCM_OP_ACT_POL_SPEC_VERIFY	Authenticating User Actions Customizing Authentication Checks Enabling Duplicate Session Checking
PCM_OP_ACT_POL_VALIDATE_SCHEDULE	Performing Policy Checks before Scheduling Deferred Actions
PCM_OP_ACT_SCHEDULE_CREATE	Scheduling Deferred Actions
PCM_OP_ACT_SCHEDULE_DELETE	Deleting Deferred Actions
PCM_OP_ACT_SCHEDULE_EXECUTE	Executing Deferred Actions Scheduling Deferred Actions About Deferred Actions When Using PCM_OP_CUST_SET_STATUS
PCM_OP_ACT_SCHEDULE_MODIFY	Modifying Deferred Actions
PCM_OP_ACT_VERIFY	Implementing Password Encryption
PCM_OP_ADU_POL_DUMP	Customizing the Account Dump Utility (ADU)
PCM_OP_ADU_POL_VALIDATE	Customizing the Account Dump Utility (ADU)
PCM_OP_ADU_VALIDATE	Customizing the Account Dump Utility (ADU)
PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE	Getting Life Cycle States
PCM_OP_BILL_GROUP_ADD_MEMBER	Adding Accounts to Account Hierarchies Moving Accounts from One Account Hierarchy to Another
PCM_OP_BILL_GROUP_CREATE	Creating Account Hierarchies
PCM_OP_BILL_GROUP_DELETE	Deleting Account Hierarchies
PCM_OP_BILL_GROUP_DELETE_MEMBER	Deleting Accounts from Account Hierarchies
PCM_OP_BILL_GROUP_GET_CHILDREN	Getting a List of Child Accounts in an Account Hierarchy
PCM_OP_BILL_GROUP_GET_PARENT	Finding the Parent of an Account Hierarchy
PCM_OP_BILL_GROUP_MOVE_MEMBER	Scheduling Deferred Actions
PCM_OP_BILL_MAKE_BILL_NOW	Canceling a Service Group
PCM_OP_CUST_ACCTINFO	Customizing Automatic Account Creation (AAC) Information
PCM_OP_CUST_AMEND_CREDITOR_INFO	Amending Creditor Information Updating a Mandate
PCM_OP_CUST_AMEND_MANDATE	Amending a Mandate Updating a Mandate
PCM_OP_CUST_CANCEL_MANDATE	Canceling a Mandate Canceling a Mandate
PCM_OP_CUST_CHANGE_BUSINESS_PROFILE	Changing a Bill Unit's Business Profile
PCM_OP_CUST_COMMIT_CUSTOMER	Creating Accounts Adding Custom Account Creation Steps Before the Account Is Committed Adding Custom Account Creation Steps After the Account Is Committed Sending Account Information to Your Application when an Account is Created Selecting a Database Schema Customizing Login Names Creating Accounts with Backdated Services or Balances Creating Customer's Collections Profiles at the Time of Customer Account Creation Creating a Service Group Configuring Extended Rating Attributes for a Service Group Associating a Device with a Service Group Assigning Bill Units to Business Profiles Transaction Handling During Account Creation
PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE	Creating Business Profiles
PCM_OP_CUST_CREATE_BAL_GRP	Creating Accounts
PCM_OP_CUST_CREATE_BILLINFO	Creating Accounts Creating Business Profiles
PCM_OP_CUST_CREATE_CUSTOMER	Creating Accounts Creating a Service Group
PCM_OP_CUST_CREATE_PAYINFO	Customizing Customer Payment Information Creating Accounts CVV2/CID Fraud Prevention Functionality Registering a Mandate
PCM_OP_CUST_CREATE_PROFILE	Creating Accounts Managing and Customizing Profiles
PCM_OP_CUST_CREATE_SERVICE	Creating Services Creating Accounts
PCM_OP_CUST_DELETE_ACCT	Deleting Accounts
PCM_OP_CUST_DELETE_PAYINFO	Customizing Customer Payment Information Canceling a Mandate Canceling a Mandate
PCM_OP_CUST_DELETE_PROFILE	Managing and Customizing Profiles
PCM_OP_CUST_FIND	Finding Accounts
PCM_OP_CUST_FIND_PROFILE	Retrieving Account Profile Information
PCM_OP_CUST_GET_BUSINESS_PROFILE_INFO	Getting Information about a Business Profile
PCM_OP_CUST_GET_LIFECYCLE_STATES	Getting Life Cycle States
PCM_OP_CUST_INIT_SERVICE	Creating Services Customizing Automatic Account Creation (AAC) Information
PCM_OP_CUST_MODIFY_CUSTOMER	Modifying an Account Sending Account Information to Your Application when an Account is Modified Creating a Service Group Configuring Extended Rating Attributes for a Service Group Associating a Device with a Service Group Transferring Service Groups between Accounts in Different Schemas
PCM_OP_CUST_MODIFY_PAYINFO	Customizing Customer Payment Information CVV2/CID Fraud Prevention Functionality
PCM_OP_CUST_MODIFY_PROFILE	Managing and Customizing Profiles
PCM_OP_CUST_MODIFY_SERVICE	Modifying Services Changing a Bill Unit's Business Profile
PCM_OP_CUST_POL_COMPARE_PASSWD	Implementing Password Encryption
PCM_OP_CUST_POL_DECRYPT_PASSWD	Implementing Password Encryption
PCM_OP_CUST_POL_ENCRYPT_PASSWD	Implementing Password Encryption Creating Passwords
PCM_OP_CUST_POL_EXPIRATION_PASSWD	Customizing Password Expiration
PCM_OP_CUST_POL_GET_CONFIG	Sending Account Information to Your Application when an Account is Created
PCM_OP_CUST_POL_GET_DB_LIST	Getting a List of Database Schemas Selecting a Database Schema
PCM_OP_CUST_POL_GET_DB_NO	Getting a List of Database Schemas Selecting a Database Schema
PCM_OP_CUST_POL_GET_INTRO_MSG	Customizing the Introductory Message
PCM_OP_CUST_POL_GET_POPLIST	Returning a Point-of-Presence (POP) List
PCM_OP_CUST_POL_POST_COMMIT	Adding Custom Account Creation Steps After the Account Is Committed Creating Accounts Customizing the Introductory Message Sending the Introductory Message
PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER	Modifying an Account Sending Account Information to Your Application when an Account is Modified
PCM_OP_CUST_POL_PRE_COMMIT	Adding Custom Account Creation Steps Before the Account Is Committed Creating Accounts
PCM_OP_CUST_POL_PRE_DELETE_PAYINFO	Customizing Customer Payment Information
PCM_OP_CUST_POL_PREP_AACINFO	Customizing Automatic Account Creation (AAC) Information
PCM_OP_CUST_POL_PREP_ACCTINFO	Customizing Account Numbers
PCM_OP_CUST_POL_PREP_INHERITED	Creating Services
PCM_OP_CUST_POL_PREP_LOCALE	Customizing Locale Information
PCM_OP_CUST_POL_PREP_LOGIN	Customizing Login Names Requiring Login Names for Email and Broadband Services Creating Logins for Prepaid Services Creating Logins for Email Services
PCM_OP_CUST_POL_PREP_NAMEINFO	Customizing Name and Address Information
PCM_OP_CUST_POL_PREP_PASSWD	Creating Passwords
PCM_OP_CUST_POL_PREP_PAYINFO	Customizing Payment Method Data Preparation Specifying the Payment Processor Vendor
PCM_OP_CUST_POL_PREP_PROFILE	Managing and Customizing Profiles
PCM_OP_CUST_POL_PREP_STATUS	Customizing Status Changes
PCM_OP_CUST_POL_VALID_AACINFO	Customizing Automatic Account Creation (AAC) Information
PCM_OP_CUST_POL_VALID_ACCTINFO	Customizing Account Numbers
PCM_OP_CUST_POL_VALID_LOCALE	Customizing Locale Information
PCM_OP_CUST_POL_VALID_LOGIN	Customizing Login Names Requiring Login Names for Email and Broadband Services Creating Logins for Prepaid Services
PCM_OP_CUST_POL_VALID_NAMEINFO	Customizing Name and Address Information Creating Custom Country Aliases
PCM_OP_CUST_POL_VALID_PASSWD	Creating Passwords
PCM_OP_CUST_POL_VALID_PAYINFO	Customizing Payment Method Validation Verifying the Maximum Number of CVV2 Digits Registering a Mandate
PCM_OP_CUST_POL_VALID_PROFILE	Managing and Customizing Profiles Configuring Extended Rating Attributes for a Service Group
PCM_OP_CUST_POL_VALID_STATUS	Customizing Status Changes
PCM_OP_CUST_PREP_CUSTOMER	Creating Accounts
PCM_OP_CUST_SET_ACCTINFO	Customizing Account Numbers
PCM_OP_CUST_SET_ASSOCIATED_BUS_PROFILE	Assigning Bill Units to Business Profiles
PCM_OP_CUST_SET_BAL_GRP	Assigning Bill Units to Business Profiles
PCM_OP_CUST_SET_BILLINFO	Transferring Service Groups between Accounts in the Same Schema Assigning Bill Units to Business Profiles
PCM_OP_CUST_SET_DISCOUNT_STATUS	Backdating Status Changes
PCM_OP_CUST_SET_LOCALE	Customizing Locale Information
PCM_OP_CUST_SET_LOGIN	Customizing Login Names Modifying Services
PCM_OP_CUST_SET_NAMEINFO	Managing Name and Address Information Creating Accounts
PCM_OP_CUST_SET_PASSWD	Creating Passwords Modifying Services
PCM_OP_CUST_SET_PAYINFO	Customizing Customer Payment Information Registering a Mandate Transferring Service Groups between Accounts in the Same Schema
PCM_OP_CUST_SET_PRODUCT_STATUS	Backdating Status Changes
PCM_OP_CUST_SET_STATUS	Changing the Status of an Account, Bill Unit, or Service Customizing Status Changes Inactivating Accounts that Exceed a Specified Limit Backdating Status Changes Creating Accounts Modifying Services Getting Life Cycle States
PCM_OP_CUST_SETUP_TOPUP	Creating Accounts
PCM_OP_CUST_UPDATE_CUSTOMER	Modifying an Account Changing a Bill's Payment Method Customizing Customer Payment Information
PCM_OP_CUST_UPDATE_SERVICES	Modifying Services Changing the Status of an Account, Bill Unit, or Service Backdating Status Changes Getting Life Cycle States Associating a Device with a Service Group Canceling a Service Group Transferring Service Groups between Accounts in Different Schemas
PCM_OP_CUST_VALIDATE_CUSTOMER	Customizing Login Names Customizing Passwords Managing and Customizing Profiles Customizing Payment Method Data Preparation Customizing Payment Method Validation
PCM_OP_DELIVERY_MAIL_SENDMSGS	Sending the Introductory Message
PCM_OP_DEVICE_ASSOCIATE	Associating a Device with a Service Group Creating Services Modifying Services
PCM_OP_GROUP_ADD_MEMBER	Managing ACL Groups
PCM_OP_MAIL_DELIV_VERIFY	Customizing Authentication Checks
PCM_OP_MAIL_LOGIN_VERIFY	Customizing Authentication Checks
PCM_OP_PERM_ACL_GROUP_ADD_MEMBER	Managing ACL Groups
PCM_OP_PERM_ACL_GROUP_CREATE	Managing ACL Groups
PCM_OP_PERM_ACL_GROUP_DELETE	Managing ACL Groups
PCM_OP_PERM_ACL_GROUP_DELETE_MEMBER	Managing ACL Groups
PCM_OP_PERM_ACL_GROUP_MODIFY	Managing ACL Groups
PCM_OP_PERM_FIND	Finding CSR Membership
PCM_OP_PUBLISH_GEN_PAYLOAD	Adding Members to a Profile Sharing Group
PCM_OP_PYMT_CHARGE	CVV2/CID Fraud Prevention Functionality
PCM_OP_PYMT_COLLECT	Creating Accounts
PCM_OP_PYMT_GET_ACH_INFO	Customizing Account Creation Charges
PCM_OP_PYMT_POL_SPEC_COLLECT	Customizing Account Creation Charges
PCM_OP_PYMT_POL_SPEC_VALIDATE	Creating Accounts Customizing the Account Used for Credit Card Validation
PCM_OP_PYMT_VALIDATE	Creating Accounts
PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION	Canceling a Service Group
PCM_OP_SUBSCRIPTION_CYCLE_ARREARS	Creating Accounts with Backdated Services or Balances
PCM_OP_SUBSCRIPTION_CYCLE_FORWARD	Creating Accounts with Backdated Services or Balances
PCM_OP_SUBSCRIPTION_ORDERED_BALGRP	Deleting Members and Profiles from a Profile Sharing Group Deleting a Profile Sharing Group
PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY	Adding Members to a Profile Sharing Group
PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS	Adding Members to a Profile Sharing Group
PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_SERVICE	Adding Members to a Profile Sharing Group
PCM_OP_SUBSCRIPTION_POL_POST_TRANSFER_SUBSCRIPTION	Transferring Service Groups between Accounts in the Same Schema Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS	Creating a Profile Sharing Group Validating Profile Sharing Group Members
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL	Creating Accounts
PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER	Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO	Transferring Service Groups between Accounts in the Same Schema Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_SET_PRODINFO	Transferring Service Groups between Accounts in the Same Schema Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE	Creating a Profile Sharing Group Validating Profile Sharing Group Members
PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE	Deleting Members and Profiles from a Profile Sharing Group Deleting a Profile Sharing Group Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY	Modifying a Profile Sharing Group Validating Profile Sharing Group Members Adding Profiles to a Profile Sharing Group Deleting Members and Profiles from a Profile Sharing Group
PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT	Changing the Owner of a Profile Sharing Group
PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION	Transferring Service Groups between Accounts in the Same Schema Transferring Service Groups between Accounts in Different Schemas
PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY	Creating Accounts
PCM_OP_TCF_PROV_CREATE_SVC_ORDER	Adding Members to a Profile Sharing Group

About Account Locking

Some transactional process require that an account is locked to maintain data integrity. For these operations, the account is locked and unlocked automatically. When an account is locked, no other opcode can perform operations on the account.

Transaction Handling During Account Creation

When you use PCM_OP_CUST_COMMIT_CUSTOMER, the value of its PIN_FLD_TXN_FLAGS input flist field determines how it handles transactions:

• When set to 1, PCM_OP_CUST_COMMIT_CUSTOMER opens its own transaction because it authorizes credit cards. Operations related to credit card authorization require that the operation never be rolled back. As soon as the credit card authorization occurs, the transaction is committed before the opcode finishes its operation, making the transaction independent of the operations after the commit.

  This is the default when JCA Resource Adapter is not in XA Transaction mode or when PCM_OP_CUST_COMMIT_CUSTOMER is not called by JCA Resource Adapter.

  Note:

  After credit card authorization, if errors occur in the account creation processes, an account might be partially created.

• When set to 2, PCM_OP_CUST_COMMIT_CUSTOMER does not open its own transaction. Instead, it supports global transactions opened by a global transaction manager.

  When JCA Resource Adapter is in XA Transaction mode and receives a request to call PCM_OP_CUST_COMMIT_CUSTOMER, one of the following occurs:

  • If the input flist contains the PIN_FLD_TXN_FLAGS field set to 2, the adapter calls the opcode in the usual manner.

  • If the PIN_FLD_TXN_FLAGS field is missing, the adapter adds the field to the flist and sets it to 2 before calling the opcode.

  • If the PIN_FLD_TXN_FLAGS field is set to any value other than 2, the adapter rejects the opcode with the PIN_ERR_BAD_VALUE error for the PIN_FLD_TXN_FLAGS field.

  Note:

  To enable PCM_OP_CUST_COMMIT_CUSTOMER to support transactions opened by a global transaction manager, the PIN_FLD_TXN_FLAGS field must be set to 2.

PCM_OP_CUST_COMMIT_CUSTOMER returns an error in the following situations:

• A transaction is already open when PCM_OP_CUST_COMMIT_CUSTOMER tries to open a transaction.

• The input flist PIN_FLD_TXN_FLAGS field is set to any value other than 2 when JCA Resource Adapter receives a request to call PCM_OP_CUST_COMMIT_CUSTOMER in XA Transaction mode. For information about the adapter's transaction modes, see BRM JCA Resource Adapter guide.

Creating Accounts

The recommended opcode for creating accounts is PCM_OP_CUST_COMMIT_CUSTOMER. This is a wrapper opcode that performs all the tasks necessary to create an account.

For backward compatibility, use the PIN_FLD_VERSION input field to support an older version of BRM. See the discussion about supporting an older version of BRM in BRM Developer's Guide.

When you use PCM_OP_CUST_COMMIT_CUSTOMER, the account creation occurs in a transaction. This ensures that the account is created before sending the customer a welcome email. Using PCM_OP_CUST_COMMIT_CUSTOMER also creates a notification event that alerts ECE to a new account.

Note:

When PCM_OP_CUST_COMMIT_CUSTOMER is called by JCA Resource Adapter in XA Transaction mode, account creation occurs in a transaction started by a global transaction manager.

The account creation process is:

1. PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_CREATE_CUSTOMER.

   No validation is performed by PCM_OP_CUST_CREATE_CUSTOMER prior to attempting the actual creations, so invalid or missing data results in an ebuf error to be returned along with an output flist describing the validation problem, if one exists. In general, the PCM_OP_CUST_CREATE_CUSTOMER input flist should be taken from the output of a call to PCM_OP_CUST_PREP_CUSTOMER to ensure the fields have been properly validated.

   If you use rerating, use PCM_OP_CUST_COMMIT_CUSTOMER to create accounts. Do not call PCM_OP_CUST_CREATE_CUSTOMER directly. PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_POL_PRE_COMMIT, and based on that, the /profile/event_ordering object is created, which is used for rerating. If you use PCM_OP_CUST_CREATE_CUSTOMER directly to create accounts, the /profile/event_ordering object is not created.

2. PCM_OP_CUST_CREATE_CUSTOMER calls PCM_OP_CUST_PREP_CUSTOMER to validate the account creation information.

3. PCM_OP_CUST_PREP_CUSTOMER follows all the steps for creating an account object but does not commit the object to the database:

   • Opens a transaction.

   • Creates an /account object.

   • Sets account credit limits.

   • Purchases a bundle.

   • Creates a /service object.

     If the bundle purchased for the account is a required bundle, the /service object's PIN_FLD_TYPE value is set to PIN_BILL_SERVICE_REQUIRED. This establishes the service as a required service in the account.

   If PCM_OP_CUST_PREP_CUSTOMER is unsuccessful in any of these operations, it exits and calls a base opcode to cancel the transaction. This ensures that no changes are made to the database.

   If PCM_OP_CUST_PREP_CUSTOMER successfully validates the account creation data, it calls a base opcode to cancel the transaction, ensuring that the customer objects are not created, and then returns the validated account creation information in the output flist to PCM_OP_CUST_CREATE_CUSTOMER.

   If PCM_OP_CUST_PREP_CUSTOMER cannot open a local transaction, or a transaction is already open, the transaction is stopped and PCM_OP_CUST_PREP_CUSTOMER exits without validating the account creation information.

   In addition, PCM_OP_CUST_PREP_CUSTOMER calls PCM_OP_PYMT_POL_SPEC_VALIDATE to determine whether a customer's payment information needs to be validated during account creation. If validation is required, PCM_OP_CUST_PREP_CUSTOMER calls PCM_OP_PYMT_VALIDATE to perform the operation. If validation fails, the results are transformed to be consistent with the results used to describe account creation failure results and are then returned on the output flist. See "Processing Paymentech Address Validation Return Codes".

4. If the data is valid, PCM_OP_CUST_CREATE_CUSTOMER calls an internal opcode to create the /account object.

   The internal opcode creates a generic /account object. The account is constructed in the following actions, all of which are performed inside the transaction started by PCM_OP_CUST_COMMIT_CUSTOMER or the global transaction manager. To create the account, PCM_OP_CUST_COMMIT_CUSTOMER does the following:

   • Calls PCM_OP_CUST_CREATE_BILLINFO to create one or more bill units (/billinfo objects) and propagates the bill unit with billing information.

   • Calls PCM_OP_CUST_CREATE_BAL_GRP to create one or more /balance_group objects and link the balance groups to the account and the appropriate bill unit.

   • Calls PCM_OP_CUST_CREATE_PAYINFO to create a /payinfo object and link the payment information to the appropriate bill unit.

   • Calls PCM_OP_CUST_CREATE_PROFILE to create a /profile object if the input flist contains profile information.

   • Calls PCM_OP_CUST_SET_NAMEINFO to set the contact information.

   • Calls PCM_OP_CUST_SETUP_TOPUP to set up top-up information, if any, for the account.

   • Calls PCM_OP_CUST_SET_STATUS to set the account status to active.

5. PCM_OP_CUST_CREATE_CUSTOMER calls PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY to validate that the bundles passed from the input flist do not violate any bundle dependencies.

6. PCM_OP_CUST_CREATE_CUSTOMER calls PCM_OP_CUST_CREATE_SERVICE to create /service objects.

7. PCM_OP_CUST_CREATE_CUSTOMER calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase bundles.

   When calling PCM_OP_SUBSCRIPTION_PURCHASE_DEAL, PCM_OP_CUST_CREATE_CUSTOMER populates the PIN_FLD_DEAL_INFO field in the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL input flist only when the following is true for the input flist of PCM_OP_CUST_CREATE_CUSTOMER:

   • At the PIN_FLD_ACCTINFO level:

     • PIN_FLD_DEAL_OBJ is not populated.

     • PIN_FLD_DEAL_INFO is populated, including the PIN_FLD_PRODUCTS array and its PIN_FLD_STATUS field.

   • At the PIN_FLD_SERVICES level:

     • PIN_FLD_DEAL_OBJ is not populated.

     • PIN_FLD_DEAL_INFO field is populated, including the PIN_FLD_PRODUCTS array and its PIN_FLD_STATUS field.

   • At the PIN_FLD_SERVICES > PIN_FLD_DEALS level:

     • PIN_FLD_DEAL_OBJ is not populated.

     • PIN_FLD_DEAL_INFO field is populated, including the PIN_FLD_PRODUCTS array and its PIN_FLD_STATUS field.

8. PCM_OP_CUST_COMMIT_CUSTOMER creates the customer's collections profile at the time of customer account creation.

9. Before committing the transaction, PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_POL_PRE_COMMIT.

10. After committing the transaction, PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_POL_POST_COMMIT. See "Adding Custom Account Creation Steps After the Account Is Committed".

11. PCM_OP_CUST_COMMIT_CUSTOMER:

    • Passes credit card in "Adding Custom Account Creation Steps Before the Account Is Committed" formation to PCM_OP_PYMT_VALIDATE and PCM_OP_PYMT_COLLECT, which collect any credit card payments charged at account creation and validate the credit card information returned by the payment processor.

    • If you use multiple schemas, creates the /uniqueness object.

    • Calls PCM_OP_CUST_POL_GET_CONFIG to get information used by client applications. See "Sending Account Information to Your Application when an Account is Created".

    • Calls PCM_OP_CUST_SET_BAL_GRP to create balance groups, set credit limits, and set sub-balance consumption rules. See "How BRM Handles Consumption Rules and Credit Limits".

      Note:

      By default, BRM does not log events that do not have a balance impact. You can specify to log all account-creation events. See "Logging Noncurrency Events" in BRM System Administrator's Guide.

Customizing Account Numbers

Use PCM_OP_CUST_POL_PREP_ACCTINFO and PCM_OP_CUST_POL_VALID_ACCTINFO to customize the account number format.

PCM_OP_CUST_POL_VALID_ACCTINFO validates the fields that are required to create or modify an account based on the input from the calling opcode. This opcode is called by PCM_OP_CUST_POL_PREP_ACCTINFO when an account is being created or modified. If the mandatory fields are not passed in, PCM_OP_CUST_POL_VALID_ACCTINFO reports an error.

PCM_OP_CUST_POL_VALID_ACCTINFO is an empty hook.You must modify this opcode only for special situations.

To run these opcodes, PCM_OP_CUST_SET_ACCTINFO initializes an /account object with generic fields passed in on the input flist. PCM_OP_CUST_SET_ACCTINFO calls PCM_OP_CUST_POL_PREP_ACCTINFO and PCM_OP_CUST_POL_VALID_ACCTINFO to prepare and validate account information, and returns the account number based on the customizations made in the opcodes.

Customizing the Introductory Message

You can customize how to choose an introductory message and how to send it:

• To choose the message, use PCM_OP_CUST_POL_GET_INTRO_MSG. The type of account and package selected are passed to the operation on the input flist. This enables different introductory messages to be returned based on the values of these fields. The introductory message is returned on the output flist as an uninterpreted buffer of data. This enables the introductory message to include HTML, graphics, and other complex information.

  PCM_OP_CUST_POL_GET_INTRO_MSG is not called by any opcode.

• To send the message, use PCM_OP_CUST_POL_POST_COMMIT.

PCM_OP_CUST_POL_GET_INTRO_MSG reads the message from the file specified in the CM pin.conf file intro_dir entry.

PCM_OP_CUST_POL_GET_INTRO_MSG returns the introductory message as an uninterpreted buffer of data. This allows the introductory message to include HTML, graphics, and other complex information.

The subject line for the welcome email message is by default “Welcome to the Internet." To change this, edit the PCM_OP_CUST_POL_POST_COMMIT policy opcode.

In each introductory message, a parameter substitution system enables the message to contain values that are specific to this customer, such as the name of the package they chose to purchase. For example, the following enables you to substitute a package name and a promotional code:

You are requesting to purchase the ${price_plan} package via the ${promo_code} promo code.

The package name and promotional code substitution is handled by the following code in PCM_OP_CUST_POL_GET_INTRO_MSG:

/*************************************************************
 * Package Name
 *************************************************************/

if  (strcasecmp( macro, "price_plan")==0) {
valp = NULL;
valp = (char *)PIN_FLIST_FLD_GET( in_flistp, 
PIN_FLD_AAC_PACKAGE, 0, ebufp);
if(valp) fm_cust_pol_buf_cat( bufp, valp, ebufp);
}

/*************************************************************
 * Promo Code
 *************************************************************/

else if (strcasecmp( macro, "promo_code")==0) {
valp = NULL;
valp = (char *)PIN_FLIST_FLD_GET( in_flistp, 
PIN_FLD_AAC_PROMO_CODE, 0, ebufp);
if(valp) fm_cust_pol_buf_cat( bufp, valp, ebufp);
}

Sending the Introductory Message

PCM_OP_CUST_POL_POST_COMMIT uses the Email DM PCM_OP_DELIVERY_MAIL_SENDMSGS opcode to send a welcoming message. PCM_OP_DELIVERY_MAIL_SENDMSGS in turn calls the Email DM PCM_OP_CREATE_OBJ.

Customizing Account Creation Charges

By default, BRM collects cycle forward and purchase fees on account creation for credit card customers. Use PCM_OP_PYMT_POL_SPEC_COLLECT to customize whether to charge the customer immediately for all or part of the current account balances during account creation or to defer the charges to a later date. You can also specify whether to validate the charges.

The only type of action that can trigger this opcode is create customer. If this is not passed in, PIN_ERR_BAD_VALUE is returned.

PCM_OP_PYMT_POL_SPEC_COLLECT checks all the account balance groups and specifies the amount for each bill unit (/billinfo object).

• The PIN_FLD_BILLINFO_OBJ field in the input flist specifies the bill unit associated with the payment.

• The PIN_FLD_ITEMS array in the output flist specifies a list of open items to be paid.

• If the pay type is _dd, then it determines from the pin.conf file whether to validate, and then validates the account with Paymentech.

PCM_OP_PYMT_POL_SPEC_COLLECT then calls PCM_OP_PYMT_GET_ACH_INFO to retrieve the Automated Clearing House (ACH) information.

Note:

PCM_OP_PYMT_GET_ACH_INFO retrieves ACH information from the /config/ach object. It uses the ACH vendor name or element ID in the input flist to determine which element in the ACH_INFO array should be used.

BRM supports direct debit transactions from checking accounts only.

You can disable the default logic for PCM_OP_PYMT_POL_SPEC_COLLECT by changing the value of the cc_collect or dd_collect entry in the CM pin.conf configuration file. Change the value from 1 (enabled) to 0 (disabled).

Creating Multiple Accounts in One Transaction

You can create multiple BRM accounts in one transaction with JCA Resource Adapter. This is useful, for example, when a single order in Oracle Communications Order and Service Management (OSM) produces multiple new customers. It enables Oracle Application Integration Architecture (Oracle AIA) to maintain the cross-references between the OSM order and its associated BRM accounts.

Creating Accounts with Backdated Services or Balances

By default, BRM does not allow accounts to be created with the services or balances creation dates backdated beyond the account or service creation date.

When you backdate the account creation, the account becomes effective as of the new backdated date. BRM does the following:

• Sets the PIN_FLD_EFFECTIVE_T field in the /account object to the backdated date.

• Sets the purchase, usage, or cycle start date to the backdated date unless these dates are explicitly set to a different date.

• Sets the billing day of month (DOM) to the backdated date unless the actg_dom entry in the Connection Manager (CM) configuration file (pin.conf) is used.

BRM does not allow backdating the account creation to a date prior to the general ledger (G/L) posting date.

To backdate an account's creation time, pass the backdate time in the PIN_FLD_END_T field of PCM_OP_CUST_COMMIT_CUSTOMER. The value of PIN_FLD_END_T is copied to the PIN_FLD_EFFECTIVE_T field internally and is then passed to the appropriate opcodes to complete the account creation process.

When you backdate account creation, you also backdate the charge offer purchase. If the charge offer includes cycle fees, BRM uses PCM_OP_SUBSCRIPTION_CYCLE_FORWARD and PCM_OP_ SUBSCRIPTION_CYCLE_ARREARS to calculate cycle forward and cycle arrears fees for the subscription operations.

When you backdate the creation of an account that has cycle forward events, the cycle forward fee is applied for the first cycle just as it would be if the account were to be created on the backdated date. The remaining cycles, until the current cycle, are charged only during the next bill run.

You can create accounts with the services or balances creation date backdated beyond the account or service creation date by running the pin_bus_params utility to change the SubsDis74BackDateValidations business parameter. For information about this utility, see BRM Developer's Guide.

To create accounts with backdated services or balances:

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

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

   pin_bus_params -r BusParamsSubscription bus_params_subscription.xml
   

3. In the file, change disabled to enabled:

   <SubsDis74BackDateValidations>enabled</SubsDis74BackDateValidations>
   

4. Save the file as bus_params_subscription.xml.

5. Load the XML file into the BRM database:

   pin_bus_params bus_params_subscription.xml
   

6. Stop and restart the CM.

7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see BRM System Administrator's Guide.

Creating Customer's Collections Profiles at the Time of Customer Account Creation

BRM uses PCM_OP_CUST_COMMIT_CUSTOMER to create a customer's collections profile at the time of customer account creation.

As input, this opcode takes /profile/collections_params as the Portal object ID (POID) type in the PIN_FLD_PROFILE_OBJ field and the collections parameter details in the PIN_FLD_COLLECTIONS_PARAMS array to create the collections profile. This opcode uses the PIN_FLD_BILLINFO_ID field to identify the bill unit in case of multiple bill units.

Customizing Automatic Account Creation (AAC) Information

To validate automatic account creation data, BRM uses PCM_OP_CUST_POL_PREP_AACINFO and PCM_OP_CUST_POL_VALID_AACINFO.

For example, when registering customers, you can offer different packages to different customers by having customers enter account creation numbers. You can also assign account creation numbers to customers to track marketing information. To specify how to validate account creation numbers, edit the PCM_OP_CUST_POL_VALID_AACINFO policy opcode.

PCM_OP_CUST_POL_PREP_AACINFO prepares automatic account creation (AAC) data for validation. This opcode takes the AAC fields for an /account and /service object during customer account creation and processes them as necessary to prepare for validation. This opcode can be used to prepare ACC info for online account creation.This opcode is an empty hook.

This opcode is called by PCM_OP_CUST_INIT_SERVICE and PCM_OP_CUST_ACCTINFO.

See BRM Developer's Reference guide.

Adding Custom Account Creation Steps Before the Account Is Committed

To run additional steps before an account is committed, use PCM_OP_CUST_POL_PRE_COMMIT.

PCM_OP_CUST_POL_PRE_COMMIT is called by PCM_OP_CUST_COMMIT_CUSTOMER just after the /account and /service objects have been created and initialized but before the transaction containing those operations has been committed. Therefore, PCM_OP_CUST_POL_PRE_COMMIT cannot alter the /account and /service objects, but it can cancel the account creation process by returning an ebuf error. Therefore, you can include tests that the customer must pass before proceeding.

The entire account creation flist is passed in the input flist so any information about the customer can be used in interacting with the external or legacy system.

No information is returned as output parameters. Unless an error is returned, account creation continues as expected.

PCM_OP_CUST_POL_PRE_COMMIT is an empty hook.

Adding Custom Account Creation Steps After the Account Is Committed

To run additional steps after the account is committed, use PCM_OP_CUST_POL_POST_COMMIT.

PCM_OP_CUST_POL_POST_COMMIT is called by PCM_OP_CUST_CREATE_CUSTOMER just after the transaction containing the creation and initialization of the /account and /service objects has been committed.

PCM_OP_CUST_POL_POST_COMMIT takes the entire account creation flist as its input flist so any information about the customer can be used to interact with an external or legacy system. This opcode cannot alter the account creation data used to create the customer. Because the transaction creating the customer objects has already been committed, this operation cannot prevent or alter the account creation process in any way. If an ebuf error is returned by PCM_OP_CUST_POL_POST_COMMIT, it is ignored by PCM_OP_CUST_CREATE_CUSTOMER.

No information is returned as output parameters.

Integrating BRM With an External Account Creation Application

See the following topics:

• Sending Account Information to Your Application when an Account is Created

• Sending Account Information to Your Application when an Account is Modified

Sending Account Information to Your Application when an Account is Created

To send account information to your application after the account is created, use PCM_OP_CUST_POL_GET_CONFIG. This opcode is called by PCM_OP_CUST_COMMIT_CUSTOMER after customer account creation has been successfully performed to specify the configuration data that should be returned to the client software.

PCM_OP_CUST_POL_GET_CONFIG allows configuration information, such as news server address or mail server address, to be determined dynamically.

Input parameters include the POID of the account object that was created by the account creation. Output parameters include all configuration fields and values that should be returned to the client software.

The default implementation supports different sets of configuration information based on the value of the aac_source field from the customer account creation data. The list of configuration fields is stored in a text file in a configurable directory.

Sending Account Information to Your Application when an Account is Modified

To send account information to your application after a service is purchased, use PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER. This opcode is called by PCM_OP_CUST_MODIFY_CUSTOMER.

PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER provides a mechanism to export customer data to an external or legacy system for processing when new services have been added to existing customers.

PCM_OP_CUST_MODIFY_CUSTOMER calls PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER just after the transaction containing the creation and initialization of the new /service object associated with the add-on package has been committed. The input flist contains all of the same information as the PCM_OP_CUST_MODIFY_CUSTOMER input flist, thereby allowing any information about the customer to be used by the external or legacy system. Because the transaction creating the customer /service object has already been committed, PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER cannot alter the customer data or prevent or alter the customer modification process in any way. If an error is returned by PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER, it is ignored by PCM_OP_CUST_MODIFY_CUSTOMER.

Returning a Point-of-Presence (POP) List

To get an account creation point-of-presence (POP) list, use PCM_OP_CUST_POL_GET_POPLIST.

This opcode retrieves either the best POP for a registering customer to call or the entire list of POPs so the customer can choose one. Both approaches are supported because some account creation models do not supply the customer phone number when retrieving the POP list, so no automatic matching can be done. If no phone number is supplied, the entire POP list is returned.

If the application requires the entire POP list, then all that is required on the input flist is the PIN_FLD_POID.

If the application is looking for the nearest POP based on location, the input flist requires the area code and prefix (or the ANI) in the PIN_FLD_ANI field and the PIN_FLD_POID field containing the database number where the POP tables reside.

The fields returned to the caller when a specific POP is needed are:

• PIN_FLD_PHONE

• PIN_FLD_CITY

• PIN_FLD_STATE

• PIN_FLD_ZIP

• PIN_FLD_FLAGS

The PIN_FLD_FLAGS field contains two flags:

• The POP_TOLL_FREE flag, if set, indicates whether the POP is a toll free call for the caller.

• The POP_DIAL_ONE flag, if set, indicates that the caller needs to dial 1 first when placing the call to the pop.

These flags are bit flags. To check if POP_DIAL_ONE is set, for example, the code would be:

if (flags & POP_DIAL_ONE) {
/*
** Action code.
*/
}

The fields returned to the caller when a list of POPs is requested is an array of POPs (PIN_FLD_POP) where each element contains fields:

• PIN_FLD_PHONE

• PIN_FLD_CITY

• PIN_FLD_STATE

• PIN_FLD_ZIP

The default implementation uses /pop objects in the database to determine the POP information to return. Applications are provided with BRM to load POP objects into the database for each POP in the network and to compute the best POP for each exchange in the U.S. based on phone call rating tables from a third party.

PCM_OP_CUST_POL_GET_POPLIST is not called by any opcode.

Creating Accounts in a Multischema System

In multischema systems, you can configure BRM to balance account loads among database schemas. You can use policy opcodes to customize how to select schemas during account creation. See the following topics:

• Getting a List of Database Schemas

• Selecting a Database Schema

Getting a List of Database Schemas

To get a list of database schemas defined in a multischema environment, use PCM_OP_CUST_POL_GET_DB_LIST. If you have schemas that you do not want included in the list of available schemas, you can customize this opcode to prevent them from being listed.

The default implementation returns the cached list of schema distributions created by PCM_OP_CUST_POL_GET_DB_NO during BRM initialization.

When BRM is set up as a multischema environment, the output flist contains a POID and the schema distributions array. In a single-schema environment, the output flist contains only the POID.

PCM_OP_CUST_POL_GET_DB_LIST is not called by any opcode.

Selecting a Database Schema

In a multischema system, the criteria for selecting a schema is set in the BRM_home/apps/multi_db/config_dist.conf file. See "Setting Database Schema Priorities" in BRM System Administrator's Guide. During account creation, PCM_OP_CUST_COMMIT_CUSTOMER calls PCM_OP_CUST_POL_GET_DB_LIST to select a schema for the new account.

You can customize the selection process by customizing PCM_OP_CUST_POL_GET_DB_NO.

Managing Name and Address Information

To add name and address information to a specific account object, use PCM_OP_CUST_SET_NAMEINFO. This opcode sets the fields of the PIN_FLD_NAMEINFO array of a specified /account object to the values specified in the input flist PIN_FLD_NAMEINFO array.

PCM_OP_CUST_SET_NAMEINFO does the following:

• Sets the billing address in the account's PIN_FLD_NAMEINFO array by using the PIN_NAMEINFO_BILLING element (element_id = PIN_NAMEINFO_BILLING = 1).

• Sets the mailing address (if needed) using the PIN_NAMEINFO_MAILING element (element_id = PIN_NAMEINFO_MAILING = 2).

  Note:

  Element IDs through 100 are reserved for BRM use.

BRM calls PCM_OP_CUST_SET_NAMEINFO as part of the process of creating an /account object.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_NAMEINFO creates an /event/customer/nameinfo object to record the details of the operation.

If the operation is successful, BRM returns the POID of the /event/customer/nameinfo object in the PIN_FLD_RESULTS array. If the operation fails, BRM returns a PIN_FLD_FIELDS array that specifies the failing field.

Customizing Name and Address Information

Use the following opcodes to customize name and address information:

• PCM_OP_CUST_POL_PREP_NAMEINFO

• PCM_OP_CUST_POL_VALID_NAMEINFO

See BRM Developer's Guide.

PCM_OP_CUST_SET_NAMEINFO calls PCM_OP_CUST_POL_PREP_NAMEINFO to prepare the customer information for validation and to determine whether the account being created is the BRM payment suspense account. If the country is not provided, it is assumed to be “USA" and “USA" is added as the country value. You can change the country parameter in the pin.conf file to insert any country when none is provided.

PCM_OP_CUST_POL_PREP_NAMEINFO checks the relevant /config/business_params object to determine whether payment suspense management is enabled. If so, it checks if the first name is “payment" and the last name is “suspense," which identifies it as a payment suspense account. If it exists, PCM_OP_CUST_POL_PREP_NAMEINFO retrieves the POID of the /config/psm object and passes it to PCM_OP_CUST_SET_NAMEINFO.

If it is the payment suspense account, PCM_OP_CUST_SET_NAMEINFO performs the following tasks:

• If the opcode provides a /config/psm object, PCM_OP_CUST_SET_NAMEINFO updates the PIN_FLD_ACCOUNTS array with the account POID for the payment suspense account being created.

• If the opcode provides a dummy POID, PCM_OP_CUST_SET_NAMEINFO creates the /config/psm object. It includes the account POID of the payment suspense account in the PIN_FLD_ACCOUNTS_ARRAY.

PCM_OP_CUST_SET_NAMEINFO then calls PCM_OP_CUST_POL_VALID_NAMEINFO to validate the information.

Customizing Locale Information

Use PCM_OP_CUST_SET_LOCALE to set the locale in an account. This opcode creates an /event/customer/locale object (or one inherited from it) to record the details of the operation.

You can use the PCM_OPFLG_CALC_ONLY flag to run the operation without creating the event object.

To customize how locales are set, use the following opcodes:

• To customize the creation of the locale, use PCM_OP_CUST_POL_PREP_LOCALE. This opcode is called by PCM_OP_CUST_SET_LOCALE. This opcode is an empty hook. See BRM Developer's Guide.

• To customize how to validate the locale, use PCM_OP_CUST_POL_VALID_LOCALE. See BRM Developer's Guide. PCM_OP_CUST_POL_VALID_LOCALE does the following:

  • Validates limit information for a service.

  • Confirms that the value of PIN_FLD_LOCALE in the input flist is one of the valid BRM locales.

Creating Custom Country Aliases

You can define custom values to represent countries by adding them to the country:alias list in the source code of PCM_OP_CUST_POL_VALID_NAMEINFO. This example shows three valid values for Angola: AO, Angola, and Ang.

"AO:AO",
"AO:Angola",
"AO:Ang"

After you edit this list, recompile the code to make your changes take effect.

Authenticating and Authorizing Customers

See the following topics:

• Customizing Login Names

• Requiring Login Names for Email and Broadband Services

• Creating Logins for Prepaid Services

• Creating Logins for Email Services

• Creating Passwords

• Authenticating Customers

Customizing Login Names

To set the login for an account, use PCM_OP_CUST_SET_LOGIN. This opcode sets the login field for a /service object to the value specified in the PIN_FLD_LOGINS array of the input flist.

If the PCM_OPFLG_READ_RESULT flag is set and the operation is successful, PCM_OP_CUST_SET_LOGIN returns all fields of the /event/customer/login object in the PIN_FLD_RESULTS array. Otherwise, only the POID of the event object is returned. If the operation is not successful, PCM_OP_CUST_SET_LOGIN returns the PIN_FLD_FIELDS array which specifies the failing field.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_LOGIN creates an /event/customer/login object to record the details of the operation.

Use the following opcodes to customize how login names are created. These opcodes are called by PCM_OP_CUST_SET_LOGIN.

• To prepare login names for validation, use PCM_OP_CUST_POL_PREP_LOGIN. This opcode takes the login field for a service object during customer account creation and processes it as necessary to prepare for validation. For example, you can add characters or change the case to all lowercase. This opcode is called by PCM_OP_CUST_COMMIT_CUSTOMER and PCM_OP_CUST_SET_LOGIN. See BRM Developer's Guide.

• To validate login names, use PCM_OP_CUST_POL_VALID_LOGIN (for example, to ensure that they have the required number of characters). This opcode takes the login field for a /service object during customer account creation or administrative update and validates it. This opcode is called by PCM_OP_CUST_SET_LOGIN, PCM_OP_CUST_COMMIT_CUSTOMER, and PCM_OP_CUST_VALIDATE_CUSTOMER. See BRM Developer's Guide.

  Caution:

  BRM requires unique login names for service types. BRM will not function properly if PCM_OP_CUST_POL_VALID_LOGIN is customized to allow nonunique login names.

  Note:

  BRM requires logins for services (they cannot be NULL). BRM requires that login names be unique. BRM will not function properly if PCM_OP_CUST_POL_VALID_LOGIN is customized to allow nonunique login names.

Requiring Login Names for Email and Broadband Services

By default, BRM requires all accounts that purchase email or broadband services to create a login name and password before they can proceed with the account creation or modification process. BRM enforces the login name requirement by using the following two opcodes:

• PCM_OP_CUST_POL_PREP_LOGIN converts all NULL login names to an empty string. For example, if the service type is /service/email and the opcode's PIN_FLD_LOGIN input flist field is set to NULL, the opcode changes the PIN_FLD_LOGIN flist field to "".

• PCM_OP_CUST_POL_VALID_LOGIN rejects all login names that are set to an empty string, because the validation process requires that all login names are at least one character in length.

To override this behavior and allow accounts to purchase email and broadband services without supplying a login name, customize PCM_OP_CUST_POL_PREP_LOGIN to skip the conversion of NULL login names to an empty string.

Creating Logins for Prepaid Services

For prepaid services, the login is generated automatically. The default login generated by PCM_OP_CUST_POL_PREP_LOGIN is a unique string composed of the database number, service name, and POID.

In cases where a prepaid service login is needed, such as Self-Care Manager, the customer's Mobile Station Integrated Services Digital Network (MSISDN) number is stored in the service object PIN_FLD_ALIAS_LIST array.

PCM_OP_CUST_POL_VALID_LOGIN enforces that a password for a service cannot be changed when the account is created or when a service is added. The password can be changed later.

Creating Logins for Email Services

For email services, PCM_OP_CUST_POL_PREP_LOGIN appends the domain entry in the CM configuration file (pin.conf) to the login. Passing in a domain name results in an error.

Creating Passwords

To add or change passwords, use PCM_OP_CUST_SET_PASSWD.

This opcode sets the PIN_FLD_PASSWD field for a specified /service object to the value specified in the PIN_FLD_PASSWORDS array of the input flist.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_PASSWD creates an /event/customer/password object to record the details of the operation.

Before setting the new password value, PCM_OP_CUST_SET_PASSWD calls the following opcodes to perform these operations:

• PCM_OP_CUST_POL_PREP_PASSWD, to process and prepare the new password for validation.

• PCM_OP_CUST_POL_VALID_PASSWD, to validate the password.

• PCM_OP_CUST_POL_ENCRYPT_PASSWD, to encrypt the password.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_PASSWD creates an /event/customer/password object to record the details of the operation.

If the password is successfully updated, the POID of the /event/customer/password object is returned in the PIN_FLD_RESULTS array. Otherwise, PCM_OP_CUST_SET_PASSWD returns the PIN_FLD_FIELDS array that specifies the failing fields.

Customizing Passwords

Use the following opcodes to customize passwords:

• To prepare account or service passwords for validation, use PCM_OP_CUST_POL_PREP_PASSWD. This opcode is called by PCM_OP_CUST_SET_PASSWD. PCM_OP_CUST_POL_PREP_PASSWD takes the password field for an /account or /service object during customer account creation and prepares it for validation.

  If a service password is passed in, the operation does nothing. If there is no password for a service, it generates one. A password is considered to be passed in if the PIN_FLD_PASSWD_CLEAR field is in the input flist, even if it is NULL.

• To validate account or service passwords, use PCM_OP_CUST_POL_VALID_PASSWD. This opcode is called by PCM_OP_CUST_SET_PASSWD and PCM_OP_CUST_VALIDATE_CUSTOMER. PCM_OP_CUST_POL_VALID_PASSWD takes the password field for an /account or /service object during customer account creation or administrative update and validates it. The default check is to make sure the password is not NULL and is less than 255 characters.

Implementing Password Encryption

Use the following opcodes to implement password encryption:

PCM_OP_CUST_POL_ENCRYPT_PASSWD encrypts a cleartext password based on the type of the account or service POID given and/or the requested encryption algorithm. The binary result is stored as an ASCII-like string to facilitate storage. All encryption requests from IP accounts get clear text encryption (to support Challenge Handshake Authentication Protocol, or CHAP). Advanced Encryption Standard (AES) or OZT encryption is used for all others. See "About Encrypting Passwords". This opcode is called by PCM_OP_CUST_SET_PASSWD and PCM_OP_CUST_POL_COMPARE_PASSWD.

PCM_OP_CUST_POL_COMPARE_PASSWD takes a cleartext password and an encrypted password from PCM_OP_CUST_POL_ENCRYPT_PASSWD and performs a comparison to check if the cleartext password was the source value of the encrypted password. The type of the /account or /service object whose password is being compared is included in the input flist, so the encryption mechanism can be varied for different object types. PCM_OP_CUST_POL_COMPARE_PASSWD returns true (match) or false (no match). PCM_OP_CUST_POL_COMPARE_PASSWD is used by BRM whenever a client application supplies a password to be authenticated against an /account or /service object. PCM_OP_CUST_POL_COMPARE_PASSWD is called by PCM_OP_ACT_VERIFY.

PCM_OP_CUST_POL_DECRYPT_PASSWD decrypts a cleartext password.

Creating Passwords for Prepaid Services

For prepaid services, the password is generated automatically. By default, PCM_OP_CUST_POL_PREP_PASSWD generates a random eight-character password, but you can customize the password algorithm.

Customizing Password Expiration

To customize password expiration, use PCM_OP_CUST_POL_EXPIRATION_PASSWD.

This opcode is called by PCM_OP_CUST_SET_PASSWD.

PCM_OP_CUST_POL_EXPIRATION_PASSWD calculates and sets the expiration date for the password. This opcode is called when the password status of a CSR account is set as Expires.

By default, PCM_OP_CUST_POL_EXPIRATION_PASSWD sets the password expiration date to 90 days.

To change the default password expiry duration, edit the passwd_age entry in the CM pin.conf file. For example, instead of 90 days you can set the expiration duration to 150 days.

If successful, PCM_OP_CUST_POL_EXPIRATION_PASSWD returns:

• PIN_FLD_POID: The POID of the /account object passed in.

• PIN_FLD_PASSWORD_EXPIRATION_T: The expiration date and time when the password expires.

Authenticating Customers

When customers log in, BRM first verifies the customer's login name and password and then performs a variety of checks (for example, when customers attempt to access a service or content offered by your company or a third-party provider).

• PCM_OP_ACT_FIND_VERIFY is the recommended opcode for authenticating customers. See "Authenticating User Actions".

• PCM_OP_ACT_FIND. See "Finding a Customer's Account Information".

• PCM_OP_ACT_POL_SPEC_VERIFY. See "Customizing Authentication Checks".

Authenticating User Actions

Use PCM_OP_ACT_FIND_VERIFY to verify a customer's identity and to perform authentication checks, such as verifying that the customer has good credit and an active account status.

PCM_OP_ACT_FIND_VERIFY takes as input a type-only POID, the action to verify, and the user's login and password. PCM_OP_ACT_FIND_VERIFY then:

1. Calls PCM_OP_ACT_FIND to retrieve the user's /account and /service objects. See "Finding a Customer's Account Information".

2. Calls PCM_OP_ACT_POL_SPEC_VERIFY to retrieve the list of authentication checks for the specified action. See "Customizing Authentication Checks".

3. Performs all authentication checks specified by the opcode.

4. Returns the following, depending on the success of the transaction:

   • If authentication succeeds, PCM_OP_ACT_FIND_VERIFY returns the POID of the service object and the PIN_FLD_RESULT field set to one of the following:

     –   0 to indicate a valid login and password.

     –   4 to indicate that the customer used a temporary password.

   • If authentication fails, PCM_OP_ACT_FIND_VERIFY returns PIN_FLD_RESULT set to one of the following:

     –   2 to indicate an incorrect password.

     –   5 to indicate that the customer used an expired password.

     –   6 to indicate that the password is no longer valid.

Customizing Authentication Checks

Use PCM_OP_ACT_POL_SPEC_VERIFY to specify the list of authentication checks to perform for each user action.

This opcode is called by PCM_OP_ACT_FIND_VERIFY to specify a list of checks used to authenticate user actions.The specified checks are then performed by standard opcodes.

Table 9-2 lists the available authentication checks:

Table 9-2 Default Authentication Checks

Authentication check	Enum value	Description
PIN_ACT_CHECK_UNDEFINED	0	None
PIN_ACT_CHECK_ACCT_TYPE	1	Check type of /account object.
PIN_ACT_CHECK_SRVC_TYPE	4	Check type of /service object.
PIN_ACT_CHECK_SRVC_STATUS	5	Check the service status. Can be active, inactive, or closed.
PIN_ACT_CHECK_SRVC_PASSWD	6	Confirm that the password is correct.
PIN_ACT_CHECK_CREDIT_AVAIL	7	Check the available credit.
PIN_ACT_CHECK_DUPE_SESSION	8	Check the open session count for the service. See "Enabling Duplicate Session Checking".

You can control the list of checks that each action requires and, to some extent, the behavior of the checks. Few authentication checks lend themselves to these behavior changes. Those that do can define a PIN_FLD_CHOICES array for the options.

The other fields present in an element of the checks array depend on which of the checks is specified by that element.

Table 9-3 shows the authentication checks that PCM_OP_ACT_POL_SPEC_VERIFY returns and their behavior:

Table 9-3 Authentications Checks Returned by PCM_OP_ACT_POL_SPEC_VERIFY

Action	Default authentication checks
PCM_OP_MAIL_DELIV_VERIFY	PIN_ACT_CHECK_SRVC_STATUS = active
PCM_OP_ACT_LOGIN	PIN_ACT_CHECK_SRVC_STATUS = active PIN_ACT_CHECK_SRVC_PASSWD PIN_ACT_CHECK_CREDIT_AVAIL = >=0
PCM_OP_MAIL_LOGIN_VERIFY	PIN_ACT_CHECK_SRVC_STATUS = active PIN_ACT_CHECK_SRVC_PASSWD PIN_ACT_CHECK_CREDIT_AVAIL = >=0
DEFAULT (for everything else)	PIN_ACT_CHECK_SRVC_STATUS = active PIN_ACT_CHECK_SRVC_PASSWD

You can customize PCM_OP_ACT_POL_SPEC_VERIFY to:

• Choose a different combination of authentication checks to use on an action.

• Change the behavior of the authentication checks.

• Decide not to use any checks to authenticate an action.

• Authorize a custom action using the list of authentication checks.

PCM_OP_ACT_POL_SPEC_VERIFY uses the DEFAULT set of authentication checks on any action it does not recognize.

To specify a different set of authentication checks for a new action:

1. Edit the BRM_home/source/sys/fm_policy/fm_act_pol/fm_act_pol_spec_vrfy.c source file.

2. Create a new Activity Policy Facilities Module (FM).

   Each authentication check must have a type (the enum value from the table of authentication checks above), and choice options to control the behavior of the check. See the PCM_OP_MAIL_DELIV_VERIFY action definition in the fm_act_pol_spec_vrfy.c file for an example of a PIN_FLD_CHOICES array.

For example, suppose you defined a noncurrency balance. To enforce a credit limit on that balance, you must modify the fm_act_pol_spec_vrfy.c file to include a new action that checks the noncurrency balance. (By default, checks are performed only on the currency balance.)

Reducing the number of authentication checks does not have a significant effect on performance, with the exception of duplicate session checking.

Enabling Duplicate Session Checking

You can customize PCM_OP_ACT_POL_SPEC_VERIFY to check for duplicate login attempts (PIN_ACT_CHECK_DUPE_SESSION) by performing the following tasks:

1. Modify your BRM_home/source/sys/fm_act/pol/fm_act_pol_spec_vrfy.c file to add duplicate session checking to the input flist for the desired actions. This is just the term_ip_dialup related action. Assuming the default version of fm_act_pol_spec_vrfy.c is used as a base, add the following code fragment at line 339:

   type = PIN_ACT_CHECK_DUPE_SESSION;
         c_flistp = PIN_FLIST_ELEM_ADD(a_flistp, PIN_FLD_CHECKS, 4, ebufp);
         PIN_FLIST_FLD_SET(c_flistp, PIN_FLD_TYPE, (void *)&type, ebufp);
         action = "/dialup";
         PIN_FLIST_FLD_SET(c_flistp, PIN_FLD_OBJ_TYPE, (void *)action, ebufp);
   

2. Add the same code fragment at line 390.

3. Recompile the file and use it as a new Activity Policy FM.

Managing and Customizing Profiles

To manage and customize profiles:

• To add a /profile object to an account, use PCM_OP_CUST_CREATE_PROFILE.

  This opcode calls other opcodes that prepare and validate the account data. After the account data is validated, PCM_OP_CUST_CREATE_PROFILE calls base opcodes to create a /profile object that contains extra information that you want to store about an account and associates it with the account object POID.

  Only one element can be passed in the PIN_FLD_PROFILES array. Otherwise, the opcode ignores the array.

  When automatic rerating is enabled, PCM_OP_CUST_CREATE_PROFILE triggers automatic rerating of backdated extended rating attribute (ERA) modifications when certain conditions are met.

• To modify a profile object, use PCM_OP_CUST_MODIFY_PROFILE. When automatic rerating is enabled, this opcode triggers automatic rerating of backdated ERA modifications when certain conditions are met.

  Given the POID of an existing /profile object, PCM_OP_CUST_MODIFY_PROFILE modifies the object with the specified changes.

  If the input flist for the inherited fields for the profile object contains a null array or substruct value, the array or substruct table entry is deleted in the database.

  Only one element can be passed in the PIN_FLD_PROFILES array. Otherwise, the opcode ignores the array.

• To delete profiles, use PCM_OP_CUST_DELETE_PROFILE.

  If the profile object specified in the input flist is a part of a profile sharing group (/group/sharing/profile object), PCM_OP_CUST_DELETE_PROFILE does not delete the profile and returns an error. If the specified profile object is not part of a profile sharing group, this opcode deletes the profile.

To customize profiles, use the following opcodes:

• Use PCM_OP_CUST_POL_PREP_PROFILE to add custom data to the /profile object. This opcode is an empty hook. This opcode is called by PCM_OP_CUST_CREATE_PROFILE and PCM_OP_CUST_MODIFY_PROFILE, and returns the flist that comes in.

• Use PCM_OP_CUST_POL_VALID_PROFILE to validate the data in the /profile object. This opcode is an empty hook. This opcode is called by PCM_OP_CUST_CREATE_PROFILE, PCM_OP_CUST_VALIDATE_CUSTOMER, and PCM_OP_CUST_MODIFY_PROFILE, and returns the flist that comes in. If the data is not valid, a list of possible problems is returned.

Retrieving Account Profile Information

To find the /profile objects that belong to an account, use PCM_OP_CUST_FIND_PROFILE.

This opcode uses the input PIN_FLD_POID database field of the input flist to determine which database to search for the profile list. The opcode calls a bas opcode to search for the profile.

If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_CUST_FIND_PROFILE returns the entire /profile object. Otherwise, it returns the fields specified in the PIN_FLD_RESULTS array. If no fields are specified, only the profile POID is returned. Other fields are returned with the profile POID only if they are specified in the PIN_FLD_PARAMETERS field of the input flist.

To limit the returned profile list, include a profile type string in the input flist by using PIN_FLD_TYPE_STR. A type string contains an object name or a wildcard value using the percent sign (%) that is compared to the profile object name. For example, /profile/foo returns all object subtypes “foo," and /profile/f% returns all profile subtypes starting with “f." If the profile string is not included in the input flist, all matching profiles for the account are returned.

Note:

The percent sign is the only wildcard you can use with this field.

Modifying an Account

To modify an account, use PCM_OP_CUST_UPDATE_CUSTOMER and PCM_OP_CUST_MODIFY_CUSTOMER opcodes.

PCM_OP_CUST_UPDATE_CUSTOMER calls other opcodes to add, modify, or delete the following data:

• Contact information

• Payment information: see "Changing a Bill's Payment Method" for more information.

• Bill units

• Top-up information

• Balance groups

• Profiles

• Locale

PCM_OP_CUST_MODIFY_CUSTOMER adds a service by adding a bundle to the account. PCM_OP_CUST_MODIFY_CUSTOMER adds a bundle by calling other opcodes to perform these operations:

• If the validate_deal_dependencies entry is enabled in the CM pin.conf file, PCM_OP_CUST_MODIFY_CUSTOMER verifies that any set bundle dependencies are valid. If not, the operation is disallowed.

• Purchase the bundle associated with the package.

• Set the account credit limit for each balance of the added package.

• Create service objects associated with the package.

  • If a service with an add-on package is added, and the ValidateDiscountDependency flag is enabled in the /config/business_params object, PCM_OP_CUST_MODIFY_CUSTOMER checks for any mutually exclusive relationships between discounts associated with the add-on package and any discounts already owned by the account. If any such relationship is found, the service addition is not continued.

    Note:

    Discount-to-discount exclusion rules are not validated. PCM_OP_CUST_MODIFY_CUSTOMER validates only package-to-discount exclusion rules at purchase time.

  • If the PIN_FLD_STATUS_FLAGS field is set to PIN_STATUS_FLAG_DUE_TO_SUBSCRIPTION_SERVICE, PCM_OP_CUST_MODIFY_CUSTOMER verifies that the service group relationships are valid and associates member services with the appropriate balance group.

  • If a subscription service is being added, PCM_OP_CUST_MODIFY_CUSTOMER verifies that it is not a member of another service group.

  • If the account status is inactive and the provisioning flag is not set, an error value is returned and PCM_OP_CUST_MODIFY_CUSTOMER exits without modifying the account.

  • If a subscription member service is being created, PCM_OP_CUST_MODIFY_CUSTOMER verifies that the subscription service is not inactive or closed. If the member service requires its own balance group, PCM_OP_CUST_MODIFY_CUSTOMER creates the balance group. Otherwise, it associates the member service with the subscription service's balance group.

• Optionally associate /device objects with the services.

• Create notification events to mark the beginning and end of its execution.

You can use other opcodes to modify accounts, such as PCM_OP_CUST_MODIFY_PAYINFO and PCM_OP_CUST_MODIFY_PROFILE.

PCM_OP_CUST_MODIFY_CUSTOMER is an empty hook to PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER, which you can use to export customer data to an external or legacy system for processing.

Table 9-4 lists the opcodes to which PCM_OP_CUST_MODIFY_CUSTOMER passes information from arrays in its input flist. The opcodes, in turn, use the information to create or modify objects:

Table 9-4 Opcodes and Information Received to Create or Modify Objects

This Opcode	Uses Information from This Array	To Create or Modify This Object
PCM_OP_CUST_SET_NAMEINFO	PIN_FLD_NAMEINFO     PIN_FLD_PHONES (subarray)	/account
PCM_OP_CUST_SET_BAL_GRP	PIN_FLD_ACCTINFO     PIN_FLD_BAL_INFO (subarray)	/balance_group
PCM_OP_CUST_SET_BILLINFO	PIN_FLD_BILLINFO	/billinfo
PCM_OP_CUST_SET_PAYINFO	PIN_FLD_PAYINFO     PIN_FLD_CC_INFO (subarray)     PIN_FLD_DD_INFO (subarray)     PIN_FLD_INV_INFO (subarray)	/payinfo/cc /payinfo/dd /payinfo/invoice
PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER	PIN_FLD_ACCTINFO     PIN_FLD_BAL_INFO (subarray) PIN_FLD_BILLINFO	/balance_group /billinfo
PCM_OP_CUST_SET_LOCALE	PIN_FLD_LOCALE	/account
PCM_OP_CUST_CREATE_PROFILE PCM_OP_CUST_MODIFY_PROFILE	PIN_FLD_PROFILES	/profile
PCM_OP_CUST_SET_TOPUP	PIN_FLD_TOPUP_INFO     PIN_FLD_GROUP_TOPUP_INFO     (subarray)         PIN_FLD_GROUP_TOPUP_LIMITS         (subarray)         PIN_FLD_GROUP_TOPUP_MEMBERS         (subarray)	/topup /group/topup

If the information is successfully updated, the opcode returns the POID of the /event objects created in the PIN_FLD_RESULTS array of the output flist. Otherwise, it returns the PIN_FLD_FIELDS array specifying the failing field.

If the input flist array value for PIN_FLD_NAMEINFO is set to NULL, the corresponding element ID is deleted from the NAMEINFO table in the /account object.

Changing a Bill's Payment Method

Use PCM_OP_CUST_UPDATE_CUSTOMER to change the payment method for an account's bill unit in the following ways:

• To change an existing payment method for a bill unit, pass the POID of the /payinfo object in the PIN_FLD_ PAYINFO_OBJ field in the PIN_FLD_BILLINFO array.

  For example:

  0 PIN_FLD_POID POID                [0] 0.0.0.1 /account 23304551863 227 
  0 PIN_FLD_ACCOUNT_OBJ POID         [0] 0.0.0.1 /account 23304551863 227 
  0 PIN_FLD_PROGRAM_NAME STR        [0] "program_name" 
  0 PIN_FLD_BILLINFO ARRAY          [0] allocated 20, used 3 
  1    PIN_FLD_BILLINFO_ID STR      [0] "Account Bill" 
  1    PIN_FLD_PAY_TYPE ENUM        [0] 10005 
  1    PIN_FLD_BILLING_SEGMENT ENUM [0] 0 
  1    PIN_FLD_PAYINFO_OBJ POID      [0] 0.0.0.1 /payinfo/cc 4780 0 
  ...
  

• To add a new payment method for an existing bill unit, you can create the /payinfo object and associate it with the bill unit in the same call by doing the following:

  • Include a PIN_FLD_PAYINFO_ARRAY field (outside of the PIN_FLD_ BILLINFO array) and add an array element for the new /payinfo object.

  • In the PIN_FLD_BILLINFO array, include the PIN_FLD_PAY_TYPE field with the new payment method. Specify a NULL value for the PIN_FLD_PAYINFO array and make sure the array element ID matches the element ID of the new /payinfo object in the PIN_FLD_PAYINFO array that is outside the PIN_FLD_BILLINFO array.

  For example:

  0 PIN_FLD_POID POID                [0] 0.0.0.1 /account 23304551863 227 
  0 PIN_FLD_ACCOUNT_OBJ POID         [0] 0.0.0.1 /account 23304551863 227 
  0 PIN_FLD_PROGRAM_NAME STR        [0] "program_name" 
  0 PIN_FLD_BILLINFO ARRAY          [0] allocated 20, used 3 
  1    PIN_FLD_BILLINFO_ID STR      [0] "Account Bill" 
  1    PIN_FLD_PAY_TYPE ENUM        [0] 10005 
  1    PIN_FLD_BILLING_SEGMENT ENUM [0] 0 
  1    PIN_FLD_PAYINFO ARRAY         [1] NULL
  0 PIN_FLD_PAYINFO ARRAY            [1] allocated 20, used 20
  1    PIN_FLD_POID POID            [0] 0.0.0.1 /payinfo/cc -1 0 
  ...
  

  In the preceding example, the new /payinfo object is created and associated with the bill unit specified in the input flist.

  Note:

  You must specify either the PIN_FLD_PAYINFO array or the PIN_FLD_ PAYINFO_OBJ field in the PIN_FLD_BILLINFO array. However, because these fields are mutually exclusive and you cannot specify both, they are classified as optional.

Creating Services

To create a service object BRM uses PCM_OP_CUST_CREATE_SERVICE.

If the PIN_FLD_SUBSCRIPTION_OBJ field in the input flist specifies the POID of a subscription's service object, the service being added to the customer's account is a member of the subscription service's group.

PCM_OP_CUST_CREATE_SERVICE creates the service by doing the following inside a transaction:

• Calls PCM_OP_CUST_INIT_SERVICE to create and initialize the /service object.

  PCM_OP_CUST_INIT_SERVICE initializes a service in a defunct state with generic fields provided by the input flist. Returns a short flist with the new POID and unencrypted password. This operation is carried out inside a transaction.

  PCM_OP_CUST_INIT_SERVICE calls PCM_OP_CUST_POL_PREP_INHERITED to prepare inherited information to be ready for online account creation. This opcode creates a place holder for a substruct in a /service string when a /account and /service object is created. For GSM services, the default BEARER_SERVICE value is an empty string and the default PRIMARY_MSISDN value is set to 0.

• Calls PCM_OP_CUST_SET_PASSWD to encrypt and set a password (if one is supplied) in the /service object. If a password is not provided, one is generated. See "Customizing Passwords" for more information.

• Stores any client-supplied inherited information in the /service object.

• Calls PCM_OP_CUST_SET_STATUS to set the service status. See "Setting Account, Service, and Bill Unit Status" for more information.

• Calls PCM_OP_DEVICE_ASSOCIATE to associate /device objects with the service.

Modifying Services

To modify a service BRM uses PCM_OP_CUST_UPDATE_SERVICES. For most services, this wrapper opcode calls PCM_OP_CUST_MODIFY_SERVICE to set, change, or delete extended service information.

PCM_OP_CUST_UPDATE_SERVICES takes as input the POID of the /account object, the name of the calling program, and an array containing a list of services to be updated. Additional inputs depend on the type of services being updated. Services are processed in the order dictated by the element value passed in the PIN_FLD_SERVICES array.

PCM_OP_CUST_UPDATE_SERVICES performs these operations:

1. Creates an /event/notification/service/pre_change event.

2. If login or alias list information is specified, calls PCM_OP_CUST_SET_LOGIN to update the service login or alias list with the value specified.

3. If password information is specified, calls PCM_OP_CUST_SET_PASSWD to update the service password with the value specified.

4. If service status information is specified, calls PCM_OP_CUST_SET_STATUS to update the status of the service with the value specified.

5. If inherited fields are specified, calls PCM_OP_CUST_MODIFY_SERVICE for most services to update the values for the inherited fields.

6. If one or more PIN_FLD_DEVICES arrays are specified, calls PCM_OP_DEVICE_ASSOCIATE to disassociate or associate the device. Disassociations are processed before associations.

7. Creates an /event/notification/service/post_change event.

If successful, the PCM_OP_CUST_UPDATE_SERVICES output flist contains the following:

• The POID of the /account object passed in.

• A services array containing the following:

  • The POIDs of the /service objects modified.

  • A results array containing the POID of the /event objects created to record the changes. The index values returned in the PIN_FLD_RESULTS array correspond to the input flist values as shown in Table 9-5:

    Table 9-5 Indexes and Input Flist Values in PIN_FLD_RESULTS

    Index Value	Input Flist Value
    0	Login
    1	Password
    2	Status
    3	Inherited information

If an error is encountered in the service data, PCM_OP_CUST_UPDATE_SERVICES:

• Continues to process all of the data, so that all erroneous data is uncovered.

• Rolls back the transaction. Any updates already made to the information are undone.

• Returns an error in the error buffer.

After the object is modified, BRM creates the /event/notification/service event to notify listeners about the change to the /service object. The output flist contains the POID of the modified /service object. In case of an error, the error buffer is populated and the output flist can be ignored.

The PCM_OP_CUST_MODIFY_SERVICE input flist contains the POID of the /service object to be modified and a substruct of the inherited information to be stored. If the input flist for an inherited field of the /service object contains a null entry, the array table entry is deleted from the object in the database.

Finding Accounts

In addition to using the base search opcodes to find accounts, you can use PCM_OP_CUST_FIND.This opcode replaces PCM_OP_SEARCH and PCM_OP_STEP_SEARCH. Given an account number, PCM_OP_CUST_FIND finds the /account object in question and returns the POID of the object and any other information that you request. If no results array is specified, the entire contents of the object are returned.

You can specify an array of account numbers in an input flist and have an array of results returned.

Finding a Customer's Account Information

Use PCM_OP_ACT_FIND to locate a customer's account information by using the login name.

PCM_OP_ACT_FIND searches for information on a specific account. In addition, the opcode performs the following operations:

• If you use a multischema BRM system, it searches all database schemas to find the /account object.

  In multischema environments, the calling opcode must not open a transaction before calling PCM_OP_ACT_FIND. Instead, the calling opcode must first call PCM_OP_ACT_FIND to find the schema in which the account resides and then open a transaction on the correct schema.

• If there is an open context (CM connection) to a schema when it is called and it finds the account in a different schema, it switches the context to the correct schema.

• If there is no open context when it is called, it searches all schemas.

  Note:

  PCM_OP_ACT_FIND does not perform authentication.

PCM_OP_ACT_FIND searches for the /account and /service object. If PCM_OP_ACT_FIND is called with the PCM_OPFLG_READ_RESULT flag, it returns all fields of the /service object, not just the POID.

Deleting Accounts

Note:

You can delete accounts in a production system, but ensure that you use this opcode with care.

To delete accounts, use PCM_OP_CUST_DELETE_ACCT. This opcode deletes the specified /account object and all related objects (such as events, bill items, bill history, balances, and notes) and disassociates devices that are assigned to the services. It also ensures that all the BRM objects and audit entries containing the subscriber's personal data are purged.

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

This opcode does not delete any audit table entries associated with the /account object.

To allow ECE to delete accounts that still have active open session, set the PIN_FLD_FLAG input field to 1.

You cannot delete the /account object if the account was previously associated with a subscription service transfer or if the bill unit it owns is a paying bill unit of a nonpaying bill unit in another account.

Note:

The PCM_OP_CUST_DELETE_ACCT opcode does not delete all custom objects. You can write custom logic to clean up the custom objects in BRM when the /event/notification/account/pre_delete and /event/notification/account/delete events are generated by the PCM_OP_CUST_DELETE_ACCT opcode.

Customizing Customer Payment Information

To customize how /payinfo objects are created, see the following topics:

• Customizing Payment Method Data Preparation

• Customizing Payment Method Validation

• Finding Payment Info

• Customizing the Account Used for Credit Card Validation

Customer payment information is stored in /payinfo objects. Use PCM_OP_CUST_SET_PAYINFO to create or modify a /payinfo object. This opcode also updates the PIN_FLD_PAYINFO_OBJ field in the /billinfo object.

During account modification, PCM_OP_CUST_SET_PAYINFO modifies the payment information for the bill unit if necessary.

PCM_OP_CUST_SET_PAYINFO creates an /event/audit/customer/payinfo object.

For credit card payment methods, PCM_OP_CUST_SET_PAYINFO omits the PIN_FLD_SECURITY_ID field from the PCM_OP_CREATE_OBJ input flist when the /payinfo/cc object is created. The result is that the CVV2/CID information is stored in the database with a NULL value.

PCM_OP_CUST_CREATE_PAYINFO is called by PCM_OP_CUST_UPDATE_CUSTOMER when a customer's payment information is modified.

PCM_OP_CUST_SET_PAYINFO is a wrapper opcode that calls the following opcodes:

• PCM_OP_CUST_CREATE_PAYINFO, which creates the account /payinfo object.

• PCM_OP_CUST_MODIFY_PAYINFO, which modifies a /payinfo object.

  When calling PCM_OP_CUST_MODIFY_PAYINFO, PCM_OP_CUST_SET_PAYINFO calls PCM_OP_WRITE_FLDS. One or more fields must be selected or an error is returned. The /payinfo object is modified only if the data in the input flist is different from the /payinfo object data in the database.

  PCM_OP_CUST_MODIFY_PAYINFO omits the PIN_FLD_SECURITY_ID field from the PCM_OP_WRITE_FLDS input flist when the /payinfo/cc object is updated. The result is that the CVV2/CID information is stored in the database with a NULL value.

To delete a /payinfo object, use PCM_OP_CUST_DELETE_PAYINFO. This opcode is given the POID of the object to delete.

PCM_OP_CUST_DELETE_PAYINFO is given the /payinfo object POID of the object to delete. You cannot delete a /payinfo object that is currently associated with a /billinfo object; you must first delete the /billinfo object.

Before PCM_OP_CUST_DELETE_PAYINFO deletes the /payinfo object, it calls PCM_OP_CUST_POL_PRE_DELETE_PAYINFO to perform any custom actions provided by you (for example, appropriate precautionary actions on a /payinfo object marked for deletion if that /payinfo object has been customized).

Use PCM_OP_CUST_POL_PRE_DELETE_PAYINFO to perform any actions that may be necessary before a /payinfo object is deleted by PCM_OP_CUST_DELETE_PAYINFO. For example, you can provide the code necessary to check if the /payinfo object selected for deletion has been customized. And if so, take appropriate precautionary actions before returning that object to the calling PCM_OP_CUST_DELETE_PAYINFO.

PCM_OP_CUST_POL_PRE_DELETE_PAYINFO is called by PCM_OP_CUST_DELETE_PAYINFO before the latter opcode deletes the /payinfo object.

PCM_OP_CUST_POL_PRE_DELETE_PAYINFO requires the POID of the /payinfo object in the PIN_FLD_POID field of its input flist. It returns the POID of the /payinfo object in the PIN_FLD_POID field to the calling PCM_OP_CUST_DELETE_PAYINFO.

Customizing Payment Method Data Preparation

PCM_OP_CUST_POL_PREP_PAYINFO processes inherited fields and prepares a /payinfo object. This opcode checks the payment method and creates the correct object based on that information.

• If the payment method is invoice, the /payinfo/invoice object is created.

• If the payment method is cc (credit card), the /payinfo/cc object is created and the information is prepared for online account creation.

  You can specify the valid date format for credit card and debit card expiration.

• If the payment method is dd (US and Canadian direct debit), the /payinfo/dd object is created and the information is prepared for online account creation.

• If the payment method is SEPA, the /payinfo/sepa object is created and the information is prepared for SEPA payments.

If the payment method is cc or dd, PCM_OP_CUST_POL_PREP_PAYINFO checks the /config/ach object to find the payment processor vendor to associate with the payment method. To use a vendor other than the default, you must customize this opcode.

PCM_OP_CUST_POL_PREP_PAYINFO is called by PCM_OP_CUST_VALIDATE_CUSTOMER.

Specifying the Payment Processor Vendor

PCM_OP_CUST_POL_PREP_PAYINFO selects the first payment processor vendor listed in the /config/ach object to process the BRM-initiated payment. If you configured multiple payment processor vendors, you can specify the vendor to use by passing the vendor's ID in the PIN_FLD_ACH field in the opcode input flist. The vendor's ID corresponds to the ID of the PIN_FLD_ACH_INFO array, in the /config/ach object, that contains the information for that vendor.

Customizing Payment Method Validation

PCM_OP_CUST_POL_VALID_PAYINFO validates inherited fields for a /payinfo object, which may include a /payinfo/cc object for credit cards or a /payinfo/dd object for direct debit, or a /payinfo/sepa object for SEPA Direct Debit or SEPA Credit Transfer transactions.

For credit cards, this opcode checks the credit card type, number, expiration date, and CVV2 or CID number during account creation.

For SEPA Direct Debit and Credit Transfer, PCM_OP_CUST_POL_VALID_PAYINFO checks that the International Bank Account Number (IBAN) and the Business Identifier Code (BIC) formats comply with the standards in the SEPA Rulebook and also validates that the primary currency of the account is euro.

Note:

Visa and American Express require a CVV2 or CID number for credit card fraud prevention. For security reasons, these numbers are not stored in the BRM database. For more information on how BRM handles these numbers, see "CVV2/CID Fraud Prevention Functionality".

If the information is valid, the standard checksum operation is performed.

PCM_OP_CUST_POL_VALID_PAYINFO is called by PCM_OP_CUST_VALIDATE_CUSTOMER.

Default /payinfo Validation

PCM_OP_CUST_POL_VALID_PAYINFO validates inherited fields for a /payinfo object according to the criteria contained in the /config/fld_validate object.

Mandatory fields for validation:

• PIN_FLD_CITY

• PIN_FLD_STATE

• PIN_FLD_ZIP

• PIN_FLD_COUNTRY

• PIN_FLD_CARD_TYPE

Checks performed for credit card-specific billing information:

• Is the debit number acceptable? (checksum)

• Is the debit number an acceptable type?

• Has the expiration date passed?

Checks performed for Paymentech direct debit transactions:

• Is the bank number acceptable? (9 digits)

• Is the debit number acceptable? (11 digits)

• What is the account type? (checking, corporate checking, savings)

CVV2/CID Fraud Prevention Functionality

As a fraud prevention feature, Visa and American Express use additional three- and four-digit security codes attached to standard credit card numbers.

• Visa uses a three-digit CVV2 number in the signature section on the back of the card.

• American Express uses a four-digit CID number.

For security reasons, PCM_OP_CUST_CREATE_PAYINFO and PCM_OP_CUST_MODIFY_PAYINFO opcodes omit the PIN_FLD_SECURITY_ID field from the PCM_OP_CREATE_OBJ input flist when the /payinfo object is created or changed. The result is that the CVV2/CID information is stored in the database with a NULL value. Likewise, PCM_OP_PYMT_CHARGE omits this value when a credit card is charged or validated; therefore, the /event/billing/charge/cc and /event/billing/validate/cc objects also store a NULL value for the PIN_FLD_SECURITY_ID value.

If the CM pin.conf file's cvv2_required flag is set to 1 (required), these opcodes send the PIN_FLD_SECURITY_ID value directly to the credit card processor when customers add or change credit cards in their accounts. If the CVV2 information is not provided in the input flist, the PIN_FLD_RESULT value is set to PIN_ERR_MISSING_ARG, with the description “Missing argument".

Verifying the Maximum Number of CVV2 Digits

By default, PCM_OP_CUST_POL_VALID_PAYINFO verifies that a credit card's CVV2 passed in the PIN_FLD_SECURITY_ID input flist field does not exceed three digits. You can modify the maximum allowed number of CVV2 digits by customizing the opcode to:

• Validate that the number of digits passed in the PIN_FLD_SECURITY_ID input flist field of the PIN_FLD_CC_INFO array does not exceed a specified value.

• If the validation succeeds, pass the PIN_FLD_SECURITY_ID field to the calling opcode.

• If the validation fails, return the appropriate error in the PIN_FLD_RESULT output flist field.

Disabling the Credit Card Checksum

To disable the credit card checksum:

1. Open the CM configuration file (BRM_home/sys/cm/pin.conf).

2. Change the flag in the cc_checksum entry from 1 (enable) to 0 (disable):

   - fm_cust_pol cc_checksum 0
   

3. Save and close the file.

The new value becomes effective immediately and applies to the next account created. The CM does not need to be restarted.

Customizing the Banking Information for US and Canadian Direct Debit

The bank number (/bank_no) and debit number (/debit_num) fields can be customized to allow for bank and debit numbers that do not meet the US standard (5 digits).

Customizing the Account Used for Credit Card Validation

When validating a credit card at account creation, BRM needs an account to validate the card with. By default, this is the root account. You cannot store this information with each account because the credit card validation is done before the account is created.

Use PCM_OP_PYMT_POL_SPEC_VALIDATE to change the account used for credit card validation.

The default account is:

0.0.0.1 /account 1

You can change the 1 to some other account number as long as it has a bill type that is not affected by billing operations or events.

PCM_OP_PYMT_POL_SPEC_VALIDATE reads the following CM pin.conf file entries:

• The cc_validate entry, which specifies whether to validate credit cards.

• The cc_revalidate entry, which specifies the amount of time before revalidation is required.

In addition, PCM_OP_PYMT_POL_SPEC_VALIDATE reads the /config/ach object to find the merchant value.

The only types of action supported are prep customer and commit customer. If one of these is not passed in, PIN_ERR_BAD_VALUE is returned. If the action passed in is NULL, a blank flist is returned. If an error occurs, a null flist is returned.

If the PIN_FLD_PAY_TYPE value is NULL, only the POID from the pin.conf file is returned. If the PIN_FLD_PAY_TYPE value is not PIN_PAY_TYPE_CC or PIN_PAY_TYPE_DD, the result is set to PIN_BOOLEAN_FALSE because there is nothing to validate. If the value is PIN_PAY_TYPE_CC or PIN_PAY_TYPE_DD, the result is set to PIN_BOOLEAN_TRUE.

Managing Mandate Information

The following sections describe how BRM manages mandate information when you use SEPA processing.

Registering a Mandate

To register the mandate information provided during customer account creation, BRM uses PCM_OP_CUST_SET_PAYINFO.

PCM_OP_CUST_SET_PAYINFO takes as input the mandate information such as the customer's IBAN and BIC and the creditor identification code.

This opcode adds the mandate by:

1. Creating a unique mandate reference number (UMR) for the mandate, if it is not provided in the input flist

2. Setting the status of the mandate to active

3. Creating the /payinfo/sepa object with the mandate information

PCM_OP_CUST_SET_PAYINFO calls PCM_OP_CUST_CREATE_PAYINFO, which calls PCM_OP_CUST_POL_VALID_PAYINFO, which validates that the format of the IBAN and BIC comply with the formats described in the SEPA rulebooks. Additional custom validations can be performed on the mandate information, such as country-specific validations.

Updating a Mandate

To update the mandate information, BRM uses the following opcodes:

• PCM_OP_CUST_AMEND_MANDATE, to update the customer information

• PCM_OP_CUST_AMEND_CREDITOR_INFO, to update the creditor information

PCM_OP_CUST_AMEND_MANDATE takes as input a reference to the /payinfo/sepa object and the mandate information to update.

This opcode updates the mandate by:

1. Updating the /payinfo/sepa object with the new mandate information

2. Updating the PIN_FLD_MANDATE_AMENDED field in the /payinfo/sepa object by using flags to indicate the fields that are amended

3. Generating the /event/activity/sepa/mandate_amendment event to record the mandate update

PCM_OP_CUST_AMEND_CREDITOR_INFO takes as input the creditor ID to be updated and the new creditor ID and creditor name.

This opcode updates the creditor information by:

1. Updating the /config/creditor object with the new creditor information

2. Determining if any /payinfo/sepa object exists that is associated with the original creditor ID and updating the /payinfo/sepa object with the new creditor information

3. In each /payinfo/sepa object that is updated, updating the PIN_FLD_MANDATE_AMENDED field by using flags to indicate the fields that are amended

4. Generating the /event/activity/sepa/mandate_amendment event to record the update

Canceling a Mandate

To cancel a mandate, BRM uses PCM_OP_CUST_CANCEL_MANDATE.

PCM_OP_CUST_CANCEL_MANDATE takes as input the reference to the /payinfo/sepa object that contains the mandate to cancel.

This opcode cancels the mandate by:

1. Setting the PIN_FLD_MANDATE_STATUS field in the /payinfo/sepa object to PIN_MANDATE_STATUS_CANCELED

2. Setting the PIN_FLD_MANDATE_END_T field to the current time to record the time of cancellation

3. Calling PCM_OP_CUST_DELETE_PAYINFO to delete the /payinfo/sepa object. The opcode does not cancel the /payinfo/sepa object if it determines that it is associated with a bill unit or if a SEPA payment request is pending

Setting Account, Service, and Bill Unit Status

See the following topics:

• Changing the Status of an Account, Bill Unit, or Service

• Customizing Status Changes

• Inactivating Accounts that Exceed a Specified Limit

Changing the Status of an Account, Bill Unit, or Service

PCM_OP_CUST_SET_STATUS changes and checks the status of an account, bill unit, or service. You can call the opcode directly for accounts and bill units. For service status changes, use PCM_OP_CUST_UPDATE_SERVICES, which in turn calls PCM_OP_CUST_SET_STATUS.

Note:

Do not callPCM_OP_CUST_SET_STATUS directly for service status changes. Use PCM_OP_CUST_UPDATE_SERVICES instead.

In addition to changing status, PCM_OP_CUST_SET_STATUS does the following:

• Triggers auto-billing if bills are still pending.

• Calls opcodes to prorate cycle fees.

To return all the fields in the event object, set the PCM_OPFLG_READ_RESULT flag. If this flag is not set, PCM_OP_CUST_SET_STATUS returns only the POID.

If PCM_OP_CUST_SET_STATUS is called at the account level, more than one result can be returned:

• One for each service owned by this account.

• One for each bill unit owned by this account.

• One or more for each child account and nonpaying bill unit.

• One for each deferred action.

To run PCM_OP_CUST_SET_STATUS without changing data in the database, use the PCM_OPFLG_CALC_ONLY flag.

• If the flag is set, no fields in the database are changed and the event object is not created. The fields used to create the event object and adjustment item are returned to the caller.

• If the flag is not set, the /event/customer/status object is created to record details of the operation.

PIN_FLD_STATUS Field Values for PCM_OP_CUST_SET_STATUS

When you use PCM_OP_CUST_SET_STATUS, set the account or bill unit status entry to one of the following field values listed in Table 9-6.

Table 9-6 PIN_FLD_STATUS Values

PIN_FLD_STATUS field	Description	Value
PIN_STATUS_ACTIVE	Account or bill unit fully functional; login is subject to credit limit check.	10100
PIN_STATUS_INACTIVE	Inactive account or bill unit; no logins permitted and no fees are charged.	10102
PIN_STATUS_CLOSED	Closes the account or bill unit, which can be reopened later. This does not activate the corresponding charge offers.	10103
PIN_STATUS_DEFUNCT	Reserved for BRM. PIN_ERR_BAD_ARG is returned if you try to set a status to this value.	0

PIN_FLD_STATUS_FLAG Field Values for PCM_OP_CUST_SET_STATUS

The values used to further define the status for the account, bill unit, or service are listed in Table 9-7:

Table 9-7 PIN_FLD_STATUS_FLAG Values

PIN_FLD_STATUS_FLAG field	Description	Value
PIN_STATUS_FLAG_ACTIVATE	Sets the future activation date (accounts and bill units only).	0x01
PIN_STATUS_FLAG_DEBT	Displays the outstanding debt (accounts and bill units only).	0x02
PIN_STATUS_FLAG_MANUAL	Displays manual operations performed by the administrative operator.	0x04
PIN_STATUS_FLAG_DUE_TO_ACCOUNT	Closes all related services for the account or bill unit (accounts and bill units only).	0x08
PIN_STATUS_FLAG_DUE_TO_PARENT	Closes all child accounts if the parent account is closed (only for accounts in groups set up for billing purposes). Closes all child bill units if the parent bill unit is closed.	0x10
PIN_STATUS_FLAG_DUE_TO_SUBSCRIPTION_SERVICE	Changes all member services when the subscription's service status is changed.	0x20000
PIN_STATUS_FLAG_PO_EXHAUSTED	Obsolete.	0x20
PIN_STATUS_FLAG_PROVISIONING	Identifies tasks that use the provisioning system.	0x40

The field values in the object are set as follows:

• If the input status is PIN_STATUS_ACTIVE:

  • Flags = (Old flag AND NOT (New flag))

  • If the result flag is 0, new status is input status, else old status.

• If the input status is PIN_STATUS_INACTIVE:

  • The status field is set to inactive.

  • The flags field is set to the OR of the old flags in the database and the new flags on the input flist.

• If the input status is PIN_STATUS_CLOSED:

  • The status field is set to closed.

  • The flags field is set to the OR of the old flags and new flags.

If the status change is caused by a change to the parent account or bill unit, PIN_FLD_STATUS_FLAG_DUE_TO_PARENT is set in the new flags.

If the status change is caused by a change to an accounts receivable (AR) account or AR bill unit, PIN_FLD_STATUS_FLAG_DUE_TO_ACCOUNT is set in the new flags.

Accounts, bill units, or services marked as closed (terminated) are actually closed when the pin_deferred_act billing application is run.

About Deferred Actions When Using PCM_OP_CUST_SET_STATUS

For deferred actions, the PIN_FLD_WHEN_T field is passed to indicate the date on which the status change is made. It also creates a /schedule object to store the input flist to call PCM_OP_CUST_SET_STATUS on the specified date.

You can create, delete, run, and modify /schedule objects by calling the opcodes in Table 9-8:

Table 9-8 Opcodes used to Modify /schedule Objects

Opcode	Function
PCM_OP_ACT_SCHEDULE_CREATE	Creates a schedule object.
PCM_OP_ACT_SCHEDULE_DELETE	Deletes a schedule object.
PCM_OP_ACT_SCHEDULE_MODIFY	Modifies a schedule object.
PCM_OP_ACT_SCHEDULE_EXECUTE	Runs a schedule object. This opcode is called directly by the pin_deferred_act billing utility.

By default, the pin_deferred_act utility, which is part of the pin_bill_day billing script, finds expired schedule objects and calls PCM_OP_ACT_SCHEDULE_EXECUTE, which in turn calls PCM_OP_CUST_SET_STATUS.

If the deferred status change is for closing an account, bill unit, or service, PCM_OP_CUST_SET_STATUS sets the PIN_FLD_CLOSE_WHEN_T field in the account, bill unit, or service to midnight on the specified date.

Setting, Resetting, or Unsetting a Deferred CLOSE

When setting or resetting a deferred CLOSE, PCM_OP_CUST_SET_STATUS calls a standard opcode to set the PIN_FLD_PURCHASE_END_T, PIN_FLD_CYCLE_END_T, and PIN_FLD_USAGE_END_T fields for each corresponding charge offer and discount offer to the deferred CLOSE date if the old values for these fields are later than the deferred CLOSE date or if these fields are set to NEVER (“0").

If a deferred CLOSE is canceled (the schedule object is deleted), PCM_OP_CUST_SET_STATUS calls a standard opcode to set the values of the PIN_FLD_PURCHASE_END_T, PIN_FLD_CYCLE_END_T, and PIN_FLD_USAGE_END_T fields for all corresponding charge offers and discount offers to the old values from the previous /event/billing/product/action/modify event.

Customizing Status Changes

You can customize status changes by using the following opcodes:

• To customize the way status is changed for an account or service, use PCM_OP_CUST_POL_PREP_STATUS. This call is used to modify status information before changing the account. For example, you can use this opcode to customize how customer service representatives (CSR) can set permissions on specific service types. This opcode is called by PCM_OP_CUST_SET_STATUS. This opcode is an empty hook.

• To validate status changes for an account or service, use PCM_OP_CUST_POL_VALID_STATUS. This opcode is called by PCM_OP_CUST_SET_STATUS. The default is to do no additional checking and to return the verified information.

See BRM Developer's Guide.

Inactivating Accounts that Exceed a Specified Limit

Use PCM_OP_ACT_POL_EVENT_LIMIT to inactivate any account or account hierarchy that exceeds a specified limit.

PCM_OP_ACT_POL_EVENT_LIMIT performs the following tasks:

1. Calls PCM_OP_CUST_SET_STATUS to inactivate an account or account hierarchy based on the status set in the PIN_FLD_STATUS field.

2. Calls PCM_OP_ACT_POL_EVENT_NOTIFY to notify any custom applications that a limit was reached and that an action took place.

PCM_OP_ACT_POL_EVENT_LIMIT is not called by any opcode.

Backdating Status Changes

To backdate a status change, enter the date to which you want to backdate the account, service, charge offer, or discount offer status change in the PIN_FLD_END_T field of the applicable opcodes. For example, enter the backdated date in the PIN_FLD_ END_T field of the following opcodes:

• PCM_OP_CUST_SET_STATUS: for backdating the account status change.

• PCM_OP_CUST_UPDATE_SERVICES: for backdating the service status change.

• PCM_OP_CUST_SET_PRODUCT_STATUS: for backdating the charge offer status change.

• PCM_OP_CUST_SET_DISCOUNT_STATUS: for backdating the discount status change.

Getting Life Cycle States

PCM_OP_CUST_GET_LIFECYCLE_STATES gets one of the following, depending on what information is passed to it:

• If only the account and service POIDs are passed, gets the life cycle states configuration object (/config/lifecycle_states) associated with a specified service type

• If the account and service POIDs and the state ID are passed, gets the PIN_FLD_STATES array for that state from a life cycle states configuration object

• If the account, service, and bill unit (/billinfo object) POIDs are passed, gets the PIN_FLD_STATES array for the initial state (PIN_FLD_INITIAL_STATE = 1) of the life cycle

PCM_OP_CUST_GET_LIFECYCLE_STATES is called by the following components:

• pin_state_change calls this opcode to get state transition information from a life cycle states configuration object.

• PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE calls this opcode to get the state expiration time. After a balance is adjusted for a service that uses a custom life cycle, PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE triggers any required service state change and updates the state expiration date in the /service object.

• PCM_OP_CUST_SET_STATUS calls this opcode to get the service's initial state.

• PCM_OP_CUST_SET_STATUS and PCM_OP_CUST_UPDATE_SERVICES opcodes call this opcode during validation.

PCM_OP_CUST_GET_LIFECYCLE_STATES is used only if the SubscriberLifeCycle business parameter is associated with the specified service's bill unit and is enabled.

Amending Creditor Information

To amend creditor information, use PCM_OP_CUST_AMEND_CREDITOR_INFO.

PCM_OP_CUST_AMEND_CREDITOR_INFO takes as input the creditor ID to be updated and the new creditor ID and creditor name.

PCM_OP_CUST_AMEND_CREDITOR_INFO does the following:

1. Updates the /config/creditor object with the new creditor information.

2. Determines if any /payinfo/sepa object exists that is associated with the original creditor ID and updating the /payinfo/sepa object with the new creditor information.

3. In each /payinfo/sepa object that is updated, updates the PIN_FLD_MANDATE_AMENDED field by using flags to indicate the fields that are amended.

4. Generates the /event/activity/sepa/mandate_amendment event to record the update.

Amending a Mandate

To amend a mandate, BRM calls PCM_OP_CUST_AMEND_MANDATE.

PCM_OP_CUST_AMEND_MANDATE takes as input a reference to the /payinfo/sepa object and the mandate information to update.

PCM_OP_CUST_AMEND_MANDATE does the following:

1. Updates the /payinfo/sepa object with the new mandate information.

2. Updates the PIN_FLD_MANDATE_AMENDED field in the /payinfo/sepa object by using flags to indicate the fields that are amended.

3. Generates the /event/activity/sepa/mandate_amendment event to record the mandate update.

Canceling a Mandate

To cancel a mandate, use PCM_OP_CUST_CANCEL_MANDATE.

PCM_OP_CUST_CANCEL_MANDATE takes as input the reference to the /payinfo/sepa object that contains the mandate to cancel.

PCM_OP_CUST_CANCEL_MANDATE does the following:

1. Sets the PIN_FLD_MANDATE_STATUS field in the /payinfo/sepa object to PIN_MANDATE_STATUS_CANCELED.

2. Sets the PIN_FLD_MANDATE_END_T field to the current time to record the time of cancellation.

3. Calls PCM_OP_CUST_DELETE_PAYINFO to delete the /payinfo/sepa object. The opcode does not cancel the /payinfo/sepa object if it determines that it is associated with a bill unit or if a SEPA payment request is pending.

Managing Deferred Actions

See the following topics:

• Scheduling Deferred Actions

• Modifying Deferred Actions

• Deleting Deferred Actions

• Executing Deferred Actions

• Performing Policy Checks before Scheduling Deferred Actions

Scheduling Deferred Actions

PCM_OP_ACT_SCHEDULE_CREATE creates /schedule objects, which schedule a single action for a predetermined date and time.

BRM supports the following deferred actions:

• Account activation, deactivation, and closure.

• Account parent change.

• Service activation and closure.

Two optional fields, PIN_FLD_WHEN_T and PIN_FLD_DESCR, enable deferred actions in BRM. These fields are set by the input flists of PCM_OP_ACT_POL_EVENT_NOTIFY or PCM_OP_BILL_GROUP_MOVE_MEMBER.

• PIN_FLD_DESCR describes the deferred action.

• PIN_FLD_WHEN_T specifies when the deferred action occurs.

If the PIN_FLD_WHEN_T field is populated in the input flist of the calling opcode, that opcode can call PCM_OP_ACT_SCHEDULE_CREATE to create a /schedule object to hold the input flist information. The /schedule object remains active until the PIN_FLD_WHEN_T time expires and PCM_OP_ACT_SCHEDULE_EXECUTE runs the action stored in the /schedule object.

Note:

Deferred actions are always rounded off to midnight. For example, if you use PCM_OP_ACT_SCHEDULE_CREATE to schedule a deferred action on January 15 at 8:00 a.m., the schedule object is created with a scheduled time of January 15 at 00:00.

Modifying Deferred Actions

PCM_OP_ACT_SCHEDULE_MODIFY modifies an existing /schedule object.

This opcode modifies the text description in PIN_FLD_DESCR field and the scheduled date in PIN_FLD_WHEN_T field.

Deleting Deferred Actions

PCM_OP_ACT_SCHEDULE_DELETE deletes existing /schedule objects.

Executing Deferred Actions

PCM_OP_ACT_SCHEDULE_EXECUTE runs any deferred actions defined in a /schedule object. This opcode is called directly by the pin_deferred_act billing utility.

When you run the pin_deferred_act utility, it searches for any /schedule object with both an expired PIN_FLD_WHEN_T field and a PIN_FLD_STATUS field marked Pending. When it finds one, it calls PCM_OP_ACT_SCHEDULE_EXECUTE to:

1. Run the action defined in the /schedule object.

2. Update PIN_FLD_STATUS to either Done or Error, depending on its success.

Performing Policy Checks before Scheduling Deferred Actions

Use PCM_OP_ACT_POL_VALIDATE_SCHEDULE to perform custom policy checks before creating a /schedule object. For example, you can customize this opcode to verify that an account balance is zero before scheduling it for closure.

This opcode is an empty hook.

This opcode is called by PCM_OP_ACT_SCHEDULE_CREATE.

Managing Service Groups

See the following topics:

• Creating a Service Group

• Configuring Extended Rating Attributes for a Service Group

• Associating a Device with a Service Group

• Adding a Service to an Existing Service Group

• Canceling a Service Group

• Transferring Service Groups between Accounts in the Same Schema

• Transferring Service Groups between Accounts in Different Schemas

Creating a Service Group

A service group is composed of a subscription service and any number of member services. The /service objects for subscription services are created when packages are purchased. This can occur at the following times:

• When registering customers, use PCM_OP_CUST_COMMIT_CUSTOMER.

• When customers purchase a package for an existing account, use PCM_OP_CUST_MODIFY_CUSTOMER.

These opcodes call other opcodes to set up a customer's services and create the service objects.

These opcodes set the service group relationship fields in the service objects that they create. Services are created in the following order: account services, the subscription service, and member services in the service group.

To create a service group, set the following fields in the PCM_OP_CUST_CREATE_CUSTOMER and PCM_OP_CUST_MODIFY_CUSTOMER input flists:

• Add a PIN_FLD_SERVICES array for each service in the service group.

  Note:

  The service arrays must start with array element 1.

• In each service array, set the PIN_FLD_SUBSCRIPTION_OBJ field to specify the POID of the subscription service. If the service being created is the subscription service, this field and the PIN_FLD_POID field specify the same value.

• Add a PIN_FLD_BAL_INFO array to create a balance group for the subscription service. Optionally, specify a credit limit or threshold.

• Add an additional PIN_FLD_BAL_INFO array for each member service that should have its own balance group, and optionally set the credit limit and threshold. A member service that does not have a balance group uses the subscription service's balance group.

• In each PIN_FLD_SERVICES array, set the PIN_FLD_BAL_INFO_INDEX field to specify the index of the array that contains the balance group for that service.

Configuring Extended Rating Attributes for a Service Group

After setting up systemwide extended rating attribute (ERAs), you assign an ERA to a customer's service and specify customer-specific information (for example, the customer's birthday for a birthday discount ERA).

Service ERAs are stored in /profile/serv_extrating objects. These objects are typically associated with customer accounts at two times:

• When registering customers, use PCM_OP_CUST_COMMIT_CUSTOMER.

• When customers purchase a package for an existing account, use PCM_OP_CUST_MODIFY_CUSTOMER.

These opcodes call other opcodes to create or modify the /profile objects.

To configure a service group ERA for a customer, add a PIN_FLD_PROFILES array to the subscription service's PIN_FLD_SERVICES array on the input flist of the *_CUSTOMER opcodes. In the profiles array, set the POID of the /profile/serv_extrating object owned by the service.

To configure the ERA with customer-specific data, write custom code that sets the customer's information in the PIN_FLD_DATA array of the /profile/serv_extrating object.

To validate the customer's profile information, you must modify PCM_OP_CUST_POL_VALID_PROFILE.

You can also use the customer profile opcodes to create and modify /profile objects directly.

Associating a Device with a Service Group

Customers use devices, such as a wireless handset, to access the services in their service groups. The device information, such as device ID, manufacturer, and associated account and service, are stored in a /device object. You associate /device objects with subscription /service objects when you register customers or add packages to customer accounts:

• When registering customers, use PCM_OP_CUST_COMMIT_CUSTOMER.

• When customers purchase a package for an existing account, use PCM_OP_CUST_MODIFY_CUSTOMER.

These opcodes call other opcodes to create or modify the /device objects.

To create a /device object and associate it with a service group, set the following fields in the subscription service's PIN_FLD_SERVICES array on the input flist of the customer opcodes:

• In the PIN_FLD_DEVICE_OBJ field of the PIN_FLD_DEVICES array, specify the POID of the /device object.

• In the PIN_FLD_ALIAS_LIST array, specify the number associated with the device (such as the IMSI or MSISDN).

You can also use PCM_OP_CUST_UPDATE_SERVICES to modify /device objects. This opcode calls PCM_OP_DEVICE_ASSOCIATE to associate or disassociate a device with a service.

To create or modify device objects directly, use the PCM_OP_DEVICE* opcodes.

Adding a Service to an Existing Service Group

You add a service to a service group in the same way that you create a service in a service group. Use PCM_OP_CUST_MODIFY_CUSTOMER and set the service information in the input flist. See "Creating a Service Group".

Canceling a Service Group

Use PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION to cancel the services in a service group. This opcode cancels the group's subscription service and all its member services.

Specify the following information in PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION input flist:

• Set PIN_FLD_POID to the POID of the account object that owns the service group.

• Set PIN_FLD_SUBSCRIPTION_OBJ to the POID of the subscription service to be canceled.

• Set the input flag PIN_FLD_FLAGS to PIN_BILL_FLG_BILL_NOW, to bill the account immediately upon service cancellation.

  Note:

  If the input flag is not set, the account is billed for the service on the regularly scheduled billing date.

PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION performs the following tasks:

1. If the PIN_BILL_FLG_BILL_NOW flag is passed in the input flist, calls PCM_OP_BILL_MAKE_BILL_NOW for each bill unit associated with the service group.

   Note:

   Typically, all member services are associated with the subscription service's bill unit. However, it is possible for member services to be associated with different bill units.

2. Calls PCM_OP_CUST_UPDATE_SERVICES to update the status of the subscription service and member services. PCM_OP_CUST_UPDATE_SERVICES does the following:

   1. Changes the status of the subscription service and all its member services to closed.

   2. Changes the status of all associated with the subscription service and member services to canceled.

   3. Deletes any charge or discount sharing groups owned by the subscription service and the member services, and updates the ordered balance group (/ordered_balgrp object) of those services.

   4. Removes the subscription service and member services from any charge or discount sharing group of which they are members.

3. Generates the /event/audit/subscription/cancel audit event to record the service cancellation.

If the PIN_BILL_FLG_BILL_NOW flag is specified in the input flist, the service is billed upon cancellation. Otherwise, the service is billed during the regularly scheduled billing time.

If successful, PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION returns the following:

• The POID of the subscription service that was canceled.

• The POID of the /event/audit/subscription/cancel audit event created to record the cancellation.

Transferring Service Groups between Accounts in the Same Schema

To transfer a service group to another account in the same schema, use PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION.

Specify the following information in the PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION input flist:

• The POID of the source account.

• The POID of the target account.

• The POID of the subscription service to transfer.

• The POID of a bill unit (/billinfo object) and of a pay info object (/payinfo):

  • If the subscription service is to be associated with an existing bill unit in the target account, specify the POIDs of that bill unit and pay info object.

  • If the subscription service is to be associated with a new bill unit created for the service only, specify the POIDs of the new bill unit and pay info object.

• The POID of an existing pay info object for the target account or the POID of a new pay info object created for the service only.

To transfer the service group's member services, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following for each member service:

1. Sets the account POID to the target account's POID.

2. Creates a transfer list array element, and adds it to the service objects.

3. Creates an /event/audit/subscription/transfer audit event to record the service transfer.

To transfer the service group's devices, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following for each member service:

1. Finds all the devices owned by the service, and sets each device's account POID to the target account POID.

2. Creates an /event/audit/subscription/transfer audit event to record the device transfer.

To transfer the service group's charge and discount offers, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION cancels the service group offers owned by the source account and creates copies for the target account. To do this, the opcode does the following for each member service:

1. Finds all charge and discount offers associated with the service in the source account.

2. For each charge offer instance:

   1. Calls PCM_OP_SUBSCRIPTION_SET_PRODINFO to set the purchase, cycle, and usage end dates to the transfer date in the source account and to apply cycle forward fees.

   2. Creates another instance of the charge offer and assigns it to the target account with purchase, cycle, and usage start dates set to the transfer date.

   3. Creates an /event/billing/product/action/purchase event to record the transfer of the charge offer instance.

3. For each discount offer instance:

   1. Calls PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO to set the purchase, cycle, and usage end dates to the transfer date in the source account and to apply cycle forward fees.

   2. Creates another instance of the discount offer and assigns it to the target account with purchase, cycle, and usage start dates set to the transfer date.

   3. Creates an /event/billing/discount/action/purchase event to record the transfer of the discount offer instance.

To transfer the service group's billing information, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION associates each service balance group with an existing bill unit in the target account or with a new bill unit created for the service group. To do this, the opcode does the following:

1. If a /billinfo object is specified in the input flist, the opcode sets the PIN_FLD_BILLINFO_OBJ field in the service /balance_group object to reference that /billinfo object.

2. If a /payinfo object is specified in the input flist, the opcode sets the PIN_FLD_PAYINFO_OBJ field in the service /balance_group object to reference that /payinfo object.

3. If a /billinfo object is not specified, the opcode calls PCM_OP_CUST_SET_BILLINFO to create a /billinfo object and sets the PIN_FLD_BILLINFO_OBJ field in the service /balance_group object to the new /billinfo object.

4. If a /payinfo object is not specified, the opcode calls PCM_OP_CUST_SET_PAYINFO to create a /payinfo object and sets the PIN_FLD_PAYINFO_OBJ field in the service /balance_group object to the new /payinfo object.

To transfer the service group's sub-balances, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following:

1. Modifies each service /balance_group object to reference the /billinfo object in the account.

2. Sets the sub-balance validity based on the sub_bal_validity parameter in /config/business_params.

3. Creates an /event/audit/subscription/transfer audit event to record the balance group transfer.

To transfer pending scheduled actions for a service in a service group when transferring the group to another account, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION calls PCM_OP_SUBSCRIPTION_POL_POST_TRANSFER_SUBSCRIPTION.

The TransferScheduledActions business parameter must be enabled for PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION to call PCM_OP_SUBSCRIPTION_POL_POST_TRANSFER_SUBSCRIPTION. See "Enabling Transfer of Pending Scheduled Actions during Service Group Transfers".

When a service group is transferred to another account, its subscription service and member services are deleted from any sharing group of which they are a member. PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following for each member service:

1. Finds the charge or discount sharing groups that the service is a member of and deletes the service from the sharing group.

2. Deletes any ordered balance group associated with the service.

When a subscription service is transferred to another account, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION finds and deletes any charge or discount sharing group that it owns.

Enabling Transfer of Pending Scheduled Actions during Service Group Transfers

To enable the transfer of pending scheduled actions during service group transfers:

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

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

   pin_bus_params -r BusParamsSubscription bus_params_subscription.xm
   

3. In the file, change disabled to enabled:

   <TransferScheduledActions>enabled</TransferScheduledActions>
   

4. Save the file as bus_params_subscription.xml.

5. Load the XML file into the BRM database:

   pin_bus_params bus_params_subscription.xml
   

6. Stop and restart the CM.

7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see BRM System Administrator's Guide.

Transferring Service Groups between Accounts in Different Schemas

To transfer a service group between accounts stored in multiple schemas, you enable the RecreateDuringSubscriptionTransfer business parameter.

Note:

When RecreateDuringSubscriptionTransfer is enabled, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION re-creates all the objects in the schema to which the service groups are transferred.

Enabling Transfer of Service Groups between Accounts in Multiple Schemas

To enable the transfer of service groups to an account in a different schema:

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

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

   pin_bus_params -r BusParamsSubscription bus_params_subscription.xml
   

3. In the file, change disabled to enabled:

   <RecreateDuringSubscriptionTransfer>disabled</RecreateDuringSubscriptionTransfer>
   

4. Save the file as bus_params_billing.xml.

5. Load the XML file into the BRM database:

   pin_bus_params bus_params_subscription.xml
   

6. Stop and restart the CM.

7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see BRM System Administrator's Guide.

Transferring Service Groups across Schemas

To transfer a service group, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following:

1. Finds all the related services. If the service to be transferred is a subscription service, this opcode finds all the member services and groups.

2. Changes the status of the services to CANCELLED and recalculates charges for all service-level that use PCM_OP_SUBSCRIPTION_SET_PRODINFO or PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO.

3. Creates an flist of all the services to be transferred, and saves login information, profiles, and devices.

4. Adds login information to the source services by prepending the login details with the service POID, and generates an /event/customer/login event.

5. Calls PCM_OP_CUST_MODIFY_CUSTOMER to create new service instances for the account in the target schema.

6. Creates /billinfo, /payinfo, and /balance_group objects if the source objects do not already have them.

   Note:

   The /billinfo object passed in the input flist must belong to the account in the target schema.

7. Fetches the encrypted password from the service in the source schema, sets it in the service in the target schema, and generates an /event/customer/status and an /event/customer/login event.

8. If called from PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER, saves the /service, /balance_group, and /billinfo objects in the NAMED_TRANS_FLIST array.

9. Updates the SUBSCRIPTION_OBJ field of the new instance of each member service in the target schema with the POID of the subscription service created in the target schema.

10. Updates /device object with the service and the account in the target schema.

    Note:

    Devices associated with the services to be transferred must not be associated with any services that are not transferred.

11. Re-creates the /profile objects in the target schema using PCM_OP_CREATE_OBJ that has effective_t set to the transfer time.

    Note:

    To cancel the source service instances, the opcode deletes the /ordered_balgrp and /group/sharing/* relationships and saves the audit copies on the source service instances for processing late CDRs. Sharing group relationships are terminated on the transfer date, and the new service instances do not participate in any sharing relationships.

12. Calls PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE to delete all sharing groups in which service is an owner or a member.

13. Creates the /purchased_discount and /purchased_product objects and cycle forward events. For cycle arrears events, calls PRO_FORCED in CYCLE_FEE_FLAGS.

14. Regenerates a package ID for the offerings created in the target schema.

15. Calls PCM_OP_CUST_UPDATE_SERVICES to close the service on the source schema.

16. Sets the status flag of the source subscription service to PIN_STATUS_FLAG_DUE_TO_SERVICE_TRANSFER, and sets the status to Closed.

17. Sets the status flag of the source member services to PIN_STATUS_FLAG_DUE_TO_SUBSCRIPTION_SERVICE, and sets the status to Closed.

18. Generates an /event/customer/status event.

19. Creates an /event/audit/subscription/transfer audit event to record the service transfer. The /event/audit/subscription/transfer event contains PIN_FLD_TO_SERVICE_OBJ, PIN_FLD_TO_BAL_GRP_OBJ, and PIN_FLD_TO_PROFILE_OBJ.

20. Calls PCM_OP_SUBSCRIPTION_POL_POST_TRANSFER_SUBSCRIPTION if the TransferScheduledActions business parameter is enabled.

If the source and target balance groups of the transferred services are in different schemas, PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER does the following:

1. Calls PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION, which finds all the services and their new service references and uses the references to purchase bundles on the services in PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER.

   Note:

   For PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER to call PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION:

   • Either PIN_FLD_FROM_BAL_GRP_OBJ or the /service object must be present in the input flist.

   • Either the /billinfo object or the /billinfo array must be present in the input flist.

2. Creates an /event/audit/service_balgrp_transfer audit event to record the balance group transfer. The /event/audit/service_balgrp_transfer audit event contains the PIN_FLD_TO_SERVICE_OBJ field.

Managing Profile Sharing Groups

See the following topics:

• Creating a Profile Sharing Group

• Validating Profile Sharing Group Members

• Modifying a Profile Sharing Group

• Deleting Members and Profiles from a Profile Sharing Group

• Changing the Owner of a Profile Sharing Group

• Deleting a Profile Sharing Group

Creating a Profile Sharing Group

To customize a third-party application to create a profile sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE.

The profile sharing group has either a service or an account as the owner and a list of member services or accounts. It also contains one or more /profile objects owned by the group owner that is shared with group members.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE creates the group object and then adds the members and profiles:

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

2. Adds the /account and /service objects in the PIN_FLD_MEMBERS array to the MEMBERS array of the /group/sharing/profiles object. Each PIN_FLD_MEMBERS array element specifies an /account object 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 profile sharing group. However, subclass instances of the service type do not become members.

   If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/profiles object is created. The member account can join the group and purchase the service later.

3. Validates that the group owner does not belong to a profile sharing group owned by one of the members.

4. Calls PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS to validate the members. By default, this opcode has no validation rules for profile sharing group members, but you can customize it to validate members. See "Validating Profile Sharing Group Members".

   Note:

   PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE does not validate that the primary currency of members matches the parent.

5. Adds the /profile objects in the PIN_FLD_PROFILES array to the PROFILES array of the /group/sharing/profiles object.

   The profiles must be owned by the profile sharing group owner and must have a current validity period.

   If the PIN_FLD_PROFILES array is empty, the profiles list is empty. Duplicate entries are ignored.

If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE returns the POID of the profile sharing group object created and the POID of the event generated to record the creation.

When the profile sharing group is created, the group is automatically added to each member's ordered balance group.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE fails if the owner is a member of a sharing group owned by one of the members.

Validating Profile Sharing Group Members

To validate the members of a profile sharing group, use PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS. By default, this opcode does nothing.

You can customize this opcode to implement your validation rules. For example, the opcode can make sure that a member's service type is the same as the owner's service type.

This opcode takes as input the list of potential members and returns only those members that pass validation.

This opcode is called by PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE and PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY.

If customized for profile sharing groups, PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS validates members before they are added or modified and returns a list of valid members to the calling opcode.

Modifying a Profile Sharing Group

To modify a profile sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY. This opcode performs one of the following modifications, depending on the input POID:

• Adds member accounts or services to an existing group.

• Adds profiles to an existing group.

If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY returns the POID of the group that was modified and the POIDs of the events that were generated 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 profile object in the input flist is not valid.

For more information, see:

• Adding Members to a Profile Sharing Group

• Adding Profiles to a Profile Sharing Group

Adding Members to a Profile Sharing Group

To add members to a profile sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY.

Note:

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.

To make sure that you do not assign a new member to an existing member's ID, include all the existing members in the input flist. In this case, the opcode will make sure that all new members are added, even if a new member's element ID is the same as an existing member's ID.

This opcode handles duplicate members, so including existing members in the input flist does not cause problems.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY does the following:

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

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

   Note:

   • The guidelines for creating a profile sharing group also apply to adding members to an existing group.

   • If you specify a service type as a member, the member account does not need to own the service when the /group/sharing/profiles object is modified. The member account can join the group and purchase the service later.

2. Validates that the group owner does not belong to a profile sharing group owned by one of the members.

3. Calls PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS to validate the members. By default, this opcode has no validation rules for profile sharing group members, but you can customize it to validate members. See "Validating Profile Sharing Group Members".

4. Creates an flist that includes the list of members to be added to the sharing group.

5. Generates an /event/group/sharing/profiles/modify event to record the changes.

Adding a member to a profile sharing group triggers PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS, which adds the profile sharing group to the ordered balance group for each member.

PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS creates or modifies ordered balance groups for profile sharing group members (accounts or services) when the profile sharing group is created or modified.

PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS is triggered when a profile sharing group is created or modified. This opcode calls PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY to create or modify ordered balance groups.

You can customize PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS to use it with other types of sharing groups or to use it with only certain profile sharing groups.

This opcode is listed in the pin_notify file for these events:

• /event/group/sharing/profiles/create

• /event/group/sharing/profiles/modify

When merging event notification files, list PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_MEMBERS after the Enterprise Application Integration (EAI) framework publishing opcode, PCM_OP_PUBLISH_GEN_PAYLOAD. See the discussion on merging event notification lists in BRM Developer's Guide.

Use PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_SERVICE to create an ordered balance group for a new service purchased by an existing account, if that service automatically belongs to a sharing group. By default, this opcode creates an ordered balance group for a service that is a member of a profile sharing group.

A newly purchased service belongs to a profile sharing group if its service type already belongs to a profile sharing group and the group is defined to include services added in the future.

PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_SERVICE is triggered when a new service is added to an existing account.

You can customize this opcode to use it with other types of sharing groups or to use it with only certain profile sharing groups.

PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_SERVICE is listed in the pin_notify file for /event/notification/service/create. When merging event notification files, this opcode should be listed after PCM_OP_TCF_PROV_CREATE_SVC_ORDER. See the discussion on merging event notification lists in BRM Developer's Guide

PCM_OP_SUBSCRIPTION_POL_AUTO_SUBSCRIBE_SERVICE is not called by any opcode.

Adding Profiles to a Profile Sharing Group

When adding profiles to a profile sharing group, PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY does the following:

1. Adds the /profile objects in the PIN_FLD_PROFILES array to the PROFILES array of the /group/sharing/profiles object.

2. Validates that the new group name is not a duplicate of an existing group name.

3. Creates an flist that includes the list of profiles to be added to the sharing group.

4. Generates an /event/group/sharing/profiles/modify event to record the changes.

Deleting Members and Profiles from a Profile Sharing Group

Note:

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

To delete a member or profile from a profile sharing group, your application calls PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY to list the members or profiles to be deleted. This opcode passes an empty array with an element ID for each listed object to be deleted.

Note:

If the array passed by the opcode is not empty, you are either adding or modifying the member or profile.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_MODIFY then calls PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE.

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

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

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

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

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

1. Deletes the /profile objects specified in the PIN_FLD_PROFILES array from the PROFILES array of the /group/sharing/profiles object.

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

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

Changing the Owner of a Profile Sharing Group

To change the owner of an existing profile sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT.

This opcode takes the following fields as input:

• PIN_FLD_GROUP_OBJ: The profile sharing group (/group/sharing/profiles) 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 profile sharing group. The /service object can be in the account that currently owns the profile 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 profile sharing group from one service to another in the same account, the object passed in this field matches the one in the PIN_FLD_POID field.

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

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

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 profile sharing group owner.

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

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

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

3. Adds the list of profile instances of the new parent passed in the input flist to the group object.

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

5. Adds the new owner's shared profiles to the /group/sharing/profiles object.

6. Generates an /event/group/sharing/profiles/modify event to record the owner change.

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

PCM_OP_SUBSCRIPTION_SHARING_GROUP_SET_PARENT fails if the new owner that is passed is already a member of the profile sharing group.

Deleting a Profile Sharing Group

To delete a profile sharing group, use PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE.

If the member and profiles arrays are empty in the input flist, the opcode assumes you are deleting the group.

PCM_OP_SUBSCRIPTION_SHARING_GROUP_DELETE does the following:

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

2. Deletes the group/sharing/profiles object.

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

Using Access Control Lists

See the following topics:

• Managing ACL Groups

• Accessing /group/acl Data

Managing ACL Groups

BRM stores information about each ACL in /group/acl objects in the BRM database. You manage or access data in /group/acl objects by using the Permissioning facilities module (FM) standard opcodes.

You create, modify, and delete /group/acl objects by using PCM_OP_PERM_ACL* opcodes. These opcodes validate data in the input flist and then call Group FM standard opcodes to create, add, modify, or delete data in a /group/acl object. For example, PCM_OP_PERM_ACL_GROUP_ADD_MEMBER adds members to a /group/acl object by calling PCM_OP_GROUP_ADD_MEMBER.

To manage /group/acl objects, you use the following Permissioning FM standard opcodes:

• To create a /group/acl object, use PCM_OP_PERM_ACL_GROUP_CREATE.

• To add a member to a /group/acl object, use PCM_OP_PERM_ACL_GROUP_ADD_MEMBER.

• To delete a member from a /group/acl object, use PCM_OP_PERM_ACL_GROUP_DELETE_MEMBER.

• To modify the attributes in a /group/acl object, such as the ACL name, group account, or list of authorized service types, use PCM_OP_PERM_ACL_GROUP_MODIFY.

  Note:

  PCM_OP_PERM_ACL_GROUP_MODIFY overwrites the list of authorized services in the /group/acl object. When the PIN_FLD_PERMITTEDS array is included in the input flist, PCM_OP_PERM_ACL_GROUP_MODIFY deletes all services from the /group/acl object and adds the services from the input flist.

• To delete an entire /group/acl object, use PCM_OP_PERM_ACL_GROUP_DELETE.

  Note:

  Deleting an ACL does not affect services. It only removes the ACL.

Accessing /group/acl Data

Use the following opcodes to access data in /group/acl opcodes. Client applications typically use these opcodes to find all ACLs that a CSR belongs to or to determine which account group to display.

• To find all ACLs to which a CSR or member belongs, use PCM_OP_PERM_FIND. See "Finding CSR Membership".

• To determine which account group to display in a client application, use PCM_OP_PERM_GET_CREDENTIALS and PCM_OP_PERM_SET_CREDENTIALS.

Finding CSR Membership

Use PCM_OP_PERM_FIND to find all ACLs to which a CSR belongs. This opcode returns a list of all groups that a CSR is authorized to access, along with specific information about each ACL.

Customizing the Account Dump Utility (ADU)

Use the account dump policy opcodes to customize Account Dump Utility (ADU) validation and output file format. The Account Dump utility (ADU) is a diagnostics tool that enables you to validate account information before or after certain business processes (for example, after completion of a migration or upgrade or before billing or payment allocation).

Use PCM_OP_ADU_POL_DUMP to convert the ADU output format to a format other than XML. By default, PCM_OP_ADU_VALIDATE dumps account information in XML format. PCM_OP_ADU_POL_DUMP allows you to convert the account information in the input flist into a format other than XML (for example, CSV).

Use PCM_OP_ADU_POL_VALIDATE to define custom validations for validating account data. By default, PCM_OP_ADU_VALIDATE performs the predefined validations enabled in the ADU pin.conf file. PCM_OP_ADU_POL_VALIDATE allows you to define custom validations for validating the account information provided in the input flist.

Any custom validation you define must be associated with a validation code. For PCM_OP_ADU_VALIDATE to perform the custom validations, they must be configured and enabled in the ADU pin.conf.

Business Profile Opcode Workflows

See the following topics:

• Creating Business Profiles

• Assigning Bill Units to Business Profiles

• Getting Information about a Business Profile

Creating Business Profiles

Use PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE to create business profiles.

PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE creates one /associated_bus_profile object for each bill unit in an account.

If the BRM-BI Publisher invoice integration is enabled, during customer account creation, PCM_OP_CUST_CREATE_BILLINFO calls PCM_OP_CUST_CREATE_ASSOCIATED_BUS_PROFILE to create one /associated_bus_profile object for each bill unit in the account.

Assigning Bill Units to Business Profiles

You can assign a bill unit to a business profile (/config/business_profile object) during or after account creation.

To assign a bill unit to a business profile during account creation:

1. Call PCM_OP_CUST_COMMIT_CUSTOMER.

   In the opcode's input flist, specify the /config/business_profile object's POID in the PIN_FLD_BUSINESS_PROFILE_OBJ field of the appropriate BILLINFO array element.

2. PCM_OP_CUST_COMMIT_CUSTOMER passes the business profile information to an internal opcode.

3. BRM calls the following opcodes to validate the bill unit and its balance groups and services against the rules in the validation templates associated with the business profile:

   • PCM_OP_CUST_SET_BILLINFO, which validates the /billinfo object against the bill unit validation template (/config/template/billinfo object) and sets the /billinfo object's PIN_FLD_OBJECT_CACHE_TYPE value.

   • PCM_OP_CUST_SET_BAL_GRP, which validates the balance group objects against the balance group validation template (/config/template/balance_group object) and sets the /balance_group object's PIN_FLD_OBJECT_CACHE_TYPE value. When a service is associated with a balance group, this opcode also validates the service object against the service validation template that corresponds to the service object type (/config/template/service or /config/template/service/*) and sets the /service object's PIN_FLD_OBJECT_CACHE_TYPE value.

     Note:

     If the business profile is not associated with a validation template that matches a particular object type, validation is not performed on the corresponding object type. Skipping validation for this reason is not equivalent to validation failure and does not prevent the bill unit from being assigned to the business profile.

4. One of the following results occurs:

   • If no validation errors occur, BRM calls PCM_OP_CUST_SET_BILLINFO to put the business profile POID in the PIN_FLD_BUSINESS_PROFILE_OBJ field of the new /billinfo object.

   • If validation errors occur, account and bill unit creation fail.

Whenever invoice business profiles are modified in the /config/business_profile object, use PCM_OP_CUST_SET_ASSOCIATED_BUS_PROFILE to update all related /associated_bus_profile objects.

To assign a bill unit to a business profile after account creation, see "Changing a Bill Unit's Business Profile".

Changing a Bill Unit's Business Profile

Use PCM_OP_CUST_CHANGE_BUSINESS_PROFILE to perform these operations:

• Assign a bill unit to a business profile after an account has been created.

• Change the business profile of a bill unit that currently belongs to a different business profile.

Include the following information in PCM_OP_CUST_CHANGE_BUSINESS_PROFILE input flist:

• The POID of the /billinfo object whose business profile you want to change.

• The POID of the new /config/business_profile object to assign the /billinfo object to.

• The POID of any associated /balance_group objects that must be modified for the new business profile and the required modifications.

• The POID of any associated /service/* objects that must be modified for the new business profile and the required modifications.

PCM_OP_CUST_CHANGE_BUSINESS_PROFILE performs these operations:

1. Validates the /billinfo object against the bill unit validation template (/config/template/billinfo object) associated with the new business profile and then does one of the following:

   If validation succeeds:

   1. Calls PCM_OP_CUST_SET_BILLINFO to change the /config/business_profile POID in the PIN_FLD_BUSINESS_PROFILE_OBJ field of the /billinfo object.

   2. If cache residency distinction is enabled, changes the /account object's PIN_FLD_OBJECT_CACHE_TYPE value if required, then validates all cache residency objects that are related to the account and are in the account context (for example, /profile/acct_extrating objects and account /purchased_product objects).

   If validation fails, returns an error.

2. Creates a list of all the objects associated with the bill unit.

3. For each balance group in the list, checks whether the input flist contains a requested modification.

   If a modification is requested, calls PCM_OP_CUST_SET_BAL_GRP to make the modifications and to validate the modified balance group object against the balance group validation template (/config/template/balance_group object) associated with the new business profile.

   If a modification is not requested, validates the balance group itself.

4. After validating a balance group, creates a list of all the services associated with the balance group.

5. If cache residency distinction is enabled, searches for objects related to each service in the list and validates them (for example, /purchased_discount and /profile/serv_extrating objects that belong to the account).

6. For each service in the list, checks whether the input flist contains a requested modification.

   If a modification is requested, calls PCM_OP_CUST_MODIFY_SERVICE to make the modifications and to validate the modified service object against the service validation template that most closely corresponds to the service object type (/config/template/service or /config/template/service/* object) associated with the new business profile.

   If a modification is not requested, validates the service itself.

7. Repeats steps 3 through 6 until all balance groups and services associated with the bill unit are validated.

   If any of the balance group or service validations fail, returns an error. If an error is returned, the business profile change initiated in step 1 does not take effect.

   Note:

   If the business profile is not associated with a validation template that matches a particular object type, validation is not performed on the corresponding object type. Skipping validation for this reason is not equivalent to validation failure and does not prevent the bill unit from being assigned to the business profile.

Getting Information about a Business Profile

A business profile (/config/business_profile object) and the validation templates (/config/template subclass objects) linked to it include key-value pairs in their PIN_FLD_PAIR arrays. To get information about the objects belonging to a business profile, you can retrieve the values of the keys in the business profile and its associated validation templates. For example, if a bill unit belongs to a business profile that has a PIN_FLD_PAIR_KEY field set to IsPrepaidGold and a corresponding PIN_FLD_PAIR_VALUE field set to Yes, you know that the charges associated with the bill unit are prepaid with a gold credit card.

To get the value of a key in the business profile and validation templates associated with an object, call PCM_OP_CUST_GET_BUSINESS_PROFILE_INFO. Include the following information in the opcode's input flist:

• The POID of the /config/business_profile object to which the related object belongs. These are the possible related objects:

  • /balance_group

  • /billinfo

  • /group/sharing/charges

  • /group/sharing/discounts

  • /group/sharing/profiles

  • /ordered_balgrp

  • /profile/acct_extrating

  • /profile/serv_extrating

  • /purchased_discount

  • /purchased_product

  • /service/*

• The key whose value you want the opcode to get.

• The type of object from which the key's value should be obtained. These are the possible object types:

  • /config/business_profile

  • /config/template/balance_group

  • /config/template/billinfo

  • /config/template/group

  • /config/template/sharing

  • /config/template/ordered_balgrp

  • /config/template/profile/*

  • /config/template/purchased_discount

  • /config/template/purchased_product

  • /config/template/service/*

Creating and Managing Account Hierachies

To create and manage account hierarchies, BRM uses the following PCM_OP_BILL_GROUP_* opcodes:

Note:

These opcodes call other PCM_OP_GROUP_* opcodes to perform functionality. Your custom client application should not call the PCM_OP_GROUP_* opcodes.

• PCM_OP_BILL_GROUP_CREATE

  See "Creating Account Hierarchies".

• PCM_OP_BILL_GROUP_ADD_MEMBER

  See "Adding Accounts to Account Hierarchies".

• PCM_OP_BILL_GROUP_MOVE_MEMBER

  See "Moving Accounts from One Account Hierarchy to Another".

• PCM_OP_BILL_GROUP_DELETE_MEMBER

  See "Deleting Accounts from Account Hierarchies".

• PCM_OP_BILL_GROUP_DELETE

  See "Deleting Account Hierarchies".

• PCM_OP_BILL_GROUP_GET_PARENT

  See "Finding the Parent of an Account Hierarchy".

• PCM_OP_BILL_GROUP_GET_CHILDREN

  See "Getting a List of Child Accounts in an Account Hierarchy".

Creating Account Hierarchies

To create an account hierarchy, BRM uses PCM_OP_BILL_GROUP_CREATE.

This opcode creates a /group object for the account hierarchy.

The input to PCM_OP_BILL_GROUP_CREATE is the following:

• The name of the /group object

• The parent /account object to own the group

PCM_OP_BILL_GROUP_CREATE calls PCM_OP_GROUP_CREATE_GROUP to create the group. The new group's POID is written to the PIN_FLD_GROUP_OBJ field in the specified /account object. The output of PCM_OP_GROUP_CREATE_GROUP is returned as the output of this call.

This operation is performed inside a transaction.

The PCM_OP_BILL_GROUP_CREATE output flist includes the following:

• 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 object that holds the old and new value of the parent object. Because an object was created and an old value did not exist, the old value is returned as NULL. The old and new parent values are kept in the EVENT_GROUP_PARENTS_T table, which is linked to the EVENT_T table.

If an error occurs, a NULL flist is returned.

Adding Accounts to Account Hierarchies

To add an account to an account hierarchy, BRM uses PCM_OP_BILL_GROUP_ADD_MEMBER.

The input to PCM_OP_BILL_GROUP_ADD_MEMBER includes the following:

• The /group object to add accounts to

• A set of POIDs of the accounts to add

Any account can be added to an account hierarchy, including the parent account of another account hierarchy.

Note:

Each child account can belong to only one parent account.

PCM_OP_BILL_GROUP_ADD_MEMBER calls PCM_OP_GROUP_ADD_MEMBER to add the accounts. After the accounts are successfully added, an /event object is created that contains a list of the added accounts. The POID of the new /event object is returned.

Only accounts not already in the group are added. If the list of accounts to add contains accounts already in the account group, they are ignored.

To be added to the group, an account's bill units must have the same bill time information (NEXT_BILL_T field in the /billinfo object) as the parent /billinfo object in the group's parent account.

PCM_OP_BILL_GROUP_ADD_MEMBER is performed inside a transaction.

The PCM_OP_BILL_GROUP_ADD_MEMBER output flist includes the following:

• 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 object that holds the list of accounts added to the group. The list of added accounts is kept in the EVENT_GROUP_MEMBERS_T table, which is linked to the EVENT_T table.

Moving Accounts from One Account Hierarchy to Another

To move an account from one account hierarchy to another, BRM uses PCM_OP_BILL_GROUP_MOVE_MEMBER.

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

When an account is moved, PCM_OP_BILL_GROUP_MOVE_MEMBER calls PCM_OP_BILL_GROUP_DELETE. If the account being moved is the last account in 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 PCM_OP_BILL_GROUP_MOVE_MEMBER input flist controls the type of information returned in the output flist. This field can have the following values:

• 1: If a bill unit of the account to be moved is a member of a collections sharing group, the opcode returns the details of the collections sharing group. When the flag is set to this value, the account is not moved.

• 2: If a bill unit of the account to be moved is a member of a collections sharing group, the opcode calls PCM_OP_COLLECTIONS_DELETE_GROUP_MEMBER to delete the bill unit from the collections sharing group and then continues moving the account to another account hierarchy.

If the account is moving into an existing account hierarchy, PCM_OP_BILL_GROUP_MOVE_MEMBER also calls PCM_OP_BILL_GROUP_ADD_MEMBER to add the account to the target group.

If the account is moving into a group that does not exist, PCM_OP_BILL_GROUP_MOVE_MEMBER calls PCM_OP_BILL_GROUP_CREATE to create the group.

If the target account (the top-level parent account of the nonexistent target group) also does not exist, PCM_OP_BILL_GROUP_MOVE_MEMBER attempts to remove the moving account from its group and leave it as a standalone account. If the moving account has a nonpaying bill unit, nothing is done, and an error is returned.

Deleting Accounts from Account Hierarchies

To delete an account from an account hierarchy, BRM uses PCM_OP_BILL_GROUP_DELETE_MEMBER.

PCM_OP_BILL_GROUP_DELETE_MEMBER calls PCM_OP_GROUP_DELETE_MEMBER to perform the deletion. After the accounts are successfully deleted from the group, an /event object is created that contains a list of the deleted accounts. The POID of the /event object is returned.

The list of accounts to delete can contain POIDs of accounts that are not in the account group; those accounts are ignored. Only accounts in the group are deleted from the account group.

You cannot delete an account if the bill unit it owns is a paying bill unit of a nonpaying bill unit in another account.

Deleting Account Hierarchies

To delete an account hierarchy, BRM uses PCM_OP_BILL_GROUP_DELETE.

This opcode performs the following actions:

• Deletes the specified /group object

• Deletes the accounts list for that account group

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

PCM_OP_BILL_GROUP_DELETE calls PCM_OP_GROUP_DELETE_GROUP. The input to PCM_OP_BILL_GROUP_DELETE is the POID of the group to delete. After successfully deleting the group, the opcode returns the deleted group's POID.

Finding the Parent of an Account Hierarchy

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

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

Getting a List of Child Accounts in an Account Hierarchy

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

To read only specified /account fields for each account (for example, account name), pass the specified fields in the input flist along with the POID of the /group object. If the input flist contains only the /group object POID, all the fields in the ACCOUNT table for each child are returned.

About the PCM_OP_GROUP Opcodes

The Group FM includes the following opcodes. These opcodes are called by other opcodes (for example, the wrapper opcode PCM_OP_BILL_GROUP_CREATE calls PCM_OP_GROUP_CREATE_GROUP to create a group). Always use the wrapper opcodes, such as the PCM_OP_BILL wrapper opcodes, not the PCM_OP_GROUP opcodes.

• PCM_OP_GROUP_CREATE_GROUP

  See "Creating Groups".

• PCM_OP_GROUP_ADD_MEMBER

  See "Adding Members to Groups".

• PCM_OP_GROUP_DELETE_MEMBER

  See "Deleting Members from Groups".

• PCM_OP_GROUP_SET_PARENT

  See "Setting a Group Parent".

• PCM_OP_GROUP_DELETE_GROUP

  See "Deleting Groups".

• PCM_OP_GROUP_UPDATE_INHERITED

  See "Updating Inheritance Fields in Groups".

Creating Groups

To create a /group object, BRM uses PCM_OP_GROUP_CREATE_GROUP.

PCM_OP_GROUP_CREATE_GROUP first initializes the new group. Then this opcode uses PCM_OP_GROUP_SET_PARENT to set any parent information specified on input. If a members list is passed in, PCM_OP_GROUP_ADD_MEMBER is called to add those members.

PCM_OP_GROUP_CREATE_GROUP does not generate an /event object. However, if new members are specified and added to the group, that operation generates 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 Groups

To add members to a group, BRM uses PCM_OP_GROUP_ADD_MEMBER.

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

The add members list might contain POIDs of members already in the group. Those members are ignored; only new members are added to the group.

Deleting Members from Groups

To delete members from a group, BRM uses PCM_OP_GROUP_DELETE_MEMBER.

After the members are deleted, an /event object is created containing a list of the deleted members. The POID of the /event object is returned.

The delete members list might contain POIDs of members not in the group. Those elements are ignored; only existing members are deleted from the group.

Setting a Group Parent

To set the parent object of a group, BRM uses PCM_OP_GROUP_SET_PARENT.

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 object that owns the group. If the group represents accounts, the members elements refer to accounts that belong to the group.

The results array returns the POID of an /event object that holds the old and new value of the parent object.

Deleting Groups

To delete a /group object, BRM uses PCM_OP_GROUP_DELETE_GROUP.

PCM_OP_GROUP_DELETE_GROUP removes a specified /group object and all members linked to it.

Updating Inheritance Fields in Groups

To update the inheritance fields of a group, BRM uses PCM_OP_GROUP_UPDATE_INHERITED.

The input to PCM_OP_GROUP_UPDATE_INHERITED is the POID of the group to update followed by the inheritance information. The inheritance information is passed as a substructure and must have space allocated for it as a separate object, independent of the /group object.